Kali Linux MCP Server (Dockerized)

A dockerized Model Context Protocol (MCP) server that provides secure access to Kali Linux security tools for defensive security and authorized penetration testing.

Features

Network Scanning

• nmap_scan: Network discovery and port scanning
• gobuster_dir: Directory and file enumeration

Web Application Testing

• wpscan_scan: WordPress security scanning
• sqlmap_test: SQL injection testing
• dirb_scan: Web content discovery

System Enumeration

• enum4linux_scan: SMB/NetBIOS enumeration
• searchsploit_query: Exploit database search

Credential Testing

• crackmapexec_smb: SMB credential testing
• john_crack: Password cracking with John the Ripper
• hashcat_crack: GPU-accelerated password cracking

Utilities

• netcat_connect: Network connectivity testing
• bloodhound_py: Active Directory enumeration

Security Features

• Input Sanitization: All inputs are validated against strict patterns
• Network Restrictions: Configurable allowed target networks
• Non-root Execution: Runs with minimal privileges using Linux capabilities
• Timeout Protection: Commands have configurable execution limits
• Output Limiting: Response sizes are capped for safety

Docker Installation & Usage

Prerequisites

• Docker and Docker Compose installed
• Sufficient disk space for Kali Linux image

Quick Start

# Build and start the container (MCP server starts automatically)
docker compose up --build

# Or run in background
docker compose up -d --build

# The MCP server runs inside the container with STDIO transport
# Integration with Claude Desktop uses a wrapper script

Container Usage

# View server logs
docker compose logs -f kali-mcp-container

# Access the running container (for debugging/development)
docker compose exec kali-mcp-container bash

# The MCP server is already running automatically
# Check server status inside container:
# ps aux | grep python

Container Management

# Stop the container and MCP server
docker compose down

# View real-time server logs
docker compose logs -f kali-mcp-container

# Restart the container
docker compose restart

# Rebuild container (after code changes)
docker compose build --no-cache

# For development: override auto-start to get shell access
# Temporarily modify docker-compose.yml: command: /bin/bash

Claude Desktop Integration (Automatic)

# The MCP server uses STDIO transport for Claude Desktop
# Integration happens via the wrapper script

# Container starts automatically when you run:
docker compose up -d --build

# Check if container is running:
docker compose ps | grep kali-mcp-container

Configuration

Environment Variables

• MCP_HOST: Server host (default: 127.0.0.1)
• MCP_PORT: Server port (default: 8000)
• MCP_MAX_EXEC_TIME: Command timeout in seconds (default: 300)
• MCP_OUTPUT_LIMIT: Maximum output size in bytes (default: 10000)
• MCP_ALLOWED_NETWORKS: Comma-separated list of allowed target networks
• WPSCAN_API_TOKEN: Optional WPScan API token for vulnerability data

Network Restrictions

For production use, configure MCP_ALLOWED_NETWORKS to restrict scanning targets:

# Example: Only allow internal networks
MCP_ALLOWED_NETWORKS=192.168.0.0/16,10.0.0.0/8,172.16.0.0/12

Usage Examples (Inside Container)

Automatic Server Startup

# The MCP server starts automatically when you run:
docker compose up --build

# Server is available at localhost:8000
# No manual startup required!

# To verify server is running:
docker compose logs kali-mcp-container

Testing Tools Directly (Optional)

# Access container for direct tool testing
docker compose exec kali-mcp-container bash

# Inside container:
nmap --version
gobuster version
wpscan --version
ls /usr/share/wordlists/

MCP Tool Usage (via Claude Desktop)

Once connected to Claude Desktop, you can use tools like:

# Network scanning
nmap_scan("192.168.1.1", scan_type="basic")

# Directory enumeration
gobuster_dir("http://example.com")

# WordPress scanning
wpscan_scan("http://wordpress.example.com")

# SQL injection testing
sqlmap_test("http://example.com/page?id=1")

Claude Desktop Integration

Configuration Steps

1. Start the containerized MCP server:

   docker compose up -d --build
   

2. The integration uses a wrapper script (kali_mcp_wrapper.py) that connects Claude Desktop to the containerized server via STDIO transport.

3. Configure Claude Desktop:

   {
     "mcpServers": {
       "kali-security": {
         "command": "python3",
         "args": ["/home/pellax/Documents/myfirstclaudecode/kali_mcp_wrapper.py"]
       }
     }
   }
   

4. Restart Claude Desktop to load the configuration.

Container Features

• Automatic startup: MCP server starts when container boots
• Data persistence: ./data directory mounted from host
• Real-time logs: docker compose logs -f kali-mcp-container
• Environment configuration: All variables in docker-compose.yml
• Port mapping: localhost:8000 automatically mapped

Security Considerations

Authorized Use Only

This tool is designed for:

• Authorized penetration testing
• Security assessments
• Educational purposes
• Defensive security research

Network Security

• Configure network restrictions in production
• Use firewall rules to limit access
• Monitor tool usage and logs
• Implement proper authentication

User Permissions

• Run as dedicated service user (not root)
• Use Linux capabilities for network tools
• Restrict file system access
• Enable audit logging

Requirements

Host System

• Docker and Docker Compose
• 4GB+ free disk space for Kali image
• Network access for tool downloads

Container Environment

• Kali Linux rolling base image
• Python 3.8+ (included)
• All Kali security tools (pre-installed)
• Virtual environment with Python dependencies

Python Dependencies (Auto-installed in container)

• fastmcp >= 0.4.0
• pydantic >= 2.0.0
• Built-in Python modules (asyncio, subprocess, etc.)

Development

Project Structure

myfirstclaudecode/
├── kali_mcp_server/
│   ├── __init__.py
│   └── server.py              # Main server implementation
├── kali_mcp_wrapper.py        # Claude Desktop integration wrapper
├── Dockerfile                 # Container definition
├── docker-compose.yml         # Container orchestration
├── start_server.sh           # Container startup script
├── .dockerignore             # Docker build exclusions
├── claude_desktop_config.md  # Claude Desktop setup guide
├── demo_server.py           # Demo/testing server
├── requirements.txt        # Python dependencies
├── pyproject.toml         # Package configuration
├── data/                  # Persistent data directory
└── README.md             # This file

Wrapper Script Integration

The kali_mcp_wrapper.py script enables Claude Desktop integration by:

• Connecting to the running Docker container via docker exec
• Providing STDIO transport bridge between Claude Desktop and the containerized MCP server
• Automatically handling container communication and error reporting

Adding New Tools

1. Add tool function with @mcp.tool() decorator
2. Implement input sanitization
3. Use run_tool() helper for execution
4. Add proper error handling
5. Update documentation

License

MIT License - See LICENSE file for details

Disclaimer

This software is provided for educational and authorized testing purposes only. Users are responsible for complying with applicable laws and regulations. The authors are not responsible for misuse of this tool.