Kali MCP

An MCP server that lets Claude (Desktop, Code) and other local-LLM clients drive a full Kali Linux toolset for authorized security testing and analysis.

The model doesn't run tools on your Windows host — it runs them inside an isolated Kali Docker container. The MCP server is a thin Python layer that docker execs into that container, captures output, and manages long-running scans as background jobs.

  Claude / local LLM  ──MCP──►  kali_mcp.server (Python)  ──docker exec──►  kali_mcp container
        (stdio or HTTP)                                                     (kali-linux-headless)
                                                                            /workspace (isolated volume)

Sandboxing

The container is confined so nothing it runs can touch the Windows host, while still reaching the internet and its targets:

• No host filesystem access. Output lives in a Docker-managed named volume (kali_mcp_kali_workspace), not a host bind mount. Retrieve results with the kali_read_file tool or docker cp kali_mcp:/workspace ./workspace.
• Not privileged, no host namespaces, no docker socket — the escape vectors that would give a container access to the host are simply absent.
• Minimal capabilities — only NET_RAW/NET_ADMIN (needed by nmap and friends), which act solely on the container's own isolated network stack.
• Resource caps — 6 GB RAM, 4 CPUs, 4096 PIDs, so a runaway scan can't starve the host.
• Dedicated bridge network — isolated from other containers, NAT'd to the internet.

To pull all results out to Windows at once:

docker cp kali_mcp:/workspace ".\workspace"

Optional: VPN egress (route scans through a VPS)

By design, a container reaches the internet by NAT through the host's network stack — so scan traffic transits your machine, where host AV/IPS can see and interfere with it. This is networking, not a container-isolation gap, and no amount of container hardening changes it. The fix is to control egress.

docker-compose.vpn.yml runs the Kali container through a WireGuard tunnel (gluetun sidecar) to an egress you control:

• Scan traffic exits from your VPS IP, not your workstation.
• Your host AV sees only encrypted UDP — no scan signatures to flag.
• Kill-switch: if the tunnel drops, the container has no route out (fail closed) and can't reach your LAN or host. This is the meaningful network isolation upgrade.

cp .env.example .env          # fill in your WireGuard/VPS details (never commit .env)
docker compose down           # stop the plain stack first
docker compose -f docker-compose.vpn.yml up -d
docker exec kali_mcp curl -s ifconfig.me   # should print your VPS IP

Run active scans this way; keep your workstation out of the traffic path.

Egress provider: .env supports two modes. VPN_SERVICE_PROVIDER=custom points the tunnel at your own VPS (recommended for active scanning — you own a whitelistable IP and stay within provider terms). VPN_SERVICE_PROVIDER=protonvpn uses a ProtonVPN WireGuard config (from Proton → Downloads → WireGuard) with no VPS needed — but ProtonVPN's terms prohibit port scanning, so use it for passive / OSINT egress only, not active scans.

Pivoting into internal networks

VPN egress controls outbound traffic. To reach a network segment only accessible through a foothold (an in-scope jump box), route tools through it. Both approaches use tools already in the image, driven via kali_run:

• proxychains (TCP-only). With a SOCKS proxy on the foothold (ssh -D 1080 user@pivot, or chisel / Meterpreter socks), prefix commands: proxychains4 -q curl http://10.10.0.5. It hooks TCP connect() only, so use nmap -sT -Pn -n — no SYN, UDP, or OS detection through the chain, and non-TCP traffic is not proxied.
• ligolo-ng / sshuttle (tun-based, preferred for scanning). These create a real network interface, so full nmap (-sS, UDP, OS detection) works through the pivot without proxychains' TCP-only limitation.

Keep the WireGuard tunnel for outbound egress; use pivoting only to reach internal networks via an authorized foothold.

What's inside the container

The image installs the full kali-linux-headless metapackage — hundreds of tools (nmap, masscan, nikto, gobuster, ffuf, sqlmap, nuclei, hydra, whatweb, dnsrecon, wpscan, searchsploit, metasploit, and many more) — plus SecLists and common utilities. First build is several GB and can take a while.

