Skip to content

MCP_SETUP_GUIDE.md

Latest commit

 

History

History
272 lines (205 loc) · 6.25 KB

MCP_SETUP_GUIDE.md

File metadata and controls

272 lines (205 loc) · 6.25 KB

Pentest-MCP - Complete Setup & Usage Guide

Overview

The Pentest-MCP server provides autonomous penetration testing capabilities through the Model Context Protocol (MCP). It includes network reconnaissance, web application testing, and vulnerability exploitation tools optimized for AI agents.

🚀 Quick Start

1. Start the MCP Server

cd Pentest-MCP
docker-compose up -d

Verify it's running:

docker ps | grep kali-mcp
# Should show: kali-mcp running on port 8000

2. Configure Your MCP Client

For Claude Desktop

Add 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"],
      "timeout": 600
    }
  }
}

Restart Claude Desktop completely (not just reload).

For Cline (VS Code Extension)

Add to ~/.cline/data/settings/cline_mcp_settings.json:

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

Restart Cline extension.

For Zed Editor

Add to your project's .zed/settings.json:

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

🛠️ Available Tools

Web Application Testing

web_recon

Purpose: Complete web application reconnaissance

Arguments:

  • target_url (required): Target URL to scan
  • depth (optional): Scan depth - "quick", "standard", or "deep"

Returns:

  • Detected frameworks (AngularJS, React, Vue, WordPress)
  • Parameters (GET/POST/form inputs)
  • JavaScript files and secrets
  • Attack surface analysis with prioritized vectors

Example:

{
  "name": "web_recon",
  "arguments": {
    "target_url": "https://example.com",
    "depth": "quick"
  }
}

web_exploit

Purpose: Test for web vulnerabilities

Arguments:

  • target_url (required): Target URL
  • attack_types (optional): Array of ["xss", "sqli", "template"]
  • recon_data (optional): Previous reconnaissance results

Capabilities:

  • XSS (Reflected/Stored/DOM)
  • AngularJS sandbox escape
  • CSP bypass techniques
  • SQL injection detection
  • Template injection (CSTI/SSTI)

Network Testing

recon_target

Purpose: Network reconnaissance and port scanning

Arguments:

  • target (required): IP address or hostname
  • passive_only (optional): Boolean for passive-only scanning

Returns: Open ports, running services, OS detection, attack surface map

pentest_target

Purpose: Full penetration test workflow

Arguments:

  • target (required): Target IP/hostname
  • scope (optional): Array of in-scope targets

Returns: Complete pentest report with all phases

Manual Tools

run_command_sync

Execute commands directly in Kali container:

{
  "name": "run_command_sync",
  "arguments": {
    "command": "nmap -sV example.com"
  }
}

⚠️ WARNING: This tool is stateless. Multi-step web interactions requiring session/cookies will fail. Use a Python script with requests.Session() for stateful workflows.

start_job & check_job_status

For long-running background tasks.

📝 Usage Examples

Example 1: AngularJS XSS Lab

Objective: Detect AngularJS and test for XSS with sandbox escape

Use kali-mcp web_recon to analyze https://your-lab.web-security-academy.net/

Expected Output:

{
  "frameworks_detected": ["AngularJS"],
  "parameters_discovered": [{"name": "search", "type": "GET"}],
  "attack_surface": [{
    "type": "Client-Side Template Injection (CSTI)",
    "priority": "CRITICAL",
    "payloads": ["{{constructor.constructor('alert(document.cookie)')()}}"]
  }]
}

Example 2: Network Reconnaissance

Use kali-mcp recon_target to scan 10.10.10.50

Example 3: Chained Recon + Exploit

First use kali-mcp web_recon on https://target.com, 
then use web_exploit to test all vulnerabilities found

🔧 Troubleshooting

Error: "server name kali-mcp not found"

Fix: Completely restart your MCP client (Claude/Cline), don't just reload.

Error: Container not running

docker-compose up -d
docker logs kali-mcp  # Check for errors

Test MCP Server Manually

echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | \
  docker exec -i kali-mcp python3 /app/stdio_bridge.py

Expected:

{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", ...}}

🎯 Payloads Reference

AngularJS XSS (Sandbox Escape)

Working Payloads:

{{constructor.constructor('alert(document.cookie)')()}}
{{constructor.constructor('alert(1)')()}}
{{$on.constructor('alert(1)')()}}

SQL Injection Test Payloads

'
' OR '1'='1
1' AND 1=1--
' UNION SELECT NULL--

🔐 Security Notes

  1. Only use on authorized targets - This is a penetration testing tool
  2. Container is privileged - Has NET_ADMIN capabilities for network testing
  3. Credentials - No hardcoded credentials; uses parameter-based testing
  4. Logging - All actions logged to Docker logs

📊 Tool Coverage

Category Coverage
Web XSS ✅ Reflected, Stored, DOM, AngularJS
Web SQLi ✅ Error-based detection
Web Template Injection ✅ CSTI (AngularJS), SSTI
Network Recon ✅ Port scanning, service enum
Network Exploit 🔄 Coming soon (Metasploit)
Binary Pwn 📋 Planned
Forensics 📋 Planned
Crypto 📋 Planned

Last Updated: 2026-01-13
Version: 1.3
Status: Production Ready ✅