🐉 Kali MCP Server - Web Penetration Testing

A Model Context Protocol (MCP) server built on Kali Linux Docker container, providing AI-assisted web penetration testing tools with proper input sanitization and formatted output.

---

🚀 Features

Security Tools Included

Tool	Purpose	Category
Nmap	Port scanning, service detection, OS fingerprinting	Network
Nikto	Web server vulnerability scanning	Web Vuln
SQLMap	SQL injection testing	Web Vuln
WPScan	WordPress security assessment	CMS
DIRB	Directory brute-forcing	Discovery
Gobuster	Fast directory/DNS/vhost enumeration	Discovery
FFUF	Web fuzzing	Discovery
SearchSploit	Exploit database search	Research
SSLScan	SSL/TLS analysis	Crypto
WhatWeb	Web technology identification	Recon
WAFW00F	WAF detection	Recon
Nuclei	Template-based vulnerability scanning	Web Vuln

Key Features

• ✅ Non-root execution with proper network capabilities
• ✅ Input sanitization to prevent command injection
• ✅ Formatted output for easy reading
• ✅ Async execution for non-blocking operations
• ✅ Output persistence for report generation
• ✅ Rate limiting to prevent abuse
• ✅ Docker isolation for security

---

📦 Installation

Prerequisites

• Docker Engine 20.10+
• Docker Compose v2.0+
• 4GB RAM minimum (8GB recommended)
• 10GB disk space

Quick Start

# Clone or download the project
cd kali-mcp-server

# Build the Docker image
docker-compose build

# Start the server
docker-compose up -d

# Check logs
docker-compose logs -f

# Verify it's running
curl http://localhost:8010/health

Build Only

docker build -t kali-mcp-server:latest .

Run Manually

docker run -d \
  --name kali-mcp \
  --cap-add NET_RAW \
  --cap-add NET_ADMIN \
  -p 8010:8010 \
  -v kali-outputs:/app/outputs \
  kali-mcp-server:latest

---

🔧 Configuration

Environment Variables

Variable	Default	Description
MCP_HOST	0.0.0.0	Server bind address
MCP_PORT	8010	Server port
DEBUG	false	Enable debug logging
DEFAULT_TIMEOUT	300	Default tool timeout (seconds)
MAX_TIMEOUT	3600	Maximum allowed timeout
WPSCAN_API_TOKEN	-	WPScan vulnerability database API token

Claude Desktop Integration

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "kali-pentest": {
      "url": "http://localhost:8010/sse"
    }
  }
}

Or for Docker execution:

{
  "mcpServers": {
    "kali-pentest": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--cap-add=NET_RAW",
        "--cap-add=NET_ADMIN",
        "-p", "8010:8010",
        "kali-mcp-server:latest"
      ]
    }
  }
}

---

🛠️ Available Tools

1. Network Scanning

nmap_scan

nmap_scan(
    target="192.168.1.1",           # IP, hostname, or CIDR
    ports="80,443,8080",            # Port specification
    scan_type="version",            # default, syn, connect, udp, version, aggressive, vuln
    scripts="http-enum,ssl-enum",   # NSE scripts
    timing=3,                       # 0-5 (paranoid to insane)
    timeout=600
)

2. Web Vulnerability Scanning

nikto_scan

nikto_scan(
    target="http://example.com",
    port=80,
    ssl=False,
    tuning="123bde",    # Test categories
    timeout=600
)

sqlmap_scan

sqlmap_scan(
    target_url="http://example.com/page?id=1",
    data="username=admin",          # POST data
    parameter="id",                 # Specific param to test
    level=3,                        # 1-5
    risk=2,                         # 1-3
    technique="BEUST",              # Injection techniques
    dbms="mysql",                   # Target DBMS
    tables=True,                    # Enumerate tables
    timeout=600
)

wpscan_scan

wpscan_scan(
    target="http://wordpress-site.com",
    enumerate="vp,vt,u",            # plugins, themes, users
    plugins_detection="aggressive",
    api_token="your_token"
)

3. Directory Discovery

dirb_scan

dirb_scan(
    target="http://example.com",
    wordlist="big",                 # common, big, small
    extensions="php,html,txt",
    recursive=True,
    timeout=600
)

gobuster_scan

gobuster_scan(
    target="http://example.com",
    mode="dir",                     # dir, dns, vhost
    wordlist="medium",
    extensions="php,html",
    threads=40,
    timeout=600
)