Prerequisites

• Docker Desktop (running) — already set up on this machine
• Python 3.11+ (3.14 present) with the mcp and pydantic packages

Setup

From this directory (C:\path\to\kali_mcp):

.\setup.ps1

That builds the image, starts the kali_mcp container, creates a .venv, and installs the Python deps. To do it by hand:

docker compose up -d --build                          # build image + start container
py -m venv .venv                                      # dedicated virtual environment
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Why a venv (not pip install --user)? MCP clients such as LM Studio and Claude Desktop launch the server with a stripped-down environment that omits %APPDATA%, so user-site packages become invisible and you get ModuleNotFoundError: No module named 'pydantic'. The venv's packages are found via its own prefix regardless of environment, which fixes this for every client. All client configs must point at .venv\Scripts\python.exe.

The container stays up (restart: unless-stopped). Scan reports are written to the isolated /workspace volume — read them back with the kali_read_file tool or copy them out with docker cp kali_mcp:/workspace ./workspace (see Sandboxing above).

Connecting a client

Claude Desktop (stdio)

Merge the kali block from claude_desktop_config.example.json into %APPDATA%\Claude\claude_desktop_config.json, then restart Claude Desktop. It launches the server itself over stdio.

Claude Code (stdio)

This repo already contains a project-scoped .mcp.json. Open Claude Code in this folder and it offers to enable the kali server. Or register it globally:

claude mcp add kali -e PYTHONPATH=C:\path\to\kali_mcp -- "C:\path\to\kali_mcp\.venv\Scripts\python.exe" -m kali_mcp.server

Other local LLM clients (HTTP)

Start the server in HTTP mode:

.\.venv\Scripts\python.exe -m kali_mcp.server --http --host 127.0.0.1 --port 8765

It serves the streamable HTTP MCP transport at http://127.0.0.1:8765/mcp. Point any MCP-capable client (LM Studio, Open WebUI with an MCP bridge, custom clients, etc.) at that URL.

Tools

Tool	Purpose
kali_run	Run any command in the container and wait for the result. The main workhorse.
kali_run_background	Launch a long scan detached; returns a job_id.
kali_job_status	Check / tail a background job by id.
kali_stop_job	Kill a background job.
kali_list_jobs	List this session's background jobs.
kali_nmap	nmap wrapper that also saves XML to /workspace.
kali_recon	Workflow: nmap service scan → whatweb fingerprint → optional nikto/gobuster (run_web_scan) and nuclei (run_nuclei). Saves all artifacts for reporting.
kali_engagement_set	Set engagement metadata: client, assessor, dates, scope, rules of engagement.
kali_engagement_get	Show current engagement metadata.
kali_add_finding	Record an analyst-authored finding (severity, CVSS, affected assets, description, impact, remediation, references, evidence). CVSS score auto-computed from the vector if omitted.
kali_list_findings	List manual findings.
kali_remove_finding	Delete a manual finding by ID.
kali_report	Consulting report: merges engagement metadata + manual findings + every nmap/nuclei/nikto/whatweb/gobuster/ffuf artifact + the audit log into Markdown, styled HTML, and (with pdf: true) a print-optimized PDF. Automated findings are deduplicated across hosts. Supports min_severity filtering and a PASS/FAIL gate.
kali_export_findings	Export consolidated findings to CSV and/or JSON for import into ticketing/GRC tools.
kali_list_results	List result files (scans, reports, loot) in the workspace.
kali_update	Refresh nuclei templates and the searchsploit DB.
kali_cleanup	End-of-engagement wipe of /workspace (scans, reports, engagement, findings, audit log). Requires confirm: true; otherwise a dry-run preview.
kali_which	Search installed tools by name.
kali_read_file	Read a file (e.g. a scan report) out of the container.
kali_write_file	Write a target list / wordlist / notes into the container.
kali_status	Container state, Kali version, tool count.

