kali-ssh-mcp

⚠️ For authorized security testing only. This tool executes offensive security tooling (nmap, gobuster, nuclei, nikto) against remote targets. Only use it against systems you own or have explicit written authorization to test. See SECURITY.md for the full disclaimer and threat model before use.

An MCP server that bridges an LLM client (Claude Desktop, or any MCP-compatible client) to a persistent Kali Linux VM over SSH — with a hard scope allowlist, structured JSON output, and a full audit log.

Read SECURITY.md before connecting this alongside other MCP tools that can browse the web. Combining always-on tool access with web-fetching creates a real prompt-injection risk — this doc explains the mitigations built in and what you should still do on your end.

Why this exists

There are already several good Kali/pentest MCP servers in the community (PENTEST-MCP-SERVER, pentest-mcp, zebbern-kali-mcp, and others — worth checking out). Almost all of them share one design decision: Kali runs as a disposable Docker container on the same machine as your MCP client. That's a great fit if you want zero setup and don't care about state persisting between sessions.

This project is for the other common setup: you already have a real, long-lived Kali VM — in VMware, VirtualBox, on bare metal, wherever — with your own tool configs, custom wordlists, and scripts already in place, and you don't want to lose that every time a container gets torn down. This server just SSHes into whatever Kali box you already have and drives it, nothing about your existing setup has to change.

	This project	Most Docker-based Kali MCPs
Kali environment	Your existing, persistent VM	Fresh container per run
State between sessions	Persists (it's your real VM)	Resets unless you mount volumes
Setup	SSH key exchange	Docker install + image build
Best for	You already run Kali as a daily driver	Zero-setup, throwaway testing

What it does

Exposes four scanning tools to your MCP client, each scope-gated and returning parsed JSON instead of raw terminal output:

• nmap_scan — presets for quick/full/service/vuln scans, or an explicit port spec
• gobuster_scan — directory brute-forcing, with optional session cookie support for authenticated testing
• nuclei_scan — template-based vulnerability scanning, filterable by severity or template set
• nikto_scan — web server vulnerability scanning

Plus two read-only utility tools:

• list_scope — see the current engagement's allowed targets
• get_audit_log — review recent tool calls (allowed and rejected)

Want to add another tool (sqlmap, subfinder, whatweb, ...)? See EXTENDING.md — the shared scope-gate/audit-log/validation plumbing means a new tool is usually 20-30 lines, not a rewrite.

Quick start

git clone https://github.com/1337exe/kali-ssh-mcp.git
cd kali-ssh-mcp
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp config.example.yaml config.yaml

Edit config.yaml:

• ssh.host — your Kali VM's IP
• ssh.username / ssh.key_path — SSH key auth strongly recommended
• scope.targets — only hosts/CIDRs listed here can be scanned; update this every time your authorized scope changes

On the Kali VM, make sure SSH is running and your key is authorized:

sudo systemctl enable --now ssh

Verify the connection manually before wiring up an MCP client:

ssh -i ~/.ssh/your_key user@<kali-vm-ip> "nmap --version"

Run the offline tests (no SSH needed):

python3 test_logic.py

Start the server:

python3 server.py

Connect it to your MCP client — see examples/claude_desktop_config.md for a copy-paste Claude Desktop config (macOS, Linux, and Windows). A full example conversation is in examples/example_session.md.

Design principles

• Scope is enforced in code, not just convention. Every tool call checks the target against config.yaml's allowlist before anything executes on the Kali box. No match, no execution — no exceptions.
• The tool whitelist is small and deliberate. Only nmap_scan and gobuster_scan exist right now. Adding a new tool is a conscious code change (see CONTRIBUTING.md), not something the LLM can do itself.
• Structured output only. Raw nmap XML and gobuster text are parsed into JSON before the LLM ever sees them — no asking the model to parse terminal output, which is slower and less reliable.
• Everything is logged. Every call — allowed or rejected — is appended to audit_log.jsonl. This is your record of what an LLM session actually did, which matters both for your own review and for anyone asking how a finding was reached.

Roadmap / good first contributions

• A session-capture tool pairing with a browser-automation MCP (Playwright, Claude in Chrome) to pull authenticated cookies automatically instead of pasting them in by hand
• Docker/Portainer-backed tools for long-running scans you don't want tying up the Kali VM directly
• sqlmap / subfinder / whatweb wrappers

See EXTENDING.md for exactly what a new tool needs to include before it'll be merged — scope gating and input validation aren't optional. CONTRIBUTING.md covers the PR process itself.

License

MIT — see LICENSE.

Responsible use

This tool is for testing systems you own or are explicitly authorized to test. See SECURITY.md for the full disclaimer and threat model.