Kali Linux MCP Server for Docker Desktop

An MCP (Model Context Protocol) server that provides AI assistants access to Kali Linux security tools through Docker containers.

Note: Docker Desktop's MCP Toolkit only displays servers from the official Docker Hub MCP Catalog. To use this custom server, you'll need to configure it manually using the MCP Gateway or direct client configuration. See DOCKER_DESKTOP_SETUP.md for detailed instructions.

Features

• Docker Desktop Native: Designed to work with Docker Desktop's MCP Toolkit
• Dynamic Tool Discovery: Automatically discovers and exposes Kali Linux tools
• 150+ Security Tools: Access to nmap, metasploit, burpsuite, and more
• Persistent Container: Kali container runs alongside the MCP server
• Auto-Installation: Installs kali-linux-everything on first run
• Tool Management: Install additional tools on-demand

Prerequisites

• Docker Desktop with MCP Toolkit support
• Docker Compose (included with Docker Desktop)
• At least 20GB free disk space for Kali tools (kali-linux-everything package)

Quick Start

Automated Installation (Recommended)

cd kali-mcp-docker-desktop
./setup.sh

This script automatically:

• ✅ Builds the Kali MCP server
• ✅ Starts the Kali Linux container
• ✅ Creates a custom catalog in Docker Desktop
• ✅ Adds and enables the Kali server
• ✅ Verifies the installation

👉 For detailed installation instructions, see INSTALLATION_GUIDE.md

Manual Installation

cd kali-mcp-docker-desktop

# Build the MCP server
docker-compose build

# Start the services
docker-compose up -d

# Add to Docker Desktop
docker mcp catalog create my-security-tools
docker mcp catalog add my-security-tools kali-linux-tools ./kali-catalog.yaml
docker mcp server enable kali-linux-tools

2. Verify Docker Desktop Integration

After running ./setup.sh, the Kali server is automatically added to Docker Desktop:

1. Open Docker Desktop
2. Go to MCP Toolkit in the sidebar
3. Look for Kali Linux Security Tools under "my-security-tools" catalog
4. The server should already be enabled

You can also verify from the command line:

docker mcp server ls
docker mcp catalog show my-security-tools

3. First Run (Tool Installation)

The first time the MCP server starts, it will:

1. Pull the Kali Linux Docker image
2. Install kali-linux-everything package (~15GB - ALL Kali tools)
3. Discover available tools

This takes 1-2 hours depending on your internet connection and system performance. Check logs with:

docker-compose logs -f kali-mcp-server

4. Use with AI Assistants

Once registered in Docker Desktop, AI assistants can use tools like:

Examples:

• kali_nmap - Scan networks with nmap
• kali_nikto - Scan web servers for vulnerabilities
• kali_sqlmap - Test for SQL injection
• kali_exec - Execute any Kali command
• kali_help - Get help for any tool
• kali_list_tools - List all available tools
• kali_install - Install additional tools

Available Tools

Meta Tools (Always Available)

• kali_list_tools - List available tools with optional filter
• kali_help - Get man page or help text for any tool
• kali_exec - Execute any command in Kali container
• kali_install - Install additional packages via apt-get

Security Tools (Auto-discovered)

The server discovers and exposes 150+ tools including:

Network Scanning:

• nmap, masscan, zmap, netdiscover, arp-scan

Web Security:

• nikto, burpsuite, zaproxy, wpscan, whatweb, sqlmap

Password Cracking:

• john, hashcat, hydra, medusa, ncrack

Exploitation:

• metasploit (msfconsole, msfvenom), beef-xss

Wireless:

• aircrack-ng

Reconnaissance:

• amass, subfinder, theharvester, recon-ng, dnsenum

Forensics:

• autopsy, volatility, binwalk, foremost

Reverse Engineering:

• radare2, ghidra, apktool, frida

And many more...

Configuration

Customize Tool Installation

The default installation uses kali-linux-everything (~15GB) which includes ALL Kali tools.

To use a smaller installation, edit the command in src/index.ts (around line 95):

// Current Default: All Kali tools (~15GB) - INSTALLED BY DEFAULT
"apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y kali-linux-everything man-db"

// Option 1: Top 10 tools only (~2GB) - Faster installation
"apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y kali-tools-top10 man-db"

// Option 2: Default Kali toolset (~5GB) - Balanced option
"apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y kali-linux-default man-db"

// Option 3: Specific categories only
"apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y kali-tools-web kali-tools-passwords man-db"

After editing, rebuild: docker-compose build && docker-compose up -d

Kali Tool Categories

• kali-tools-information-gathering - Reconnaissance tools
• kali-tools-vulnerability - Vulnerability scanners
• kali-tools-web - Web application testing
• kali-tools-passwords - Password cracking
• kali-tools-wireless - Wireless security
• kali-tools-exploitation - Exploitation frameworks
• kali-tools-forensics - Digital forensics
• kali-tools-reverse-engineering - Reverse engineering

