Zebbern Kali MCP Server

A Docker-based Model Context Protocol (MCP) server that gives AI agents (GitHub Copilot, Claude, etc.) direct access to a full Kali Linux penetration testing toolkit. The AI agent calls MCP tools, which forward requests to a Flask API running inside a Kali container — every tool executes in an isolated, pre-configured environment.

---

Architecture

The project is a two-part client → server system:

┌──────────────────────────────────┐          HTTP           ┌──────────────────────────────────────┐
│          Windows / Host          │        (port 5000)      │         Docker Container             │
│                                  │                         │         (kalilinux/kali-rolling)     │
│  AI Agent (Copilot / Claude)     │                         │                                      │
│          │                       │                         │  Flask API Server                    │
│          ▼                       │                         │    ├── api/blueprints/*.py  (routes) │
│  MCP Client  (mcp_tools/*.py)    │ ──── POST /tools/* ───► │    └── core/*.py           (logic)  │
│    └── KaliToolsClient           │                         │              │                       │
│        (HTTP requests)           │                         │              ▼                       │
│                                  │                         │  Kali tools (nmap, sqlmap, …)        │
└──────────────────────────────────┘                         └──────────────────────────────────────┘

| Component | Location | Runs on | Role | |-----------|----------|---------|------| | MCP Client | mcp_tools/ | Host (Windows/Linux/macOS) | Exposes tool definitions to AI agents via the MCP protocol. Each tool call is translated into an HTTP request to the Flask server. | | Flask Server | zebbern-kali/ | Inside Docker container | Receives HTTP requests, dispatches them through Flask blueprints (api/blueprints/) to core logic (core/), and executes the actual Kali tools. | | Entrypoint | entrypoint.sh | Inside Docker container | Initializes networking (routes, /etc/hosts, TUN interfaces, IP forwarding) before launching the Flask server. |

Request flow: AI Agent → MCP tool function → KaliToolsClient HTTP request → Flask blueprint → Core logic → tool execution on Kali → JSON response back.

---

Quick Start

Source checkout + uvx

1. Start the Kali backend:

# Clone the source and build the local image.
git clone https://github.com/zebbern/zebbern-kali-mcp.git
cd zebbern-kali-mcp
docker compose up -d --build

Or build and run directly:

docker build -t zebbern-kali-mcp .
docker run -d --name zebbern-kali \
  --cap-add NET_RAW --cap-add NET_ADMIN \
  --device /dev/net/tun:/dev/net/tun \
  --sysctl net.ipv4.ip_forward=1 \
  -p 127.0.0.1:5000:5000 \
  -p 127.0.0.1:1080:1080 \
  -v zebbern-kali-tmp:/app/tmp \
  -v "$(pwd)/vpn:/vpn:ro" \
  zebbern-kali-mcp

Host networking: Native Docker Engine on Linux and the current Windows Docker Desktop 4.84 setup are qualified host-network platforms. Run:

docker compose -f docker-compose.yml -f docker-compose.host.yml up -d

On Docker Desktop 4.34 or later, enable host networking in Settings > Resources > Network and restart Docker Desktop before running the overlay. The current Windows Docker Desktop 4.84 setup is qualified with that opt-in. Desktop support is limited to TCP and UDP (layer 4), does not work with Enhanced Container Isolation, supports Linux containers only, and cannot bind a specific host-interface IP. Native Linux Docker Engine retains direct host-network semantics.

2. Add to VS Code (.vscode/mcp.json or global MCP config):

{
  "servers": {
    "kali-tools": {
      "command": "uvx",
      "args": ["zebbern-kali-mcp"]
    }
  }
}

Restart VS Code — done. uvx auto-downloads the MCP client from PyPI.

Docker is the supported install path. See the setup sections below for env vars, VPN/SOCKS proxy, image variants, and networking details.

---

MCP Tool Modules

17 MCP client modules in mcp_tools/, each with a corresponding Flask blueprint in zebbern-kali/api/blueprints/ and core logic in zebbern-kali/core/:

| # | Module | Description | |---|--------|-------------| | 1 | kali_tools | Nmap, Nikto, Gobuster, Dirb, WPScan, SQLMap, Hydra, John, enum4linux, Subfinder, httpx, Arjun, Fierce, ssh-audit, FFuf, Nuclei, and more | | 2 | ad_tools | Active Directory attacks — netexec, BloodHound, impacket, certipy, bloodyAD, Kerberoasting, Pass-the-Hash, LDAP | | 3 | command_exec | Arbitrary command execution on the Kali container | | 4 | ssh_manager | SSH session lifecycle — connect, execute, tunnel, disconnect | | 5 | reverse_shell | Reverse shell listeners and session management | | 6 | metasploit | Metasploit Framework integration — modules, sessions, exploits | | 7 | network_pivot | Chisel, Ligolo-ng, SSH tunnels, ProxyChains, SOCKS proxy | | 8 | vpn | WireGuard & OpenVPN management with auto SOCKS5 proxy | | 9 | api_security | GraphQL introspection, JWT analysis, FFUF fuzzing | | 10 | web_fingerprinter | Technology detection and web fingerprinting | | 11 | exploit_suggester | Exploit suggestion based on scan results | | 12 | payload_generator | Payload generation for various platforms | | 13 | file_operations | File upload/download between host and container | | 14 | callback_catcher | Built-in HTTP + DNS callback listener for isolated networks | | 15 | ctf_platform | CTFd & rCTF API — challenges, flags, scoreboard | | 16 | hosts_management | /etc/hosts management inside the container | | 17 | output_parser | Structured parsing of tool output for AI consumption |

The default auto profile starts with the complete full tool set. With a valid capability schema version 1 response, it omits only public tools explicitly reported as unavailable. Unknown, malformed, older, or unreachable capability data fails open and keeps the complete tool set. Discovery is a startup snapshot; restart the MCP client to refresh it.

auto omits any tool the manifest reports as unavailable, so the backend owns that list rather than the client keeping a parallel copy of it. Core tools are never omitted: command execution, file operations, host management and output parsing stay registered even if a manifest marks them unavailable. That floor exists because the two failure directions are not symmetric — a tool that is present but broken fails once and the agent adapts, while a tool wrongly hidden is invisible for the life of the process, since discovery is a startup snapshot. On a lean image this omits the persistent Metasploit session tools and the two msfvenom payload tools. Use a focused profile only when a smaller tool list helps the agent choose tools more reliably:

| Profile | Focus | |---------|-------| | core | Command execution, files, hosts, and output parsing | | recon | Core plus scanners, fingerprinting, and exploit suggestions | | web | Core plus web/API testing and callback capture | | ad | Core plus AD, pivoting, SSH, shells, payloads, and VPN | | ctf | Core plus scanners, CTF platforms, payloads, shells, VPN, and callbacks | | trim | All modules except callback_catcher and output_parser; 123 tools | | full | All 17 modules; complete operator override |

The explicit profiles are core, recon, web, ad, ctf, trim, and full. Select one with --profile web or MCP_TOOL_PROFILE=web. Use --profile full to register every current MCP tool regardless of discovery results. An invalid profile fails during startup.

Excluding modules from any profile

--exclude-module (or MCP_EXCLUDE_MODULES) subtracts named modules from whichever profile is selected, so you can tune the surface without waiting for a new profile. Use it when another MCP server in your setup already covers a capability — a hosted webhook/interactsh service makes callback_catcher redundant, and an agent that parses stdout itself does not need output_parser.

zebbern-kali-mcp --profile web --exclude-module callback_catcher      # 57 tools
zebbern-kali-mcp --profile full --exclude-module callback_catcher,output_parser  # 123, same as trim
MCP_EXCLUDE_MODULES=callback_catcher zebbern-kali-mcp --profile ctf    # 75 tools

Names are case-insensitive and whitespace-tolerant; an unknown module name fails at startup with the full list of valid names. Exclusion composes with auto, applying after capability discovery.

trim is the full tool set minus the two modules that duplicate capabilities most MCP hosts already provide: callback_catcher (9 tools, overlapping hosted webhook/interactsh services) and output_parser (1 tool, duplicating the agent's own stdout parsing). It registers 123 of the 133 tools. Prefer full when the host has no webhook capability of its own, or when the engagement runs on an isolated network with no egress — the built-in callback listener is the only one that works there.

---

Installed Tools

The image installs the tools below. Core tool failures stop the build. Explicitly optional extras may be skipped with a warning; check /ready and the relevant tool-status endpoint for runtime availability.

Network Scanning

| Tool | Description | |------|-------------| | nmap | Port scanning, service/version detection, NSE scripts | | masscan | High-speed port scanner | | sslscan | SSL/TLS configuration analysis |

Web Application Scanning

| Tool | Description | |------|-------------| | nikto | Web server vulnerability scanner | | gobuster | Directory/file/DNS brute-forcing | | dirb | Web content scanner | | wpscan | WordPress vulnerability scanner | | sqlmap | Automated SQL injection | | ffuf | Fast web fuzzer | | nuclei | Template-based vulnerability scanner | | katana | Web crawler (v1.1.0 pre-built binary) | | amass | Attack surface mapping | | commix | Command injection exploitation | | ghauri | Advanced SQL injection detection |

Subdomain & DNS Enumeration

| Tool | Description | |------|-------------| | subfinder | Passive subdomain discovery | | httpx | HTTP probing and technology detection | | assetfinder | Subdomain discovery via various sources | | waybackurls | Fetch URLs from the Wayback Machine | | amass | DNS enumeration and network mapping | | massdns | High-performance DNS resolver | | fierce | DNS reconnaissance | | mapcidr | CIDR range manipulation | | subzy | Subdomain takeover checking |

Brute Force & Password Cracking

| Tool | Description | |------|-------------| | hydra | Network login brute-forcer | | john | John the Ripper password cracker | | hashcat | GPU-accelerated hash cracking |

Active Directory

| Tool | Description | |------|-------------| | netexec | Primary SMB/LDAP/WinRM tool (replaces crackmapexec) | | impacket (0.13.0) | Python AD attack toolkit — ~50 scripts symlinked as impacket-* in PATH (secretsdump, psexec, wmiexec, etc.) | | bloodhound.py | AD relationship graphing — data collector | | bloodyAD | AD privilege escalation framework | | certipy-ad | AD Certificate Services (ADCS) exploitation | | responder | LLMNR/NBT-NS/MDNS poisoner | | evil-winrm | WinRM shell with upload/download | | krbrelayx | Kerberos relay and delegation abuse | | gMSADumper | Group Managed Service Account password dumper | | PetitPotam | NTLM relay coercion via EFS RPC