pentestMCP: AI-Powered Penetration Testing via MCP

pentestMCP provides a powerful bridge between Large Language Models (LLMs) and practical penetration testing tools through the Model Context Protocol (MCP). This project functions as an MCP Server, exposing a curated suite of over 20 standard security assessment utilities (Nmap, Nuclei, ZAP, SQLMap, etc.) as callable 'tools'. This allows AI agents within MCP-compatible clients (like Claude Desktop or specific VS Code setups) to leverage these utilities for automated and interactive security analysis tasks.

The goal is to enable natural language control over complex security workflows, making pentesting capabilities more accessible and integrated into AI-driven environments. This work is inspired by Laurie Kirk's GhidraMCP.

Table of Contents

• Core Concepts & Architecture
• Key Features
• Prerequisites
• Installation & Setup
  • Using Pre-built Docker Image (Recommended)
  • Building Docker Image Locally
• Client Host Integration
  • Claude Desktop Integration
  • VS Code Copilot Chat Integration
• Tool Reference
• Security Considerations
• Contributing
• License
• Disclaimer
• Acknowledgements

Video Demo

https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6

Core Concepts & Architecture

pentestMCP strictly adheres to the MCP specification, functioning solely as an MCP Server. It does not embed or directly communicate with any specific LLM. The interaction flow is mediated by an MCP Client Host application:

1. Client Host Application (e.g., Claude Desktop, custom agent): Connects to pentestMCP (typically via stdio brokered by Docker), manages user interaction, and interfaces with a chosen LLM.
2. LLM: Receives user prompts and tool definitions (from pentestMCP via the Client Host). It decides which tools to invoke based on the context.
3. pentestMCP Server (This Project): Runs within a Docker container. Listens for tools/call requests from the Client Host, executes the corresponding underlying tool (e.g., nmap), and returns the results.
4. External Tools: The actual command-line utilities encapsulated within the Docker image.

The server is built using the Python MCP SDK (mcp.server.fastmcp.FastMCP) and features:

• Tool Discovery: Utilizes Python type hints and docstrings for automatic MCP tool schema generation.
• Concurrency Control: A threading.Semaphore limits simultaneous execution of resource-intensive scans.
• Asynchronous Scan Pattern: Implements launch/fetch methods for long-running tasks (Nmap, Nuclei, SQLMap, Gobuster) to avoid blocking the MCP connection.

sequenceDiagram
    participant User
    participant ClientHost as Client Host (Claude, VS Code)
    participant LLM
    participant PentestMCP as pentestMCP Server (Docker via stdio)
    participant ExtTool as External Tool (e.g., Nmap)

    User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org"
    ClientHost->>PentestMCP: tools/list Request
    PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan')
    ClientHost->>LLM: User Prompt + Available Tools Description
    LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV'
    ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...})
    Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally
    PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output)
    ClientHost->>LLM: Tool Execution Result
    LLM-->>ClientHost: Formulate Final Response
    ClientHost-->>User: "Nmap scan launched/completed. Results..."

Key Features

• Comprehensive Toolset: Integrates over 20 essential penetration testing tools via MCP.
• Standardized Access: Enables any MCP client supporting stdio server launching to utilize complex pentesting workflows.
• Non-Blocking Scans: Efficiently handles long-running scans without locking up the interaction flow.
• Resource Management: Implements basic concurrency limiting for scans.
• Portable & Reproducible: Dockerized environment ensures all dependencies and tools are available consistently across platforms (Windows, macOS, Linux).
• Web Scanner Integration: Provides direct control over OWASP ZAP Active Scan and AJAX Spider functionalities.

Prerequisites

• Docker: Requires Docker Desktop (Windows/macOS) or Docker Engine (Linux) to be installed and running. Ensure the Docker daemon is active.
• Git: Needed only if building the image locally (git clone step).
• (Optional but Recommended) OWASP ZAP Instance: For using ZAP-related tools (run_zap_*, run_active_scan_*, run_ajax_*). This ZAP instance needs to be running and network-accessible from inside the pentestMCP Docker container (see Client Host Integration section for configuration).

Installation & Setup

We recommend using the pre-built Docker image for the fastest and most reliable setup.

🐳 Using Pre-built Docker Image (Recommended)

Using the pre-built image avoids local build times and ensures all tools (like gofang, nmap, and nuclei) are correctly installed without dependency issues.

1. Pull the image from Docker Hub:
   hljs language-bash

   Copy

   docker pull ramgameer/pentest-mcp:latest
   

   ℹ️ Note: Depending on your environment, you may need to authenticate or ensure the Docker daemon is running.

🛠️ Building Docker Image Locally

⚠️ IMPORTANT: Building locally is currently most efficient and supported on Linux environments.

If you wish to modify the server's code, use the absolute latest version, or the pre-built image is unavailable, you can build the Docker image locally.

1. Clone the repository:

   hljs language-bash

   Copy

   git clone https://github.com/ramkansal/pentestMCP.git
   cd pentestMCP
   

2. Build the Docker image:

   hljs language-bash

   Copy

   docker build -t pentest-mcp-server:custom .
   