Usage Examples

Example 1: Network Scanning

AI: Use kali_nmap to scan 192.168.1.0/24 with args "-sV -p 1-1000"

Example 2: Web Vulnerability Scanning

AI: Use kali_nikto to scan http://testsite.local with args "-h http://testsite.local"

Example 3: SQL Injection Testing

AI: Use kali_sqlmap with args "-u 'http://testsite.local/page.php?id=1' --batch"

Example 4: Custom Command

AI: Use kali_exec with command "nmap -sV -sC 192.168.1.1 -oA scan_results"

Example 5: Get Tool Help

AI: Use kali_help with tool "metasploit"

Example 6: Install Additional Tools

AI: Use kali_install with packages "metasploit-framework bloodhound"

Docker Desktop MCP Toolkit Integration

How It Works

1. Discovery: Docker Desktop scans running containers for MCP labels
2. Registration: Containers with com.docker.desktop.mcp.server=true are registered
3. Communication: AI assistants communicate via stdio with the MCP server
4. Execution: MCP server executes commands in the Kali container via Docker socket

Architecture

Docker Desktop MCP Toolkit
    ↓ (discovers via labels)
kali-mcp-server container
    ↓ (Docker socket: /var/run/docker.sock)
kali-tools-container (Kali Linux)
    ↓ (executes commands)
Security Tools (nmap, metasploit, etc.)

Management

View Logs

# MCP server logs
docker-compose logs -f kali-mcp-server

# Kali container logs
docker-compose logs -f kali-linux

# All logs
docker-compose logs -f

Restart Services

docker-compose restart

Stop Services

docker-compose down

Rebuild After Changes

docker-compose build --no-cache
docker-compose up -d

# Re-add to catalog with updates
docker mcp catalog add my-security-tools kali-linux-tools ./kali-catalog.yaml --force

Uninstall

# Remove everything (containers, images, catalog entries)
./uninstall.sh

Install Additional Tools Manually

# Connect to Kali container
docker exec -it kali-tools-container /bin/bash

# Install tools
apt-get update
apt-get install -y <package-name>

Clear Tool Cache

The server caches discovered tools for 1 hour. To force rediscovery:

docker-compose restart kali-mcp-server

Troubleshooting

MCP Server Not Detected by Docker Desktop

1. Check if MCP Toolkit is enabled in Docker Desktop settings
2. Verify labels in docker-compose.yaml
3. Ensure container is running: docker ps | grep kali-mcp-server
4. Restart Docker Desktop

Kali Container Not Starting

docker-compose down
docker-compose up -d
docker-compose logs kali-linux

Tools Not Available

First run requires tool installation:

# Check installation progress
docker-compose logs -f kali-mcp-server

# Or install manually
docker exec -it kali-tools-container bash
apt-get update && apt-get install -y kali-linux-everything

Permission Denied Errors

The MCP server needs access to Docker socket:

# Verify socket is mounted
docker inspect kali-mcp-server | grep "/var/run/docker.sock"

Disk Space Issues

Kali tools require significant space:

• kali-linux-everything: ~15GB (DEFAULT - installed automatically)
• kali-linux-default: ~5GB
• kali-tools-top10: ~2GB (alternative option)

Ensure you have at least 20GB free before starting.

Check available space: docker system df

To reduce disk usage, switch to a smaller package (see Configuration section above).

Security Warnings

⚠️ CRITICAL SECURITY CONSIDERATIONS:

1. Legal Use Only: Only use these tools on systems you own or have explicit written permission to test
2. Privileged Container: The MCP server runs with Docker socket access
3. Network Access: Containers can access your network - use responsibly
4. Dangerous Tools: These tools can cause damage, data loss, or legal issues if misused
5. Audit Logging: Consider implementing audit logs for all commands
6. Access Control: Only run in trusted environments with proper access controls
7. Isolation: Consider running in an isolated network or VM
8. No Production Use: Never run this on production systems

Performance Notes

• First Run: 1-2 hours (image pull + kali-linux-everything installation)
• Subsequent Runs: <10 seconds to start
• Tool Discovery: 5-10 seconds (cached for 1 hour)
• Command Execution: Varies by tool (default 5 min timeout)
• Disk Usage: ~15GB for kali-linux-everything (default installation)

Contributing

To add more tools or improve functionality:

1. Edit src/index.ts to add tool definitions
2. Rebuild: docker-compose build
3. Test with Docker Desktop MCP Toolkit

License

MIT

Disclaimer

This tool is provided for educational and authorized security testing purposes only. The authors and contributors are not responsible for any misuse, damage, or legal consequences arising from the use of this tool. Users must:

• Obtain proper authorization before conducting any security testing
• Comply with all applicable laws and regulations
• Use the tools responsibly and ethically
• Understand the risks and potential consequences

By using this tool, you acknowledge that you have read and understood these terms and agree to use it only for lawful purposes.