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, …)        │
└──────────────────────────────────┘                         └──────────────────────────────────────┘

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

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:

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

Web Application Scanning

Subdomain & DNS Enumeration

Brute Force & Password Cracking

Active Directory

Exploitation

JavaScript Analysis

API Testing

Proxy & Interception

Forensics & CTF

Binary Analysis (Python)

Crypto & Math (Python)

Networking

Pivoting

Privilege Escalation

Tunneling & Remote Access

Media & Containers

Callback Catcher

A custom built-in HTTP + DNS callback listener for isolated networks where external services like webhook.site can't reach your targets. Managed via the callback_catcher MCP module.

The default listeners use TCP 8888 and UDP 5353. A target can reach them directly through a VPN interface inside the container or with Linux host networking. In bridge mode, publish the selected callback ports on an address reachable by the target, for example 8888:8888/tcp and 5353:5353/udp; these ports are not published by default.

Browser Automation

Wordlists

Pre-installed: rockyou.txt (decompressed), SecLists, and symlinked wordlists at /usr/share/wordlists/dirb/ for tool compatibility.

Python Dependencies

From requirements.txt — installed inside the container:

Flask, Werkzeug            # API server
requests                   # HTTP client
paramiko                   # SSH
mcp                        # MCP protocol (client)
playwright                 # Browser automation
pwntools                   # Binary exploitation
sympy, gmpy2               # Math
pycryptodome, z3-solver    # Crypto & SMT solving
angr                       # Binary analysis
scapy                      # Packet crafting
Pillow                     # Image processing (stego)
beautifulsoup4             # HTML parsing
impacket==0.13.0           # AD attacks (pinned)
ldapdomaindump, pywinrm    # AD support
pexpect                    # Terminal automation
python-dotenv              # Environment config

Additional pip packages installed during build: bloodyAD, certipy-ad, bloodhound, pywhisker, coercer, fierce, arjun, dementor, commix, ghauri, jwt-tool, graphw00f, clairvoyance, xnLinkFinder, paramspider, mitmproxy, waymore, ssh-audit, volatility3, numpy, scipy.

Configuration

Environment Variables

Docker Compose

# Standard (bridge networking, port-mapped)
docker compose up -d

# Host networking (qualified on native Linux Docker Engine and Windows Docker Desktop 4.84)
docker compose -f docker-compose.yml -f docker-compose.host.yml up -d

# Lean qualified variant; both qualified variants include CADO-NFS
INCLUDE_METASPLOIT=false INCLUDE_CADO_NFS=true docker compose build

# Faster development build without only CADO-NFS
INCLUDE_CADO_NFS=false docker compose build

The Compose build defaults are INCLUDE_METASPLOIT=true and INCLUDE_CADO_NFS=true. Both qualified full and lean variants include CADO-NFS. When INCLUDE_CADO_NFS=true, source retrieval, build, or executable verification failure stops the image build. Setting it to false intentionally removes only CADO-NFS.

The Kali base image, Go modules, Git sources, and moving standalone downloads are pinned. Kali rolling APT packages and Python transitive dependency resolution are not bit-identical snapshots.

The compose file grants NET_RAW + NET_ADMIN capabilities and provides /dev/net/tun for VPN and Ligolo support. In bridge mode, API and SOCKS publications bind to loopback. In host-network mode, both services listen on loopback. Native Linux Docker Engine and the current Windows Docker Desktop 4.84 setup are qualified. Docker Desktop requires version 4.34 or later, an explicit host-networking opt-in and restart, and Linux containers; it supports TCP and UDP only, cannot use Enhanced Container Isolation, and cannot bind a specific host-interface IP. Native Linux Docker Engine retains direct host-network semantics. Set the corresponding bind or listen variable when another host must connect.

For a remote API, set the same KALI_API_TOKEN value in the backend and MCP client environments. You can also pass --api-token to the MCP client. Direct REST clients send this value in the X-API-Key header. Health endpoints remain unauthenticated for Docker and orchestrator checks.

Updating pinned build inputs

1. Resolve an authoritative upstream version or commit.
2. Update one Docker argument and its checksum when present.
3. Run Docker contract tests and docker build --check ..
4. Build full and lean with CADO-NFS enabled.
5. Run image, bridge, AD, native Linux host-network, and current Windows Docker Desktop host-network smoke.
6. Compare tool names, image IDs/sizes, and common layers before accepting the update.

Live qualification fixtures

Run the qualified fixtures against the specified locally built images:

python tests/integration/run_smoke.py --image zebbern-kali-mcp:goal-full --network-mode bridge --expect-variant full
python tests/integration/run_ad_lab.py --image zebbern-kali-mcp:goal-lean
python tests/integration/run_smoke.py --image zebbern-kali-mcp:goal-full --network-mode host --expect-variant full

Add --check-trim to any run_smoke.py invocation to additionally assert the live trim profile against the running image: it must expose 123 tools and omit exactly the nine callback_* tools plus parse_tool_output, with no other additions or losses. The check is opt-in because it costs one extra MCP session per run. It is independent of the image variant, since trim is a static profile that ignores capability discovery.

python tests/integration/run_smoke.py --image zebbern-kali-mcp:goal-full --network-mode bridge --expect-variant full --check-trim

