pentestMCP

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 91 Open GitHub ↗

pentestMCP: AI-Powered Penetration Testing via MCP, an MCP designed for penetration testers.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/ram001-code-pentestmcp-badge.png)](https://mseep.ai/app/ram001-code-pentestmcp)
# pentestMCP: AI-Powered Penetration Testing via MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

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:**
    ```bash
    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:**
    ```bash
    git clone https://github.com/ramkansal/pentestMCP.git
    cd pentestMCP
    ```

2. **Build the Docker image:**
    ```bash
    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.
    ```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.
    *   `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`

[![Star History Chart](https://api.star-history.com/chart?repos=RamKansal/pentestMCP&type=date&logscale&legend=top-left&sealed_token=BsVSedXnJUUNKyrXfRn2yjXYg4Irj8SCGkn4gF7hgnZ8FcObRwMaG6zQiQjfM6DrihT5rt_-lqJ4fYD9Bj6Wu6KpP4RIeQtFigLVl1_vv5ha5_H261A73XRfnppCGx2AogimvTRqFt2hN2ln935DCG3zRM-2d0Q9x7gzye-yPE4QrjazS7Wio9Txdq_k)](https://www.star-history.com/?repos=RamKansal%2FpentestMCP&type=date&logscale=&legend=top-left)

## 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).

pentestMCP

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README