🛡️ PenTest MCP Server

AI-Powered Penetration Testing via Model Context Protocol

An MCP server that integrates 30+ security tools with Groq LLM analysis,
designed to run natively inside Claude Desktop.

🏗️ Architecture

┌──────────────────────────────────────────────────────────┐
│                    CLAUDE DESKTOP (UI)                    │
│  User asks: "Run a medium scan on example.com"           │
└──────────────────┬───────────────────────────────────────┘
                   │ MCP Protocol (JSON-RPC over stdio)
                   ▼
┌──────────────────────────────────────────────────────────┐
│               PENTEST MCP SERVER (Python)                │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │   Session    │  │  Scan Mode   │  │   Tool         │  │
│  │   Manager    │  │  Orchestrator│  │   Registry     │  │
│  └─────────────┘  └──────┬───────┘  └────────────────┘  │
│                          │                               │
│         ┌────────────────┼────────────────┐              │
│         ▼                ▼                ▼              │
│  ┌────────────┐  ┌────────────┐  ┌────────────────┐     │
│  │   nmap     │  │   sqlmap   │  │   ffuf         │     │
│  │   nuclei   │  │   dalfox   │  │   nikto        │     │
│  │   sslyze   │  │   commix   │  │   gobuster     │     │
│  │   wafw00f  │  │   arjun    │  │   subfinder    │     │
│  │   ... 30+  │  │   ...      │  │   ...          │     │
│  └────────────┘  └────────────┘  └────────────────┘     │
│                          │                               │
│                          ▼                               │
│              ┌──────────────────────┐                    │
│              │    GROQ API          │                    │
│              │  (Llama 3.1 70B)    │                    │
│              │  Triage · Analysis  │                    │
│              │  CVSS · Reporting   │                    │
│              └──────────────────────┘                    │
└──────────────────────────────────────────────────────────┘

✨ Features

📋 Table of Contents

• Quick Start
• Scan Modes
• Supported Tools
• Usage Examples
• Project Structure
• Configuration
• Troubleshooting
• Security Notice
• License

🚀 Quick Start

Prerequisites

• Python 3.11+
• uv (Python package manager)
• Groq API Key (free tier available)
• Claude Desktop (for the MCP integration)

1. Clone & Install

git clone https://github.com/yourusername/MCPToolForWebVulnerabilities
cd MCPToolForWebVulnerabilities

# Install dependencies
uv sync

2. Configure Environment

cp .env.example .env

Edit .env and add your Groq API key:

GROQ_API_KEY=gsk_your_key_here

3. Install Security Tools (Optional)

The server works with Python-native fallbacks, but for professional-grade scanning, install the external tools:

# macOS (Homebrew)
brew install nmap sqlmap

# Install ffuf (Go-based fuzzer)
go install github.com/ffuf/ffuf/v2@latest

# Install nuclei (vulnerability scanner)
go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Install subfinder (subdomain discovery)
go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest

Tip: Run session_init to see which tools are detected on your system.

4. Connect to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pentest-mcp": {
      "command": "/FULL/PATH/TO/pentest-mcp/.venv/bin/python",
      "args": ["/FULL/PATH/TO/pentest-mcp/run_mcp_server.py"],
      "env": {
        "GROQ_API_KEY": "gsk_your_key_here"
      }
    }
  }
}

Replace /FULL/PATH/TO/pentest-mcp with your actual project path.

5. Restart Claude Desktop

Quit and reopen Claude Desktop. Look for the 🔌 icon showing pentest-mcp as connected.

6. Start Scanning!

Run a quick scan on https://example.com with consent confirmed

🎯 Scan Modes

Quick Mode (5-10 minutes)

Fast triage for immediate risk assessment.

Medium Mode (15-30 minutes)

Standard penetration test covering OWASP Top 10.

Extensive Mode (45+ minutes)

Board-level comprehensive security assessment.

🔧 Supported Tools

