Pentester MCP

<h1 align="center">Pentester-MCP</h1> <p align="center"> <strong>Empower your AI assistants with the ultimate open-source penetration testing arsenal.</strong> </p> <p align="center"> <img alt="Tools" src="https://img.shields.io/badge/Tools-235%2B-blue"> <img alt="Python" src="https://img.shields.io/badge/Python-3.10%2B-blue"> <img alt="FastMCP" src="https://img.shields.io/badge/Powered%20By-FastMCP-orange"> <img alt="Docker" src="https://img.shields.io/badge/Integration-Docker-cyan"> </p>

---

Overview

Pentester-MCP provides Model Context Protocol (MCP) integration for over 200+ of the most popular open-source cybersecurity and penetration testing tools.

By adding Pentester-MCP to an AI assistant (like Claude Desktop, Cursor, or specialized agents), the AI gains the autonomous ability to act as a senior penetration tester:

• It can run nmap scans, analyze open ports, and automatically decide to run ffuf on discovered web servers.
• It can execute sqlmap against parameters it identifies as vulnerable.
• It understands tool arguments, required flags, and syntaxes thanks to AI-optimized documentation strings injected into every MCP tool.

All 235 Python *_mcp.py tools were generated intelligently from cheat sheets to ensure safe execution (e.g., preventing shell injection, enforcing timeouts, and handling huge terminal outputs).

The Arsenal

The tools/ directory includes MCP servers for almost every category:

• Reconnaissance: nmap, masscan, recon-ng, amass, subfinder, nuclei
• Web Exploitation: sqlmap, commix, ffuf, gobuster, dirsearch, nikto
• Active Directory & Network: impacket (full suite), bloodhound, responder, evil-winrm
• Brute-Forcing & Password: hydra, medusa, john, hashcat, nxc
• And 200+ more covering WiFi, Cloud, Kubernetes, Android, and reversing.

---

Installation & Usage

Because of the massive amount of tools, installing everything on your host machine can be messy. Therefore, Pentester-MCP offers two primary ways to run: Local Execution and Docker Sandbox (Recommended).

Method A: Docker Sandbox (Recommended & Secure)

Running tools via Docker isolates the execution from your host operating system and avoids polluting your system with hundreds of dependencies.

1. Clone the repository:

   git clone https://github.com/halilkirazkaya/pentester-mcp.git
   cd pentester-mcp
   

2. Customize your Dockerfile (Optional): You can open and edit the Dockerfile to add any specific pentesting tools you need using apt-get before building the image in the next step.

3. Build and Run the Sandbox:

   docker compose up -d --build
   

   Your container is now running silently in the background.

4. Add to your AI Client: Open your MCP client's configuration (e.g., claude_desktop_config.json) and route the commands directly to the running Docker container using docker exec. See the configs/ directory for ready-to-use JSON files based on the tools you need.

---

Method B: Local Execution (Fastest Setup)

If you already have Kali Linux, Parrot OS, or you specifically only want to use the tools already installed on your host system:

1. Clone and Setup Virtual Environment:

   git clone https://github.com/halilkirazkaya/pentester-mcp.git
   cd pentester-mcp
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

2. Add to your AI Client: Direct the AI client to execute the specific tool using your local python environment. You will need to extract the tool definitions from the configs/ directory and replace the "docker exec -i pentester-mcp /app/.venv/bin/python" arguments with your host machine's python path.

   Note: If the tool binary (e.g., nmap or gobuster) is not installed on your host system, the AI will gracefully receive a FileNotFoundError and inform you.

---

🔧 Configuring MCP Clients (Claude, Cursor, etc.)

To give your AI access to a tool, you must define it in the client's configuration file. Because exposing all 235 tools at once might exceed some AI context limits or confuse the model, we provide categorized configurations inside the configs/ directory:

• configs/ad-config.json: Tools for Active Directory (Impacket, Bloodhound, Kerbrute, etc.)
• configs/web-config.json: Tools for Web Pentesting (SQLMap, FFUF, Gobuster, Nikto, etc.)
• configs/recon-config.json: Reconnaissance & Discovery (Nmap, Amass, DNS tools, etc.)
• configs/exploit-config.json: Exploitation frameworks (Metasploit, Sliver, Pwncat, etc.)
• configs/pwd-config.json: Password breaking (Hashcat, John the Ripper, Hydra, etc.)
• configs/misc-config.json: General utilities (Curl, Docker, Git, etc.)
• configs/full-config.json: All 235 tools combined. Use with caution!

Claude Desktop Example (Using Web Tools)

Simply copy the contents of configs/web-config.json into your claude_desktop_config.json file. It will look like this:

{
  "mcpServers": {
    "sqlmap_mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pentester-mcp",
        "/app/.venv/bin/python",
        "/app/tools/sqlmap_mcp.py"
      ]
    },
    "ffuf_mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pentester-mcp",
        "/app/.venv/bin/python",
        "/app/tools/ffuf_mcp.py"
      ]
    }
    // ... other web tools
  }
}

WARNING: The configs use docker exec -i pentester-mcp which targets the running Docker container named pentester-mcp. Ensure the container is running via docker compose up -d before using the AI assistant.

---

Contributing & Architecture

The Python scripts in the tools/ directory are auto-generated from YAML cheat sheets to guarantee consistent API design (proper timeouts, truncating outputs to >8000 chars, no shell=True vulnerabilities).

If you have a request for a new tool to be added, please feel free to open an issue.

---

Disclaimer

Legal Disclaimer: This project is created strictly for educational purposes, authorized auditing, and ethical hacking. The developers of Pentester-MCP assume no liability and are not responsible for any misuse or damage caused by this software. Never use these tools against environments you do not own or do not have explicit, written permission to test.