PentestMCP

This is an MCP server developed as part of a 2-month summer internship. This tool gives Large Language Models the ability to use active directory penetration testing tools. The goal is to save time, have the model analyze the result for you, decide the next step and the next tool/technique to use, but most importantly (for me and for the lazy red teamers out there at least) is that it documents findings for you.

🎯 Overview

The server provides a unified interface to tools like NetExec (CrackMapExec), Bloodhound, john, certipy and Nmap. This is an initial version that provides decent features but will always accept more tools so if you're looking for something that is able to compromise an active directory environment from 0 to 100 that's not it and I dont think that it'll be possible without human in the loop. The MCP server was tested locally with Claude Desktop as the MCP client. It's important to note that I used Claude Desktop for Debian (I used stdio as the transport layer). For installation instructions, see: https://github.com/aaddrick/claude-desktop-debian. For now only stdio transport layer is implemented and explained below, to use HTTP/SSE it's suggested that you download the repo, change the mcp.run() function in server.py to implement HTTP/SSE and change the mcp configuration file to fetch the target ip and port

🛠️ Requirements

The MCP server was developed using the amazing FastMCP: https://github.com/jlowin/fastmcp

Core Dependencies

• Python 3.10+ with UV package manager
• NetExec (successor to CrackMapExec)
• Bloodhound Community Edition
• Nmap
• Certipy
• psudohash https://github.com/t3l3machus/psudohash for password list generation ( included in the package, you dont have to download it )
• john

📦 Installation

1. Install the MCP server

Using PIP

pip install pentestmcp

By cloning the repo

git clone https://github.com/YoussefSahnoun/PentestMCP.git
cd PentestMCP
pip install -e .

2. Install Required Tools

NetExec

# Via pipx (recommended)
pipx install netexec

# Or via pip
pip install netexec

Bloodhound Community Edition

# Download from official releases
wget https://github.com/SpecterOps/BloodHound/releases/latest/bloodhound-linux-x64.zip
unzip bloodhound-linux-x64.zip
# Follow BloodHound setup instructions

Nmap

# Ubuntu/Debian
sudo apt install nmap

# CentOS/RHEL
sudo yum install nmap

Certipy

pip install certipy-ad

John

https://github.com/openwall/john/blob/bleeding-jumbo/doc/INSTALL

3. Configure MCP Client

For Claude Desktop

Add to your ~/.config/claude-desktop/config.json:

{
  "mcpServers": {
    "pentestmcp": {
      "command": "uv",
      "args": ["run", "pentestmcp"]
    }
  }
}

For Other MCP Clients

Configure according to your client's documentation, pointing to pentestmcp as the command.

🚀 Usage Examples

Before you run your MCP client:

1. Start bloodhound
2. Visit ~/.local/lib/python3.13/site-packages/pentestmcp/config/ (typical path on linux) to your configure config.json (bloodhound api creds, prject directory to save findings in, etc.)

   {
    "PROJECT_DIRECTORY": "add_absolute_path_for_your_project_directory",
    "BHE_DOMAIN": "127.0.0.1",
    "BHE_PORT": 8080,
    "BHE_TOKEN_ID": "",
    "BHE_TOKEN_KEY": ""
    }
   

Example Workflow

1. Start with Network Discovery

"Scan the network 192.168.1.0/24 for SMB services and check signing status"

2. Enumerate Users

"Find all users in the domain at 192.168.1.10"

3. Credential Attacks

"Try password spraying with common passwords against the discovered users"

4. Bloodhound Analysis

"Collect Bloodhound data ingest it, upload zip to bloodhound and find attack paths to Domain Admins"

🔧 Available Tools

🗺️ Nmap (Network Reconnaissance)

• run_nmap_scan: Network and service discovery with customizable flags

⚡ NetExec (SMB/LDAP Operations)

SMB Enumeration & Authentication:

• check_SMB_signing: Check SMB signing configuration
• enumerate_domain_users: Discover Active Directory users
• bruteforce_rid_users: RID cycling for user enumeration
• password_spray: Multi-target password attacks

Kerberos Attacks:

• ASREPRoast: Extract AS-REP hashes for offline cracking
• kerberoast: Extract TGS tickets for service accounts

Post-Exploitation:

• spider_smb_shares: Comprehensive share enumeration and file collection
• dump_ntds_dit: Extract domain credential database (NTDS.dit)
• dump_sam_hashes: Local account hash extraction
• command_execution: Remote PowerShell command execution

Bloodhound Data Collection:

• bloodhound_ingest: Collect AD data using NetExec's BloodHound module

Module System:

• check_module: List available NetExec modules for protocols (SMB, LDAP, WinRM, etc.)
• check_options: View module-specific options and parameters
• use_module: Execute NetExec modules with custom options

🩸 Bloodhound (Attack Path Analysis)

• test_bloodhound_connection: Verify API connectivity and version
• upload_zip_to_bloodhound: Import collected data into Bloodhound
• list_saved_queries: View saved Cypher queries
• run_bloodhound_query: Execute custom Cypher queries for attack path discovery

🔓 John the Ripper (Hash Cracking)

• get_john_formats: List available hash formats for cracking
• john_the_ripper: Crack hashes with specified format and wordlist

🏛️ Certipy (Certificate Services)

• certipy_scan: Enumerate AD CS vulnerabilities and misconfigurations

📝 Utility & Data Management

• save_partial_finding: Organize and store assessment results
• get_project_directory_files: View files in current project directory
• read_files: Access collected data and configuration files
• generate_pwd_wordlist: Create custom password wordlists based on target information

🔧 Available Resources

• Custom Bloodhound Queries: Some custom bloodhound queries that you can include as a resource to your MCP client. Note that you can add any resources you want just follow this resource:

@mcp.resource("data://bloodhound_cypher_queries")
def get_custom_queries():
    # Resolve path relative to this script (safer than relying on current working dir)
    p = Path(__file__).parent / "custom_bloodhound_queries.json"

    # use 'encoding' (not 'encode') and json.load for file -> python object (if  your data isn't json load it normally)
    with p.open("r", encoding="utf-8") as f:
        return json.load(f)

🔒 Security Considerations

Responsible Use

• This tool is intended for authorized security assessments only
• Ensure proper authorization before testing any systems
• Follow responsible disclosure practices for discovered vulnerabilities

Troubleshooting

Common Issues

Clock Skew Errors:

# Sync time with domain controller (requires root)
sudo ntpdate domain-controller.local

Permission Errors:

• Ensure NetExec has appropriate permissions
• Check that output directories are writable
• Verify Bloodhound API credentials

## 🤝 Contributing

### Adding New Tools


1. Create a new tool function following the MCP pattern
2. Add appropriate input validation
3. Update documentation and examples