The server integrates 30+ security tools with automatic detection. If a tool isn't installed, Python-native fallbacks ensure the scan still runs.

💬 Usage Examples

See CLAUDE_PROMPTS.md for a full list of example prompts. Here are some highlights:

Unified Scanning

Run a quick triage scan on example.com. Generate a report and tell me the findings.
Perform an extensive scan on example.com including deep recon and directory fuzzing.

Individual Tools

What subdomains can you find for example.com? Run a discovery scan.
Run a port scan on example.com and fingerprint the web technologies.
Check for Cross-Site Scripting (XSS) on example.com/search.

AI Analysis

Analyze our current session findings. Are there any critical risks?
Generate a final markdown report for the current session.
Give me a CVSS 3.1 score for the SQLi vulnerability we just found.

📁 Project Structure

pentest-mcp/
├── run_mcp_server.py          # Entry point — launches MCP server
├── pentest_mcp/
│   ├── server.py              # MCP tool definitions & request handling
│   ├── scan_modes.py          # Quick/Medium/Extensive scan orchestration
│   ├── prompts.py             # Severity-specific Groq system prompts
│   ├── groq_client.py         # Groq API integration
│   ├── session.py             # Session state management
│   ├── models.py              # Pydantic data models
│   ├── config.py              # Environment & settings
│   ├── cli.py                 # CLI interface (alternative to MCP)
│   ├── risk_scorer.py         # Risk scoring engine
│   ├── command_chain.py       # Tool execution chaining
│   ├── tools/
│   │   ├── __init__.py        # Python-native security tools
│   │   └── professional.py    # External tool wrappers (nmap, sqlmap, etc.)
│   └── utils/
│       └── sanitizer.py       # Input validation & sanitization
├── tests/
│   └── test_session.py        # Session management tests
├── wordlists/                 # Fuzzing wordlists for ffuf/gobuster
├── reports/                   # Generated scan reports (Markdown)
├── CLAUDE_PROMPTS.md          # Example prompts for Claude Desktop
├── pyproject.toml             # Project dependencies & metadata
├── Makefile                   # Development shortcuts
├── install_tools.sh           # Security tool installer script
└── .env.example               # Environment variable template

⚙️ Configuration

Environment Variables

AI Analysis Pipeline

Each scan mode uses distinct Groq system prompts calibrated to the scan depth:

• Quick: Concise triage — focuses only on critical/high severity findings
• Medium: OWASP Top 10 analysis with balanced risk assessment and remediation
• Extensive: Board-level executive summary with exhaustive CVSS-scored findings, compliance mapping, and strategic recommendations

🔍 Troubleshooting

Server Not Connecting

# Check Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Verify the server starts manually
/path/to/pentest-mcp/.venv/bin/python /path/to/pentest-mcp/run_mcp_server.py

JSON Parse Errors in Logs

The MCP protocol uses stdout for JSON-RPC. If you see parse errors, ensure no libraries are logging to stdout. The server is pre-configured to redirect all logs to stderr.

Read-only file system Error

Reports are saved to <project_root>/reports/. Ensure the project directory is writable.

Groq API Errors

• Verify your API key: echo $GROQ_API_KEY
• Check rate limits at console.groq.com
• The server continues scanning even if Groq is unavailable — raw tool output is still returned

Tools Not Detected

Run session_init to see which tools are available. Install missing tools via Homebrew or your package manager. Python fallbacks cover core functionality even without external tools.

⚠️ Security Notice

This tool is for authorized security testing only.

• Always obtain explicit written permission before scanning any target
• Unauthorized testing violates the Computer Fraud and Abuse Act (CFAA), IT Act 2000/2008, and similar laws worldwide
• The consent_confirmed parameter exists as an ethical safeguard — never bypass it
• Never commit API keys to version control

📝 License

See LICENSE for details.

Built with 🐍 Python · 🤖 MCP Protocol · 🧠 Groq AI · 🛡️ OWASP Standards