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 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. Select your Tools (configs/*.yaml): Open your target configuration file in the configs/ directory (e.g., example-config.yaml) and set true for any tool you wish to enable. By default, the docker-compose.yml points to example-config.yaml.

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 server.py entrypoint. See mcp-config.json for a ready-to-use snippet.

---

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

Unlike legacy setups requiring you to register a server per tool out of 235 options, Pentester-MCP now uses a Unified Server Architecture.

1. Define which tools you want available by editing a configuration file in configs/ (e.g., example-config.yaml).
2. Add the single Unified Server to your Claude/Cursor configuration.

Claude Desktop Example

Simply copy the contents of mcp-config.json into your claude_desktop_config.json file. It will look exactly like this:

{
  "mcpServers": {
    "pentester_mcp": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "pentester-mcp",
        "/app/.venv/bin/python",
        "/app/server.py"
      ]
    }
  }
}

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.