🐉 Pentest-MCP: Autonomous Penetration Testing Agent

A production-grade Model Context Protocol (MCP) server for autonomous penetration testing, featuring intelligent tool routing and the "Blood-Red" HexStrike AI engine.

---

� Table of Contents

• 🐉 Pentest-MCP: Autonomous Penetration Testing Agent
  • � Table of Contents
  • �🚀 Overview
  • ✨ Features
  • 🏗️ Architecture
  • 📋 Prerequisites
  • ⚙️ Installation
    • Step 1: Clone the Repository
    • Step 2: Understand the Docker Base Images
    • Step 3: Build and Start the Environment
    • Step 4: Verify Running Containers
  • 🔌 Connecting Your AI
    • Claude Desktop
    • Cline (VS Code Extension)
  • ⚡ Usage
    • Example Prompts
  • 📂 Project Structure
  • 🙏 Credits & Acknowledgements
  • ⚖️ License & Disclaimer
    • ⚠️ Legal Disclaimer

---

�🚀 Overview

This project provides a fully dockerized autonomous pentesting environment that exposes powerful security tools to AI agents (like Claude, Cline, or your own LLM) via the Model Context Protocol (MCP).

It integrates Kali Linux tools with HexStrike AI, a specialized offensive intelligence engine that manages 150+ tools, optimizing parameters and strategies in real-time.

---

✨ Features

Category	Capabilities
Autonomous Recon	Smart sub-domain enumeration, technology detection, attack surface mapping
Intelligent Exploitation	Auto-routing complex tasks (SQLi, XSS) to HexStrike for deep analysis
AngularJS Sandbox Escapes	Specialized payloads for modern web framework exploitation
Stateful Operations	Persistent sessions for multi-step exploits (Store-then-Deliver attacks)
Universal Bridge	Works with any MCP-compliant client (Claude Desktop, VS Code/Cline, Zed)
150+ Security Tools	Nmap, SQLMap, Nikto, Masscan, Gobuster, Hydra, and more via HexStrike

---

🏗️ Architecture

The system uses a Unified Gateway architecture:

┌─────────────────┐      ┌──────────────────┐      ┌────────────────────┐
│   AI Client     │ ───▶ │   kali-mcp       │ ───▶ │   hexstrike-mcp    │
│ (Claude/Cline)  │      │   (Gateway)      │      │   (150+ Tools)     │
└─────────────────┘      └──────────────────┘      └────────────────────┘
                                │
                                ▼
                      ┌──────────────────┐
                      │  Local Kali      │
                      │  Tools (Fallback)│
                      └──────────────────┘

1. AI Client sends request to kali-mcp.
2. ToolExecutor analyzes the request.
3. If complex (e.g., sqlmap) → Routes to HexStrike AI container.
4. If simple or HexStrike unavailable → Executes locally on Kali.

---

📋 Prerequisites

• Docker: v20.10+
• Docker Compose: v2.0+
• Python: 3.10+ (for local test scripts)
• Git: For cloning the repository

---

⚙️ Installation

Step 1: Clone the Repository

git clone https://github.com/Vasanthadithya-Mundrathi/Pentest-MCP.git
cd Pentest-MCP

Step 2: Understand the Docker Base Images

This project uses the following Docker images:

Container	Base Image	Purpose
kali-mcp	kalilinux/kali-rolling	MCP Server, core security tools
hexstrike-mcp	kalilinux/kali-rolling	HexStrike AI engine (150+ tools)

Note: The kalilinux/kali-rolling image is the official, minimal Kali Linux Docker image. It does not include a GUI. For more information, see the Official Kali Linux Docker Documentation.

Step 3: Build and Start the Environment

docker-compose up -d --build

This command builds both containers and starts them in the background.

Step 4: Verify Running Containers

docker ps

You should see two containers running:

• kali-mcp on port 8000
• hexstrike-mcp on port 8001 (internal: 8888)

---

🔌 Connecting Your AI

Claude Desktop

Add this to your claude_desktop_config.json:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kali-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "kali-mcp", "python3", "/app/stdio_bridge.py"]
    }
  }
}

Cline (VS Code Extension)

1. Open Cline Settings → MCP Servers tab.
2. Click "Edit MCP Settings".
3. Paste the configuration above.

For more details, see CONNECT_LOCALLY.md.

---

⚡ Usage

Once connected, your AI assistant has access to these tools:

Tool	Description
recon_target	Full network & web reconnaissance
web_exploit	Targeted XSS/SQLi/CSTI exploitation
run_command_sync	Quick shell commands (ls, whoami)
start_job / check_job_status	Long-running background scans

Example Prompts

"Use kali-mcp to scan example.com for vulnerabilities."
"Run web_recon on https://target.com and identify all parameters."
"Test https://target.com?search=test for XSS vulnerabilities."

For a complete guide, see MCP_SETUP_GUIDE.md.

---

📂 Project Structure

Pentest-MCP/
├── README.md               # You are here
├── MCP_SETUP_GUIDE.md      # Detailed usage guide
├── CONNECT_LOCALLY.md      # AI client connection instructions
├── docker-compose.yml      # Container orchestration
├── kali/                   # Kali MCP server source
│   ├── Dockerfile
│   ├── mcp_server.py       # FastAPI MCP server
│   ├── stdio_bridge.py     # MCP stdio protocol handler
│   └── skills/             # Autonomous skill modules
│       ├── recon_skill.py
│       ├── web_recon_skill.py
│       ├── web_exploitation_skill.py
│       └── tool_executor.py  # Intelligent routing
├── hexstrike/              # HexStrike AI integration
│   └── Dockerfile
├── docs/                   # Additional documentation
└── tests/                  # Test scripts and utilities

---

🙏 Credits & Acknowledgements

This project stands on the shoulders of giants:

• HexStrike AI by @0x4m4: The "Blood-Red" offensive intelligence engine providing 150+ integrated security modules.
• Kali Linux by Offensive Security: The industry-standard penetration testing distribution.
• Model Context Protocol (MCP): The open standard enabling AI-tool interoperability.
• PortSwigger Web Security Academy: For providing the labs used to test and validate exploitation payloads.

---

⚖️ License & Disclaimer

License: MIT License

⚠️ Legal Disclaimer

FOR EDUCATIONAL AND AUTHORIZED PENTESTING PURPOSES ONLY.

This tool is designed for security professionals, ethical hackers, and researchers. You are solely responsible for your actions. Use of this tool against targets without prior mutual consent is illegal. The authors assume absolutely no liability for misuse or any damages that may arise.

By using this software, you agree to:

1. Obtain proper authorization before testing any system.
2. Comply with all applicable local, state, national, and international laws.
3. Use this tool responsibly and ethically.

---

Built with ❤️ by Vasanthadithya