ffuf_fuzz

ffuf_fuzz(
    target="http://example.com/FUZZ",
    wordlist="common",
    method="GET",
    headers="X-Custom:value",
    filter_code="404,500",
    threads=50
)

4. Information Gathering

whatweb_scan

whatweb_scan(
    target="http://example.com",
    aggression=3                    # 1-4
)

wafw00f_detect

wafw00f_detect(
    target="http://example.com",
    list_all=True
)

sslscan_scan

sslscan_scan(
    target="example.com",
    port=443,
    show_certs=True
)

5. Exploit Research

searchsploit_search

searchsploit_search(
    search_term="apache 2.4.49",
    exact_match=False,
    exclude="dos,windows"
)

6. Vulnerability Scanning

nuclei_scan

nuclei_scan(
    target="http://example.com",
    templates="cves,vulnerabilities",
    severity="high,critical",
    tags="rce,sqli",
    rate_limit=150
)

---

🔒 Security Considerations

Input Sanitization

All inputs are validated and sanitized:

• Targets: Validated as IP, CIDR, hostname, or URL
• Ports: Validated format, range checks
• Parameters: Regex filtering, dangerous character removal
• Paths: Allowed directory whitelist

Dangerous Patterns Blocked

; | & ` $ ( ) { } > < || && ../ %00 \n \r

Non-Root Execution

The container runs as pentester user (UID 1000) with limited capabilities:

cap_add:
  - NET_RAW           # Required for SYN scans
  - NET_ADMIN         # Network configuration
  - NET_BIND_SERVICE  # Bind to low ports

---

📋 Web Pentest Workflow

Recommended Scanning Order

1. Reconnaissance
   ├── whatweb_scan          # Identify technologies
   ├── wafw00f_detect        # Check for WAF
   └── nmap_scan (ports)     # Open ports/services

2. Discovery
   ├── gobuster_scan (dir)   # Directory enumeration
   ├── gobuster_scan (dns)   # Subdomain enumeration
   └── ffuf_fuzz             # Parameter fuzzing

3. Vulnerability Assessment
   ├── nikto_scan            # General web vulnerabilities
   ├── nuclei_scan           # Template-based scanning
   ├── sslscan_scan          # SSL/TLS issues
   └── wpscan_scan           # If WordPress detected

4. Targeted Testing
   ├── sqlmap_scan           # SQL injection
   └── searchsploit_search   # Find exploits

5. Reporting
   └── Review /app/outputs   # All scan results saved

---

📁 Project Structure

kali-mcp-server/
├── Dockerfile              # Kali Linux container setup
├── docker-compose.yml      # Orchestration
├── requirements.txt        # Python dependencies
├── README.md              # This file
├── src/
│   ├── __init__.py
│   ├── main.py            # FastMCP server & tools
│   ├── validators.py      # Input sanitization
│   ├── formatters.py      # Output formatting
│   └── config.py          # Settings management
├── config/
│   └── claude_desktop_config.json
├── scripts/               # Helper scripts
└── wordlists/            # Custom wordlists

---

🐛 Troubleshooting

Container Won't Start

# Check logs
docker-compose logs kali-mcp

# Verify capabilities
docker run --rm --cap-add NET_RAW kali-mcp-server nmap --version

Scans Timing Out

# Increase timeout
docker-compose exec kali-mcp env DEFAULT_TIMEOUT=900

# Or pass timeout parameter
nmap_scan(target="...", timeout=900)

Permission Denied

# Ensure proper capabilities
docker run --cap-add NET_RAW --cap-add NET_ADMIN ...

Tool Not Found

# Enter container and verify
docker-compose exec kali-mcp which nmap nikto sqlmap

---

📜 License

MIT License - Use responsibly and only on authorized systems.

---

⚠️ Legal Disclaimer

This tool is for authorized security testing only. Unauthorized access to computer systems is illegal. Always:

1. Get written permission before testing
2. Define scope clearly
3. Document all activities
4. Report findings responsibly

The authors assume no liability for misuse of this tool.

---

🤝 Contributing

1. Fork the repository
2. Create feature branch
3. Add tests for new tools
4. Submit pull request

---

📞 Support

For issues and feature requests, open a GitHub issue with:

• Environment details
• Steps to reproduce
• Expected vs actual behavior
• Relevant logs