π‘οΈ 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
| Feature | Description |
|---|---|
| **3 Scan Modes** | Quick (5-10 min), Medium (15-30 min), Extensive (45+ min) β each with distinct depth and AI analysis |
| **30+ Security Tools** | nmap, sqlmap, nuclei, ffuf, dalfox, nikto, wafw00f, subfinder, sslyze, and more |
| **AI-Powered Analysis** | Groq LLM (Llama 3.1 70B) performs vulnerability triage, CVSS scoring, and generates executive reports |
| **Claude Desktop Native** | Runs as an MCP server β talk to it in natural language, reports render directly in chat |
| **Session Management** | Track, pause, and resume security assessments across multiple targets |
| **OWASP Top 10 Coverage** | Systematic scanning mapped to OWASP 2021 categories |
| **Smart Fallbacks** | If a professional tool isn't installed, Python-native implementations fill the gap |
## π Table of Contents
- [Quick Start](#-quick-start)
- [Scan Modes](#-scan-modes)
- [Supported Tools](#-supported-tools)
- [Usage Examples](#-usage-examples)
- [Project Structure](#-project-structure)
- [Configuration](#-configuration)
- [Troubleshooting](#-troubleshooting)
- [Security Notice](#-security-notice)
- [License](#-license)
## π Quick Start
### Prerequisites
- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/)** (Python package manager)
- **[Groq API Key](https://console.groq.com/keys)** (free tier available)
- **Claude Desktop** (for the MCP integration)
### 1. Clone & Install
```bash
git clone https://github.com/yourusername/MCPToolForWebVulnerabilities
cd MCPToolForWebVulnerabilities
# Install dependencies
uv sync
```
### 2. Configure Environment
```bash
cp .env.example .env
```
Edit `.env` and add your Groq API key:
```env
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:
```bash
# 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`:
```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.
| Test | Tool |
|---|---|
| WAF Detection | wafw00f / custom |
| DNS Enumeration | dnsrecon / custom |
| Port Scan (top 20) | nmap / custom |
| Header Analysis | custom |
| TLS/SSL Audit | sslyze / custom |
| Tech Fingerprinting | whatweb / custom |
| Sensitive File Discovery | ffuf / custom |
### Medium Mode (15-30 minutes)
Standard penetration test covering OWASP Top 10.
| Test | Tool |
|---|---|
| Everything in Quick | β |
| Port Scan (top 100) | nmap |
| XSS Scanning | dalfox / custom |
| SQL Injection | sqlmap |
| Directory Discovery | ffuf / gobuster |
| CORS Misconfiguration | corscanner / custom |
| Path Traversal | custom |
| Open Redirect | custom |
| CSRF Checks | custom |
### Extensive Mode (45+ minutes)
Board-level comprehensive security assessment.
| Test | Tool |
|---|---|
| Everything in Medium | β |
| Port Scan (top 1000) | nmap / masscan |
| Subdomain Enumeration | subfinder / amass |
| Advanced Fuzzing | wfuzz / ffuf |
| SSRF Probing | custom |
| Secret Scanning | trufflehog |
| Git Exposure | git-dumper |
| JWT Analysis | jwt_tool |
| GraphQL Security | graphql-cop |
| Command Injection | commix |
## π§ 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.
Full Tool List (click to expand)
| Tool | Category | Required |
|---|---|---|
| nmap | Port scanning | Optional (has fallback) |
| sqlmap | SQL injection | Optional |
| ffuf | Fuzzing / file discovery | Optional (has fallback) |
| nuclei | Vulnerability scanning | Optional |
| dalfox | XSS scanning | Optional |
| subfinder | Subdomain discovery | Optional |
| wafw00f | WAF detection | Optional (has fallback) |
| sslyze | TLS/SSL audit | Optional (has fallback) |
| nikto | Web server scanning | Optional |
| gobuster | Directory brute-forcing | Optional |
| whatweb | Tech fingerprinting | Optional (has fallback) |
| wfuzz | Advanced fuzzing | Optional |
| arjun | Hidden parameter discovery | Optional |
| testssl | SSL/TLS testing | Optional |
| masscan | Fast port scanning | Optional |
| amass | OSINT / subdomain enum | Optional |
| dnsrecon | DNS enumeration | Optional (has fallback) |
| theHarvester | Email/domain OSINT | Optional |
| retire.js | JS library CVE scanning | Optional |
| trufflehog | Secret detection | Optional |
| git-dumper | Git repo exposure | Optional |
| commix | Command injection | Optional |
| corscanner | CORS misconfiguration | Optional (has fallback) |
| jwt_tool | JWT analysis | Optional |
| graphql-cop | GraphQL security | Optional |
| xsstrike | Advanced XSS | Optional |
| hydra | Brute-forcing | Optional |
| shodan | Internet intelligence | Optional |
| enum4linux-ng | SMB enumeration | Optional |
## π¬ Usage Examples
See [`CLAUDE_PROMPTS.md`](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
| Variable | Description | Default |
|---|---|---|
| `GROQ_API_KEY` | Your Groq API key | Required |
| `GROQ_MODEL` | LLM model for analysis | `llama-3.1-70b-versatile` |
| `GROQ_MAX_TOKENS` | Max response tokens | `8192` |
| `GROQ_TEMPERATURE` | LLM temperature | `0.2` |
| `SESSION_DIR` | Session storage path | `~/.pentest-mcp/sessions` |
| `LOG_LEVEL` | Logging verbosity | `INFO` |
### 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
```bash
# 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 `/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](https://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](LICENSE) for details.
---
Built with π Python Β· π€ MCP Protocol Β· π§ Groq AI Β· π‘οΈ OWASP Standards