PentestMCP

PentestMCP provides a focused MCP server that unifies active directory pentesting tools, enabling a guided workflow where a language model can help you run tools, analyze results, decide next steps, and document findings. It is designed to work with a local client through a stdio transport layer, coordinating common AD assessment tools in a streamlined, repeatable process.

How to use

You operate this MCP server by connecting a compatible MCP client and triggering the pentest workflow. Start your client and point it at the local stdio configuration so you can run the server’s commands and receive structured results. Begin with network discovery and domain enumeration, then proceed to credential testing and data collection, letting the integrated tools ingest findings into a centralized report.

How to install

Prerequisites: you need Python 3.10+ with the UV package manager, and the following tooling to support common AD assessments.

Install the MCP server package

pip install pentestmcp

Install required external tools

NetExec (SMB/LDAP operations)

# 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, Certipy, and John the Ripper are used for discovery and credential analysis.

# Nmap on Debian/Ubuntu
sudo apt install nmap
# Certipy (Python package)
pip install certipy-ad
# John the Ripper may require a Jumbo build depending on your target formats

Configuration and startup

Configure your MCP client to connect to the local MCP server. The default setup uses a stdio transport and a command to run the server within your MCP client configuration.

Client configuration snippet for Claude Desktop (example):

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

Available tools

run_nmap_scan

Perform a network and service discovery scan with customizable flags to map live hosts and open ports.

check_SMB_signing

Assess SMB signing configuration to understand worst-case authentication exposure.

enumerate_domain_users

Enumerate Active Directory users from the domain to identify potential targets.

bruteforce_rid_users

RID cycling to enumerate additional user accounts by iterating RID values.

password_spray

Execute multi-target password spraying against discovered users to test credential resilience.

ASREPRoast

Extract AS-REP hashes for offline cracking from AS-Rep Roasting opportunities.

kerberoast

Extract TGS tickets for service account targets to pursue Kerberoasting.

spider_smb_shares

Enumerate SMB shares and collect files for data collection.

dump_ntds_dit

Extract the NTDS.dit credential database from domain controllers for offline analysis.

dump_sam_hashes

Extract local SAM hashes from accessible machines.

command_execution

Execute remote PowerShell commands or shell commands on compromised hosts.

bloodhound_ingest

Ingest collected AD data into BloodHound for attack path analysis.

check_module

List available NetExec modules for protocols like SMB, LDAP, or WinRM.

check_options

View options and parameters for a selected NetExec module.

use_module

Execute a NetExec module with customized options.

test_bloodhound_connection

Verify BloodHound API connectivity and version compatibility.

upload_zip_to_bloodhound

Import collected data as a ZIP into BloodHound for analysis.

list_saved_queries

Display saved Cypher queries in BloodHound for reuse.

run_bloodhound_query

Run a custom Cypher query to discover attack paths.

certipy_scan

Enumerate AD CS misconfigurations and vulnerabilities via Certipy.

save_partial_finding

Store intermediate assessment results in an organized manner.

get_project_directory_files

List files in the current project directory for quick access.

read_files

Read collected data and configuration files from the project.

generate_pwd_wordlist

Create tailored password wordlists from target information.