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.
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.
1. Start the Kali backend:
# Download just the compose file — no full clone needed
curl -sLO https://raw.githubusercontent.com/zebbern/zebbern-kali-mcp/main/docker-compose.yml
docker compose up -dOr build and run directly:
docker build -t zebbern-kali-mcp .
docker run -d -p 5000:5000 --name zebbern-kali zebbern-kali-mcpLinux host networking: For direct host network access (no port mapping needed), also grab
docker-compose.host.ymland run:docker compose -f docker-compose.yml -f docker-compose.host.yml up -d
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.
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 |
Everything below is pre-installed in the Docker image — no manual setup required.
| Tool | Description |
|---|---|
| nmap | Port scanning, service/version detection, NSE scripts |
| masscan | High-speed port scanner |
| sslscan | SSL/TLS configuration analysis |
| 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 |
| 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 |
| Tool | Description |
|---|---|
| hydra | Network login brute-forcer |
| john | John the Ripper password cracker |
| hashcat | GPU-accelerated hash cracking |
| 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 |
| coercer | Coerce Windows authentication |
| dementor | SpoolService abuse for relay attacks |
| winrmexec | WinRM command execution |
| pywhisker | Shadow Credentials attack tool |
| ldapdomaindump | LDAP domain information dumper |
| Tool | Description |
|---|---|
| metasploit-framework | Full Metasploit Framework |
| commix | Command injection exploitation |
| ghauri | Advanced SQL injection |
| dalfox | XSS scanning and exploitation |
| byp4xx | 403 Forbidden bypass techniques |
| exploitdb | Exploit database (searchsploit) |
| Tool | Description |
|---|---|
| getJS | Extract JavaScript files from pages |
| jsluice | Extract URLs, paths, and secrets from JS |
| xnLinkFinder | Link and parameter discovery from JS |
| SecretFinder | Find API keys and secrets in JS files |
| TruffleHog | Secret scanning across repos and files |
| js-beautify | JavaScript deobfuscation/beautification |
| webcrack | Webpack bundle unpacking (npm) |
| ParamSpider | Parameter discovery from web archives |
| Tool | Description |
|---|---|
| jwt-tool | JWT token analysis and exploitation |
| graphw00f | GraphQL engine fingerprinting |
| clairvoyance | GraphQL schema introspection |
| Tool | Description |
|---|---|
| mitmproxy | Scriptable HTTP/HTTPS proxy (mitmdump) |
| OWASP ZAP | Automated web app security scanner (zaproxy) |
| Caido | Modern web proxy (CLI) |
| Tool | Description |
|---|---|
| binwalk | Firmware analysis and file extraction |
| steghide | Steganography tool |
| stegseek | Fast steghide cracker (wordlist-based) |
| zsteg | PNG/BMP steganography detector (Ruby) |
| exiftool | Metadata reader/writer |
| foremost | File carving/recovery |
| volatility3 | Memory forensics framework (Python) |
| sleuthkit | Disk forensics — mmls, fls, icat, blkcat |
| gdb | GNU Debugger |
| radare2 | Reverse engineering framework (disassembly, debugging, patching) |
| imagemagick | Image manipulation and analysis |
| tesseract-ocr | Optical character recognition |
| Tool | Description |
|---|---|
| angr | Binary analysis framework |
| pwntools | CTF exploitation library |
| Tool | Description |
|---|---|
| pycryptodome | Cryptographic primitives |
| gmpy2 | High-precision math |
| z3-solver | SMT constraint solver |
| sympy | Symbolic mathematics |
| SageMath | Not bundled in the current Kali rolling image |
| RsaCtfTool | RSA attack automation (/opt/RsaCtfTool/) |
| cado-nfs | Integer factorization for large keys (/opt/cado-nfs/) |
| Tool | Description |
|---|---|
| scapy | Packet crafting and sniffing (Python) |
| tcpdump | Packet capture |
| socat | Multipurpose relay / socket tool |
| netcat | TCP/UDP networking utility |
| proxychains4 | Proxy routing for arbitrary tools |
| openvpn | VPN client |
| wireguard-tools | WireGuard VPN |
| Tool | Description |
|---|---|
| chisel | TCP/UDP tunnel over HTTP (Go binary + Windows .exe in /opt/windows-tools/) |
| ligolo-ng (v0.7.5) | Tunneling — proxy + agents for Linux & Windows (in /opt/ligolo-ng/) |
| socat | Port forwarding and relay |
| Tool | Description | Location |
|---|---|---|
| LinPEAS | Linux privilege escalation audit script | /opt/privesc-tools/linpeas.sh |
| WinPEAS | Windows privilege escalation audit (x64, x86, .bat) | /opt/privesc-tools/ |
| Mimikatz | Windows credential extraction | /opt/windows-tools/mimikatz/ |
| RunasCs.exe | Windows runas with explicit credentials | /opt/windows-tools/RunasCs.exe |
| Tool | Description |
|---|---|
| cloudflared | Cloudflare Tunnel client (expose services without port-forwarding) |
| ngrok | Instant public URLs for local services |
| Tool | Description |
|---|---|
| ffmpeg | Audio/video processing and conversion |
| sox | Sound processing and analysis (+ all format plugins) |
| podman | Rootless container engine (needs --privileged at runtime) |
| numpy | Numerical computing (Python) |
| scipy | Scientific computing (Python) |
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.
| Tool | Description |
|---|---|
| Playwright (Chromium) | Headless browser for SPA testing, screenshots, JS-rendered pages |
Pre-installed: rockyou.txt (decompressed), SecLists, and symlinked wordlists at /usr/share/wordlists/dirb/ for tool compatibility.
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.
| Variable | Default | Description |
|---|---|---|
API_PORT |
5000 |
Flask server port |
DEBUG_MODE |
0 |
Enable debug logging |
BLOCKING_TIMEOUT |
30 |
Default command timeout (seconds) |
HTB_ROUTES |
— | Comma-separated CIDRs to route (e.g. 10.129.0.0/16,10.10.0.0/16) |
EXTRA_HOSTS |
— | Comma-separated hostname:ip pairs added to /etc/hosts |
VPN_DIR |
./vpn |
Host directory mounted at /vpn (read-only) for VPN configs |
KALI_API_URL |
http://127.0.0.1:5000 |
MCP client: URL of the Kali Flask server |
# Standard (bridge networking, port-mapped)
docker compose up -d
# Host networking (Linux only — direct access to host network/VPN interfaces)
docker compose -f docker-compose.yml -f docker-compose.host.yml up -dThe compose file grants NET_RAW + NET_ADMIN capabilities and provides /dev/net/tun for VPN and Ligolo support.
| Decision | Rationale |
|---|---|
| Fail-fast build | Dockerfile fails the build if tools can't install — no || echo WARN fallbacks on critical tools. You know immediately if something is broken. |
| netexec over crackmapexec | crackmapexec is deprecated. netexec is installed from the Kali repos as the primary SMB/LDAP/WinRM tool. |
| Custom callback catcher | For isolated CTF/pentest networks where webhook.site or interactsh can't reach your targets. Built-in HTTP + DNS listener. |
| AI-agent optimized output | NO_COLOR=1, TERM=dumb, FORCE_COLOR=0, CI=true, PWNLIB_NOTERM=1 — suppresses banners, colors, progress bars, and interactive prompts so AI agents get clean, parseable text. |
| impacket pinned to 0.13.0 | Ensures stable AD tool behavior across rebuilds. |
| Separate client/server | MCP client is a lightweight PyPI package (uvx zebbern-kali-mcp); the heavy tools live in Docker. Users never install pentest tools on their host. |
zebbern-kali-mcp/
├── Dockerfile # Multi-layer Kali image build
├── docker-compose.yml # Standard bridge-mode deployment
├── docker-compose.host.yml # Host networking overlay (Linux)
├── 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
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.
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.
⚠️ This server provides unrestricted access to powerful penetration testing tools.
- Never expose to the public internet
- Only run on isolated networks or authorized test environments
- Use strong authentication if accessible remotely
- Ensure you have proper authorization before testing any systems
- The container runs as
root— this is intentional for pentest tools but increases risk
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