pentestMCP
pentestMCP: AI-Powered Penetration Testing via MCP, an MCP designed for penetration testers.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/ramkansal--pentestmcp)HTML
<a href="/listings/ramkansal--pentestmcp"><img src="/api/listings/ramkansal--pentestmcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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 ```
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 233 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- [](https://mseep.ai/app/ram001-code-pentestmcp)
- # 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
- 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`
- [](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).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.