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

Start the containerized MCP server:
```
docker compose up -d --build
```
The integration uses a wrapper script (kali_mcp_wrapper.py) that connects Claude Desktop to the containerized server via STDIO transport.

Configure Claude Desktop:

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

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

Add tool function with @mcp.tool() decorator
Implement input sanitization
Use run_tool() helper for execution
Add proper error handling
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.