Reporting workflow

Every command is logged to /workspace/audit.log (JSON lines: timestamp, command, exit code, duration) — disable with KALI_MCP_AUDIT=0. Read-only helpers (kali_read_file, kali_status, kali_which, kali_list_results) are not logged, so the log reflects actual testing activity.

A consulting engagement flow:

1. Define the engagement — kali_engagement_set with client, assessor, dates, scope, and rules of engagement. This drives the report cover page and scope section.

2. kali_update — refresh feeds (once per engagement).

3. Test — kali_recon <host> for each target (add run_web_scan: true for nikto+gobuster, run_nuclei: true for a vuln pass), and/or drive any tool directly with kali_run.

4. Record findings — kali_add_finding for each analyst-identified issue (severity, CVSS, affected assets, impact, remediation, evidence, references). These are the heart of the report.

5. kali_report — assembles a professional report:

   • cover page (client, assessor, dates, classification banner)
   • executive summary with overall risk rating and metrics
   • optional severity gate — gate: high adds a PASS/FAIL verdict (FAIL if any finding is at/above the threshold)
   • scope & rules of engagement
   • findings ranked by severity — manual findings (full CVSS/impact/remediation) plus automated findings from nuclei/nikto; min_severity filters out low/info noise
   • per-host details — ports, service versions, OS guess, web technologies, content discovery (gobuster/ffuf)
   • methodology / command log (from the audit trail)
   • artifact appendix

   Saved to /workspace/report/report-<timestamp>.{md,html}. Pull it with docker cp kali_mcp:/workspace/report . and open the HTML in a browser.

The report engine also picks up artifacts from raw kali_run scans as long as they land in /workspace — nmap -oX *.xml, nuclei -jsonl, nikto -Format json, whatweb --log-json, gobuster -o, and ffuf -of json outputs are all parsed automatically. Engagement data (metadata + manual findings) persists in /workspace/engagement/engagement.json.

Findings hygiene, built in:

• CVSS auto-rating — supply a cvss_vector (CVSS v3.0/3.1) to kali_add_finding and the base score is computed for you (e.g. AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H → 9.8).
• Deduplication — the same automated check firing across many hosts (e.g. a nuclei template on 20 servers) collapses into one finding listing all affected assets, with an instance count.
• Export — kali_export_findings writes flat CSV/JSON of the consolidated, deduplicated findings for import elsewhere.

Example prompts

• "Run a service-version nmap scan against scanme.nmap.org and summarize the open ports."
• "Full-port-scan 192.168.1.0/24 in the background, then check the job in a minute."
• "Fuzz https://target.example directories with ffuf and the common wordlist."
• "What SQL-related tools are installed?" (uses kali_which)

Configuration

Environment variables (optional):

Variable	Default	Meaning
KALI_MCP_CONTAINER	kali_mcp	Container name to exec into.
KALI_MCP_DOCKER	docker	Docker CLI path.
KALI_MCP_COMPOSE_DIR	project root	Where the compose file lives.
KALI_MCP_MAX_OUTPUT	60000	Max output chars returned per call.

Scope and responsible use

This server runs real offensive tooling with no built-in target restrictions — by design. Only test systems you own or are explicitly authorized to assess. You are responsible for staying within the scope of your engagement and applicable law. Scan outputs live in the isolated kali_mcp_kali_workspace volume; treat them as sensitive. If you later want a target allowlist or command audit log, the executor.py layer is the single place to add it.

Troubleshooting

• "Container is not present and could not be created" — run docker compose up -d --build in this folder and check docker ps.
• Server won't start in a client — confirm the Python path in the config matches py -c "import sys; print(sys.executable)", and that PYTHONPATH points at this folder.
• Raw-socket scans fail — the container is granted NET_ADMIN/NET_RAW in docker-compose.yml; make sure you started it via compose, not a bare docker run.
• Rebuild after editing the Dockerfile — docker compose up -d --build.