Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ramkansal--pentestmcp/badge.svg)](/listings/ramkansal--pentestmcp)

HTML

<a href="/listings/ramkansal--pentestmcp"><img src="/api/listings/ramkansal--pentestmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/ram001-code-pentestmcp-badge.png)](https://mseep.ai/app/ram001-code-pentestmcp)
  2. # pentestMCP: AI-Powered Penetration Testing via MCP
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. <!-- Example badges (replace placeholders/add relevant ones) -->
  5. <!-- [![Build Status](https://img.shields.io/travis/com/Ram001-code/pentestMCP.svg?style=flat-square)](https://travis-ci.com/Ram001-code/pentestMCP) -->
  6. <!-- [![GitHub issues](https://img.shields.io/github/issues/Ram001-code/pentestMCP?style=flat-square)](https://github.com/Ram001-code/pentestMCP/issues) -->
  7. <!-- [![GitHub forks](https://img.shields.io/github/forks/Ram001-code/pentestMCP?style=flat-square)](https://github.com/Ram001-code/pentestMCP/network) -->
  8. <!-- [![GitHub stars](https://img.shields.io/github/stars/Ram001-code/pentestMCP?style=flat-square)](https://github.com/Ram001-code/pentestMCP/stargazers) -->
  9. **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.**
  10. 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).
  11. ---
  12. ## Table of Contents
  13. - [Core Concepts & Architecture](#core-concepts--architecture)
  14. - [Key Features](#key-features)
  15. - [Prerequisites](#prerequisites)
  16. - [Installation & Setup](#installation--setup)
  17. - [Using Pre-built Docker Image (Recommended)](#using-pre-built-docker-image-recommended)
  18. - [Building Docker Image Locally](#building-docker-image-locally)
  19. - [Client Host Integration](#client-host-integration)
  20. - [Claude Desktop Integration](#claude-desktop-integration)
  21. - [VS Code Copilot Chat Integration](#vs-code-copilot-chat-integration)
  22. - [Tool Reference](#tool-reference)
  23. - [Security Considerations](#security-considerations)
  24. - [Contributing](#contributing)
  25. - [License](#license)
  26. - [Disclaimer](#disclaimer)
  27. - [Acknowledgements](#acknowledgements)
  28. ---
  29. ## Video Demo
  30. https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6
  31. ## Core Concepts & Architecture
  32. 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:
  33. 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.
  34. 2. **LLM**: Receives user prompts and tool definitions (from pentestMCP via the Client Host). It decides which tools to invoke based on the context.
  35. 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.
  36. 4. **External Tools**: The actual command-line utilities encapsulated within the Docker image.
  37. The server is built using the Python MCP SDK (`mcp.server.fastmcp.FastMCP`) and features:
  38. * **Tool Discovery:** Utilizes Python type hints and docstrings for automatic MCP tool schema generation.
  39. * **Concurrency Control:** A `threading.Semaphore` limits simultaneous execution of resource-intensive scans.
  40. * **Asynchronous Scan Pattern:** Implements launch/fetch methods for long-running tasks (Nmap, Nuclei, SQLMap, Gobuster) to avoid blocking the MCP connection.
  41. ```mermaid
  42. sequenceDiagram
  43. participant User
  44. participant ClientHost as Client Host (Claude, VS Code)
  45. participant LLM
  46. participant PentestMCP as pentestMCP Server (Docker via stdio)
  47. participant ExtTool as External Tool (e.g., Nmap)
  48. User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org"
  49. ClientHost->>PentestMCP: tools/list Request
  50. PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan')
  51. ClientHost->>LLM: User Prompt + Available Tools Description
  52. LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV'
  53. ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...})
  54. Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally
  55. PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output)
  56. ClientHost->>LLM: Tool Execution Result
  57. LLM-->>ClientHost: Formulate Final Response
  58. ClientHost-->>User: "Nmap scan launched/completed. Results..."
  59. ```
  60. ## Key Features
  61. * **Comprehensive Toolset:** Integrates over 20 essential penetration testing tools via MCP.
  62. * **Standardized Access:** Enables any MCP client supporting `stdio` server launching to utilize complex pentesting workflows.
  63. * **Non-Blocking Scans:** Efficiently handles long-running scans without locking up the interaction flow.
  64. * **Resource Management:** Implements basic concurrency limiting for scans.
  65. * **Portable & Reproducible:** Dockerized environment ensures all dependencies and tools are available consistently across platforms (Windows, macOS, Linux).
  66. * **Web Scanner Integration:** Provides direct control over OWASP ZAP Active Scan and AJAX Spider functionalities.
  67. ## Prerequisites
  68. * **Docker:** Requires Docker Desktop (Windows/macOS) or Docker Engine (Linux) to be installed and running. Ensure the Docker daemon is active.
  69. * **Git:** Needed only if building the image locally (`git clone` step).
  70. * **(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).
  71. ## Installation & Setup
  72. We recommend using the pre-built Docker image for the fastest and most reliable setup.
  73. ### 🐳 Using Pre-built Docker Image (Recommended)
  74. Using the pre-built image avoids local build times and ensures all tools (like gofang, nmap, and nuclei) are correctly installed without dependency issues.
  75. 1. **Pull the image from Docker Hub:**
  76. ```bash
  77. docker pull ramgameer/pentest-mcp:latest
  78. ```
  79. > ℹ️ **Note:** Depending on your environment, you may need to authenticate or ensure the Docker daemon is running.
  80. ---
  81. ### 🛠️ Building Docker Image Locally
  82. > ⚠️ **IMPORTANT:** Building locally is currently most efficient and supported on **Linux** environments.
  83. 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.
  84. 1. **Clone the repository:**
  85. ```bash
  86. git clone https://github.com/ramkansal/pentestMCP.git
  87. cd pentestMCP
  88. ```
  89. 2. **Build the Docker image:**
  90. ```bash
  91. docker build -t pentest-mcp-server:custom .
  92. ```
  93. 3. **Install SecLists (Optional but highly recommended):**
  94. > 💡 **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.
  95. ```bash
  96. git clone https://github.com/danielmiessler/SecLists.git seclists
  97. ```
  98. ## Client Host Integration
  99. 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 ...`.
  100. ### Claude Desktop Integration
  101. 1. **Locate/Create Config File:**
  102. * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
  103. * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
  104. 2. **Edit Config:** Add/update the `mcpServers` section. Use the correct image name (`ramgameer/pentest-mcp:latest` or your custom tag) .
  105. ```json
  106. {
  107. "mcpServers": {
  108. "pentestMCP": {
  109. "command": "docker",
  110. "args": [
  111. "run",
  112. "--rm",
  113. "-i",
  114. "ramgameer/pentest-mcp:latest"
  115. ]
  116. }
  117. }
  118. }
  119. ```
  120. 3. **Restart Claude Desktop** fully.
  121. 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.
  122. 5. **Interact:** Ask Claude to use the tools (see examples in the draft).
  123. ### VS Code Copilot Chat Integration
  124. Integration requires configuring VS Code's settings to define the MCP server for Copilot Chat agents that support MCP.
  125. 1. **Install Prerequisite:** Ensure [Github Copilot extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and relevant GitHub Copilot extensions are installed.
  126. 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):
  127. ```json
  128. "pentest-mcp": {
  129. "type": "stdio",
  130. "command": "docker",
  131. "args": [
  132. "run",
  133. "-i",
  134. "--rm",
  135. "ramgameer/pentest-mcp:latest"
  136. ]
  137. }
  138. ```
  139. 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.
  140. 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.
  141. ## Tool Reference
  142. The server exposes a variety of tools categorized by function:
  143. * **Reconnaissance & Enumeration:**
  144. * `run_subfinder`: Discovers subdomains using ProjectDiscovery's Subfinder.
  145. * `launch_nmap_scan` / `fetch_nmap_results`: Executes Nmap network scans and retrieves results asynchronously.
  146. * `run_gobuster_scan` / `check_gobuster_status`: Performs directory/file/DNS bruteforcing with Gobuster asynchronously.
  147. * `launch_gofang_scan` / `fetch_gofang_results`: Runs gofang, an all-in-one web crawler with extraction superpowers.
  148. * `run_harvester` / `check_harvester_status`: Runs theHarvester asynchronously for OSINT gathering (emails, hosts, ips).
  149. * `run_dig_tool`: Executes DNS `dig` queries.
  150. * `fetch_whois_data`: Retrieves WHOIS information for a domain.
  151. * `run_curl_tool`: Executes cURL commands for HTTP interaction.
  152. * **Vulnerability Scanning:**
  153. * `launch_nuclei_scan` / `fetch_nuclei_results`: Runs template-based vulnerability scans with ProjectDiscovery's Nuclei asynchronously.
  154. * **Web Application Analysis:**
  155. * `launch_arjun_scan` / `fetch_arjun_results`: Locates hidden HTTP parameters using Arjun.
  156. * **Exploitation Support:**
  157. * `run_searchsploit`: Searches the local Exploit-DB database using Searchsploit.
  158. * `run_sqlmap_tool` / `check_sqlmap_status`: Executes SQLmap for SQL injection testing asynchronously.
  159. * **Active Directory Analysis (`ad_*` tools):**
  160. * **Enumeration:** `ad_user_enum`, `ad_shares_enum`, `ad_smb_signing_check`, `ad_certipy_enum`, `ad_ldap_dump`, `ad_bloodhound_collect`
  161. * **Attacks/Coercion:** `ad_asreproast`, `ad_kerberoast`, `ad_password_spray`, `ad_coerce_petitpotam`, `ad_coerce_printerbug`, `ad_responder_poison`, `ad_relay_setup`
  162. * **Credential/Domain Operations:** `ad_check_credentials`, `ad_secrets_dump`, `ad_dcsync`
  163. [![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)
  164. ## Security Considerations
  165. * **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.
  166. * **Target Authorization:** **CRITICAL:** Only use these tools against systems for which you have explicit, prior, written authorization. Unauthorized scanning is illegal and unethical.
  167. * **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.
  168. * **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.
  169. ## Contributing
  170. 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.
  171. ## License
  172. This project is distributed under the terms of the [MIT License](LICENSE).
  173. ## Disclaimer
  174. **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.**
  175. ## Acknowledgements
  176. 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 in

Free to use. If it’s helped, pass it on.