Content
# pentestMCP: AI-Powered Penetration Testing via MCP
[](https://opensource.org/licenses/MIT)
<!-- Example badges (replace placeholders/add relevant ones) -->
<!-- [](https://travis-ci.com/Ram001-code/pentestMCP) -->
<!-- [](https://github.com/Ram001-code/pentestMCP/issues) -->
<!-- [](https://github.com/Ram001-code/pentestMCP/network) -->
<!-- [](https://github.com/Ram001-code/pentestMCP/stargazers) -->
**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](https://github.com/LaurieWired/)'s [GhidraMCP](https://github.com/LaurieWired/GhidraMCP).
---
## Table of Contents
- [Core Concepts & Architecture](#core-concepts--architecture)
- [Key Features](#key-features)
- [Prerequisites](#prerequisites)
- [Installation & Setup](#installation--setup)
- [Using Pre-built Docker Image (Recommended)](#using-pre-built-docker-image-recommended)
- [Building Docker Image Locally](#building-docker-image-locally)
- [Client Host Integration](#client-host-integration)
- [Claude Desktop Integration](#claude-desktop-integration)
- [VS Code Copilot Chat Integration](#vs-code-copilot-chat-integration)
- [Tool Reference](#tool-reference)
- [Security Considerations](#security-considerations)
- [Contributing](#contributing)
- [License](#license)
- [Disclaimer](#disclaimer)
- [Acknowledgements](#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.
```mermaid
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
The recommended way to use pentestMCP is via the pre-built Docker image.
### Using Pre-built Docker Image (Recommended)
This avoids local build times and dependency issues.
1. **Pull the image from Docker Hub:**
```bash
docker pull ramgameer/pentest-mcp:latest
```
*(This image name needs to exist on Docker Hub for this command to work)*
### Building Docker Image Locally
**(Before Installing, NOTE THAT THIS CODE WILL BE ONLY EFFICIENT IN LINUX ONLY)**
Use this option if you want to modify the code, use the absolute latest version, or the pre-built image is unavailable.
1. **Clone the repository:**
```bash
git clone https://github.com/Ram001-code/pentestMCP.git
cd pentestMCP
```
2. **Build the Docker image:**
```bash
docker build -t pentest-mcp-server:custom .
```
3. **NOTE: FOR SCANS THAT REQUIRE WORDLISTS, YOU MUST CLONE THE SECLISTS REPO AS FOLLOW**
```bash
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) .
```json
{
"mcpServers": {
"pentestMCP": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"ramgameer/pentest-mcp:latest"
]
}
}
}
```
3. **Restart Claude Desktop** fully.
4. **Verify:** Look for the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style="display: inline; margin: 0; height: 1.3em;" /> 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](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 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):
```json
"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.
* `run_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.
* `run_dig_tool`: Executes DNS `dig` queries.
* `fetch_whois_data`: Retrieves WHOIS information for a domain.
* `run_curl`: Executes cURL commands for HTTP interaction.
* **Vulnerability Scanning:**
* `launch_nuclei_scan`/`fetch_nuclei_results`: Runs template-based vulnerability scans with ProjectDiscovery's Nuclei asynchronously.
* `run_wpscan`: Performs WordPress vulnerability scans using WPScan.
* **Web Application Scanning (ZAP):**
* `run_zap_tool`: (Potentially a general ZAP command executor - verify implementation).
* `run_zap_active_scan`/`check_scan_status`/`active_scan_results`: Manages ZAP's active scanner.
* `run_ajax_spider`/`check_ajax_spider_status`/`get_ajax_spider_results`: Manages ZAP's AJAX Spider for SPAs.
* **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.
## 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](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](https://github.com/LaurieWired/)'s groundbreaking work on [GhidraMCP](https://github.com/LaurieWired/GhidraMCP).
