<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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   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:

```json
{
  "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.**