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

By cloning the repo

2. Install Required Tools

NetExec

Bloodhound Community Edition

Nmap

Certipy

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:

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

   { "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

2. Enumerate Users

3. Credential Attacks

4. Bloodhound Analysis

🔧 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:

🔒 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:

Permission Errors:

• Ensure NetExec has appropriate permissions

• Check that output directories are writable

• Verify Bloodhound API credentials