3. Install SecLists (Optional but highly recommended):

   💡 Tip: Several tools (like Gobuster and Fuzzing utilities) rely on massive wordlists. You must clone the SecLists repo for these specific scans to function effectively.

   hljs language-bash

   Copy

   git clone https://github.com/danielmiessler/SecLists.git seclists
   

Client Host Integration

pentestMCP runs inside Docker and communicates with the Client Host via stdio. You configure your host (e.g., Claude Desktop, VS Code) to launch the server using docker run -i ....

Claude Desktop Integration

1. Locate/Create Config File:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edit Config: Add/update the mcpServers section. Use the correct image name (ramgameer/pentest-mcp:latest or your custom tag) .

   hljs language-json

   Copy

   {
     "mcpServers": {
       "pentestMCP": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "ramgameer/pentest-mcp:latest"
         ]
       }
     }
   }
   

3. Restart Claude Desktop fully.

4. Verify: Look for the icon. Clicking it should list the pentesting tools.

5. Interact: Ask Claude to use the tools (see examples in the draft).

VS Code Copilot Chat Integration

Integration requires configuring VS Code's settings to define the MCP server for Copilot Chat agents that support MCP.

1. Install Prerequisite: Ensure Github Copilot extension and relevant GitHub Copilot extensions are installed.

2. Configure VS Code Settings: Open your User or Workspace settings.json file (Command Palette: "Preferences: Open Settings (JSON)"). Add the MCP server configuration under the appropriate path (this path might change depending on the specific Copilot Chat agent implementation, check its documentation):

   hljs language-json

   Copy

   "pentest-mcp": {
       "type": "stdio",
       "command": "docker",
       "args": [
           "run",
           "-i",
           "--rm",
           "ramgameer/pentest-mcp:latest"
       ]
   }
   

3. Reload VS Code / Agent: Restart VS Code or use relevant commands to reload the Copilot agent's configuration for the changes to take effect. Consult the specific Copilot agent's documentation for details.

4. Interact: Use the Copilot Chat interface, potentially invoking tools via mentions if the agent supports it, or let the agent invoke them based on your prompts.

Tool Reference

The server exposes a variety of tools categorized by function:

• Reconnaissance & Enumeration:
  • run_subfinder: Discovers subdomains using ProjectDiscovery's Subfinder.
  • launch_nmap_scan / fetch_nmap_results: Executes Nmap network scans and retrieves results asynchronously.
  • run_gobuster_scan / check_gobuster_status: Performs directory/file/DNS bruteforcing with Gobuster asynchronously.
  • launch_gofang_scan / fetch_gofang_results: Runs gofang, an all-in-one web crawler with extraction superpowers.
  • run_harvester / check_harvester_status: Runs theHarvester asynchronously for OSINT gathering (emails, hosts, ips).
  • run_dig_tool: Executes DNS dig queries.
  • fetch_whois_data: Retrieves WHOIS information for a domain.
  • run_curl_tool: Executes cURL commands for HTTP interaction.
• Vulnerability Scanning:
  • launch_nuclei_scan / fetch_nuclei_results: Runs template-based vulnerability scans with ProjectDiscovery's Nuclei asynchronously.
• Web Application Analysis:
  • launch_arjun_scan / fetch_arjun_results: Locates hidden HTTP parameters using Arjun.
• Exploitation Support:
  • run_searchsploit: Searches the local Exploit-DB database using Searchsploit.
  • run_sqlmap_tool / check_sqlmap_status: Executes SQLmap for SQL injection testing asynchronously.
• Active Directory Analysis (ad_* tools):
  • Enumeration: ad_user_enum, ad_shares_enum, ad_smb_signing_check, ad_certipy_enum, ad_ldap_dump, ad_bloodhound_collect
  • Attacks/Coercion: ad_asreproast, ad_kerberoast, ad_password_spray, ad_coerce_petitpotam, ad_coerce_printerbug, ad_responder_poison, ad_relay_setup
  • Credential/Domain Operations: ad_check_credentials, ad_secrets_dump, ad_dcsync

Security Considerations

• Execution Permissions: Tools run as appuser within Docker, but Docker itself runs with host privileges. Be cautious with tools that modify files or require elevated system access.
• Target Authorization: CRITICAL: Only use these tools against systems for which you have explicit, prior, written authorization. Unauthorized scanning is illegal and unethical.
• Network Exposure: If mapping ZAP's port (-p 8888:8888), ensure your host firewall restricts access if the machine is on an untrusted network. The configured ZAP API key provides control over the instance.
• Input Validation: Although MCP provides structured input, the underlying tools might still be vulnerable to crafted arguments if not handled robustly within the Python wrapper functions.

Contributing

Contributions are highly encouraged! Fork the repository, create a feature branch, and submit a pull request. Please ensure adherence to ethical testing guidelines in all contributions. Bug reports and feature suggestions are welcome via GitHub Issues.

License

This project is distributed under the terms of the MIT License.

Disclaimer

This software is intended SOLELY for educational purposes and authorized, ethical security testing. Any use against systems without explicit permission is strictly prohibited and illegal. The authors and contributors assume NO liability for misuse or damage resulting from this program. Use at your own risk and ensure compliance with all applicable laws and agreements.

Acknowledgements

Profound inspiration for this project comes from Laurie Kirk's groundbreaking work on GhidraMCP.