🐉 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.

!Security !Docker !MCP

---

🚀 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:

Get written permission before testing
Define scope clearly
Document all activities
Report findings responsibly

The authors assume no liability for misuse of this tool.

---

🤝 Contributing

Fork the repository
Create feature branch
Add tests for new tools
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

Kali MCP Server