pytest -m live runs the live tool suite against an already-running backend, exercising real execution rather than a mocked client: background job state across separate MCP processes, /etc/hosts round-trips, nmap and fingerprinting against a lab target, and verbatim command output. Each case opens its own MCP stdio session, so any state that survives between calls is provably server-side. The suite skips itself when no backend answers, which keeps CI green without Docker. Override KALI_API_URL, ZKM_LAB_HOST, and ZKM_LAB_PORT to point it elsewhere; from inside the container the host lab is reachable at host.docker.internal, not 127.0.0.1.

The AD fixture is local, disposable, and has no host-published ports. It proves only local DNS, authenticated LDAP discovery, and the public MCP/API enumeration path. It does not qualify other Active Directory operations. Host networking is qualified on native Linux Docker Engine and the current Windows Docker Desktop 4.84 setup after the explicit opt-in and restart. Desktop remains limited to TCP and UDP layer 4, Linux containers, no Enhanced Container Isolation, and no binding to a specific host-interface IP. linux/amd64 is the only qualified image architecture.

Design Decisions

Project Structure

zebbern-kali-mcp/
├── Dockerfile                  # Multi-layer Kali image build
├── docker-compose.yml          # Standard bridge-mode deployment
├── docker-compose.host.yml     # Host networking overlay
├── entrypoint.sh               # Container init (routes, hosts, TUN, IP forwarding)
├── requirements.txt            # Python dependencies for the container
├── pyproject.toml              # PyPI package config for the MCP client
├── mcp_server.py               # MCP client entrypoint (FastMCP server)
│
├── mcp_tools/                  # MCP CLIENT (runs on host)
│   ├── _client.py              #   KaliToolsClient — HTTP transport
│   ├── kali_tools.py           #   Nmap, Nikto, Gobuster, SQLMap, etc.
│   ├── ad_tools.py             #   Active Directory tools
│   ├── callback_catcher.py     #   HTTP/DNS callback listener
│   └── ... (17 modules)        #   One module per tool category
│
├── zebbern-kali/               # FLASK SERVER (runs in Docker)
│   ├── kali_server.py          #   Flask app entry point
│   ├── api/
│   │   ├── routes.py           #   Blueprint registration
│   │   └── blueprints/         #   17 Flask blueprints (one per module)
│   │       ├── tools.py        #     Scanning tools routes
│   │       ├── ad.py           #     AD tool routes
│   │       ├── callback.py     #     Callback catcher routes
│   │       └── ...
│   ├── core/                   #   Business logic
│   │   ├── config.py           #     Configuration & constants
│   │   ├── command_executor.py #     Subprocess execution
│   │   ├── ad_tools.py         #     AD tool logic
│   │   └── ...
│   └── tools/
│       └── kali_tools.py       #   Tool wrappers
│
├── vpn/                        # Mount point for VPN configs
└── README.md                   # Project overview and setup guide

Usage

Once installed, ask your AI assistant to use the Kali tools:

"Scan 10.10.10.5 with nmap" "Run nuclei against example.com" "Connect to the HTB VPN and start recon" "Enumerate AD with bloodhound against dc01.corp.local" "Start a callback listener on port 8080"

The assistant calls MCP tools, which make HTTP requests to the Flask API inside Docker — no manual commands needed.

zebbern_exec and streaming command execution (exec_stream) accept shell commands including ssh, scp, rsync, netcat, and telnet. This contract accepts the commands; it does not assert that every command is bundled in every image variant. Dedicated SSH, pivot, and payload managers are structured conveniences, not mandatory restrictions. Set the command timeout for the operation. The backend keeps background-job input and output bounded, redacts common credential forms from command diagnostics, and cancels a job's process group on cancellation or timeout.

Long-running or interactive commands can use the background job workflow:

1. Call zebbern_exec(..., background=true) and keep the returned job_id.
2. Poll job_output(job_id) or check job_status(job_id).
3. Use send_input(job_id, text) for interactive stdin.
4. Call job_cancel(job_id) when the work is no longer needed.
5. Call job_list() if the job_id is gone — it returns every job the backend still tracks, newest first.

Every subprocess-backed tools_* wrapper takes the same flag — tools_nmap(target=..., background=true), tools_hydra(..., background=true) and so on — and returns a job_id driven by the same four tools. Set it for anything that may run longer than about a minute: an MCP client abandons a synchronous tool call around then, and the scan keeps running with no handle left to read or stop it.

Job state and bounded output are kept in memory. Restarting the backend clears them.

Documentation

This README is the primary source of truth for setup, usage, and tool reference. The separate MkDocs site and legacy VM install docs were removed.

Security Warning

This server intentionally provides unrestricted command execution and powerful penetration-testing tools.

The local default binds the API and SOCKS ports to 127.0.0.1. Remote use is supported: choose an explicit bind address, configure KALI_API_TOKEN, and place TLS or a trusted private network in front when traffic crosses an untrusted network. The container runs as root because several networking and assessment features require it. Use the tool only on systems you are authorized to test.

Contributing

Contributions welcome! Please open a pull request with a clear summary of changes and any relevant test notes.

Built on the Model Context Protocol · Created by Zebbern