Kali MCP Server

Authorized use only. This tool is built for penetration testing with explicit written authorization, CTF competitions, and security research in your own lab. Running it against systems you do not own or have permission to test is illegal in most jurisdictions. You are responsible for how you use it.

A native stdio MCP server for Kali Linux pentesting with 72 typed tools, structured JSON output, persistent session state, and full C2/desktop/tunneling integration. Built as a ground-up replacement for the official mcp-kali-server.

Official:  Claude  ->  MCP client  ->  HTTP  ->  Flask  ->  subprocess
This:      Claude  ->  SSH  ->  stdio  ->  subprocess

Why Not the Official One?

The official mcp-kali-server is a Flask HTTP API that wraps 12 generic command: str passthroughs around raw shell execution. No structured output, no session state, no async support. Claude gets back raw terminal text and has to guess what happened.

	Official (mcp-kali-server)	This project
Transport	HTTP Flask API on port 5000	Native stdio over SSH
Dependencies	Flask + multiple Python packages	mcp (single package)
Tools	12 generic command passthroughs	72 typed tools with schemas
Output	Raw shell text	Structured JSON (parsed XML, extracted creds, etc.)
Session State	None	Hosts, credentials, findings persist across calls
Async Jobs	No	Background jobs with poll/cancel
C2 Integration	No	Full Sliver framework (10 tools)
Remote Desktop	No	RDP/VNC with screenshots Claude can see
Tunneling	No	Chisel, Ligolo, sshuttle, proxychains, socat
GUI Tools	No	Burp Suite, Wireshark, BloodHound
AD Tools	Basic	NetExec (full), Evil-WinRM, Kerbrute, Certipy, Responder, bloodyAD + Impacket with auto-parsing
Auto-discovery	No	Tools auto-populate session (creds, hosts, findings)
Timeouts	Blanket	Per-tool with graceful SIGTERM -> SIGKILL + partial output capture
Auto-provisioning	No	Auto-downloads SharpCollection and Chisel Windows binary on first start

Setup

On Kali

# Copy the server
scp -r . kali@KALI_IP:/opt/kali-mcp/

# Install the one dependency
pip install mcp

# Install recommended tools (most are pre-installed on Kali)
sudo apt install sliver ligolo-ng sshuttle scrot xdotool xclip
pip install bloodyAD

# Verify it starts
python3 /opt/kali-mcp/server.py
# Should show: "Registered 72 tools" and "running on stdio"
# First start also auto-clones SharpCollection and downloads chisel.exe for Windows

In Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "kali-mcp": {
      "command": "ssh",
      "args": ["kali@YOUR_KALI_IP", "cd /opt/kali-mcp && python3 server.py"],
      "timeout": 600
    }
  }
}

Replace YOUR_KALI_IP with your Kali machine's IP. SSH key auth recommended.

Verify

In Claude Code, ask Claude to run ping_sweep against a test target. You should get structured JSON back with live hosts, not raw nmap text.

Auto-Provisioning

On first start, the server automatically downloads:

• SharpCollection to /opt/SharpCollection/ — pre-compiled .NET offensive tools (Seatbelt, Rubeus, SharpHound, etc.) for use with execute-assembly via Sliver or Evil-WinRM
• Chisel Windows binary to /opt/chisel-windows/chisel.exe — latest release from GitHub for uploading to targets

Both are checked on every startup and only downloaded if missing. Provisioning is controllable via environment variables:

Variable	Effect
KALI_MCP_SKIP_PROVISION=1	No downloads at startup (offline / OPSEC-sensitive engagements)
KALI_MCP_SHARP_REF=<branch-or-tag>	Pin the SharpCollection ref (default: master)
KALI_MCP_CHISEL_VERSION=<tag>	Pin the chisel release (default: latest)

---

All 72 Tools

Recon (2)

Tool	Description
nmap_scan	Port/service scan. Returns parsed JSON: hosts, ports, services, OS, scripts. Auto-populates session hosts. Supports async.
ping_sweep	Quick host discovery via nmap -sn. Returns {live_hosts: [{ip, hostname}]}.

Web (6)

Tool	Description
gobuster_scan	Directory/DNS/vhost brute-forcing. Parsed results with path, status, size.
ffuf_scan	Fast web fuzzer. Structured JSON output with URL, status, size per hit.
dirb_scan	Web content scanner. Parsed output matching gobuster format.
nikto_scan	Web server vulnerability scanner. Findings auto-added to session.
sqlmap_scan	SQL injection scanner. Injection points and databases extracted. SQLi findings auto-added to session.
wpscan_analyze	WordPress vulnerability scanner. Version, plugins, vulnerabilities.

Active Directory / SMB (9)

Tool	Description
nxc_scan	NetExec — the Swiss army knife. Protocols: smb/ldap/winrm/mssql/ssh/rdp/ftp/vnc/wmi. First-class support for: credential testing, user/share/group enum, password policy, SAM/LSA/NTDS dumping, command execution (wmiexec/smbexec/atexec), module execution (lsassy, spider_plus, mimi_sekurlsa, nanodump, zerologon, petitpotam, etc.), password spraying, file upload/download. Admin access (Pwn3d!) auto-recorded as critical findings. Dumped hashes auto-added to session.
enum4linux_scan	Windows/Samba enumeration. Extracts users, shares, groups, password policy into structured data.
bloodhound_ingest	BloodHound data collection via bloodhound-python. Supports separate dc_host (FQDN) and dc_ip (DNS) parameters, --disable-autogc.
impacket_tool	Run any Impacket tool. Auto-parses secretsdump (NTLM hashes), GetNPUsers (AS-REP hashes), GetUserSPNs (TGS hashes). Handles special characters in passwords. Also supports dacledit, psexec, wmiexec, smbexec, atexec, getTGT, getST, rpcdump, lookupsid, findDelegation, and all others.
evil_winrm	WinRM shell. One-shot command execution or interactive session. Supports pass-the-hash and PS script loading.
kerbrute	Kerberos user enumeration and password spraying. Valid creds auto-added to session.
certipy_scan	AD Certificate Services (ADCS) enumeration and exploitation. Finds ESC1-ESC8 vulnerable templates, auto-adds findings.
responder	LLMNR/NBT-NS/mDNS poisoner. Captures NTLM hashes. Runs as background job.
bloody_ad	bloodyAD — AD privilege escalation via DACL/ACE manipulation. Supports getObjectAttributes, setAttribute, addUser, changePassword, addUserToGroup, setShadowCredentials, setGenericAll, setOwner, setRbcd, and more.

Cracking (3)

Tool	Description
hydra_attack	Online brute-forcing. Parsed credentials auto-added to session.
john_crack	Offline hash cracking. Cracked creds auto-added to session.
hashcat_crack	GPU-accelerated cracking. Parsed output with status/speed. Cracked passwords auto-added to session. Supports async.

Exploitation (3)

Tool	Description
metasploit_run	Run MSF modules via resource script. Async support.
searchsploit	Search Exploit-DB. Structured JSON results.
msfvenom_generate	Generate payloads with any format, encoder, and platform.

C2 / Sliver (10)

Tool	Description
sliver_listener	Start/stop/list listeners: mTLS, HTTP, HTTPS, DNS, WireGuard.
sliver_generate	Generate session or beacon implants for Windows/Linux/macOS. All architectures, formats (exe/shared/shellcode), evasion options.
sliver_sessions	List active sessions, beacons, or jobs with optional filtering.
sliver_use	Run commands on a session/beacon via RC script. Supports ALL implant commands including armory extensions (seatbelt, rubeus, nanodump, etc.). Use execute -o instead of shell for command output. Console noise auto-stripped.
sliver_kill	Kill sessions, beacons, or jobs.
sliver_profiles	Create, list, or generate from implant profiles.
sliver_stager	Generate staged payloads with stage listener setup.
sliver_server	Manage sliver-server daemon: start/stop/restart, create operators, multiplayer mode.
sliver_armory	List, search, and install armory extensions and aliases.
sliver_command	Generic escape hatch for any Sliver console command via RC script.

Remote Desktop (10)

Tool	Description
rdp_connect	Connect to target via RDP. Auto-detects xfreerdp3 vs xfreerdp. Kerberos auth disabled by default (avoids KDC errors). Supports drive sharing, admin mode, cert ignore.
vnc_connect	Connect to target via VNC. Supports password auth and view-only mode.
desktop_screenshot	Take a screenshot and return it as an image Claude can see (base64 ImageContent). Auto-starts Xvfb for headless environments. Auto-fixes X auth via xhost. Capture full desktop or specific window.
desktop_type	Send keyboard input via xdotool. Type text or press keys (Return, ctrl+c, alt+F4, etc.). Target specific windows.
desktop_click	Mouse clicks at coordinates. Left/right/middle button, double-click support.
desktop_mouse_move	Move cursor to specific coordinates.
desktop_windows	List all open windows with title, ID, position, and size.
desktop_focus	Focus/activate a specific window by name or ID.
desktop_clipboard	Get or set clipboard contents via xclip.
desktop_disconnect	Close RDP/VNC sessions by job ID or window name (uses xdotool windowclose, not pkill).
desktop_unlock	Unlock the Kali desktop if screen is locked. Optionally disables screensaver/lock for the session.

Tunneling / Pivoting (5)

Tool	Description
chisel	TCP/UDP tunnel. Start server on Kali or client for SOCKS5 proxy, local/reverse port forwards. Accepts port shortcut and string booleans.
ligolo	Ligolo-ng tunneling proxy. Start proxy, create TUN interfaces, add routes for internal subnets.
proxychains_run	Run any command through a SOCKS proxy. Auto-generates temp config or uses existing one.
sshuttle	VPN-over-SSH tunnel to route traffic through compromised hosts. No client needed on target.
socat_relay	TCP/UDP port relay and forwarding.

GUI (7)

Tool	Description
launch_burp	Start Burp Suite (GUI or headless).
burp_api	Interact with Burp REST API: start scans, get sitemap, export issues.
launch_wireshark	Start Wireshark GUI or tshark headless capture.
tshark_analyze	Analyze pcap files: protocol stats, conversations, filtered output.
launch_bloodhound_gui	Start BloodHound GUI with Neo4j. Optional data import.
bloodhound_query	Run Cypher queries against Neo4j. 7 presets for common AD queries (shortest path to DA, kerberoastable, ASREProastable, unconstrained delegation, DCSync rights, high-value targets).
screenshot	Capture desktop or specific window to file.

Command Execution (4)

Tool	Description
execute_command	Run any shell command. Structured output: {stdout, stderr, exit_code, runtime_ms}. Pipes, redirects, everything. Supports async. Max 3600s timeout. Note: Avoid pkill -f as it can match and kill the MCP process itself — use killall by process name instead.
get_job	Check status/results of a background job.
list_jobs	List all background jobs with status and runtime.
cancel_job	Cancel a running background job (SIGTERM).

Session State (10)

Tool	Description
set_engagement	Initialize engagement with name, scope, and working directory. enforce_scope: true blocks tool calls targeting IPs outside scope.
get_session	Full session overview: hosts, creds, findings, notes, stats by severity.
add_host	Manually add/update a host. Also auto-populated by nmap, ping_sweep, nikto, sqlmap, nxc.
add_credential	Record a credential. Also auto-populated by hydra, john, hashcat, nxc, kerbrute, impacket (secretsdump/GetNPUsers/GetUserSPNs).
add_finding	Record a vulnerability with severity. Evidence is optional. Also auto-populated by nikto, sqlmap, certipy, impacket, nxc (Pwn3d! = critical).
add_note	Free-text note with category.
save_session	Persist session to JSON file (0600 permissions).
load_session	Restore a saved session.
generate_report	Generate a Markdown engagement report: scope, hosts table, credentials table, findings grouped by severity, notes. Written with 0600 permissions.
export_loot	Export credentials to attack-ready files: passwords.txt, ntlm_hashes.txt (hashcat -m 1000), asrep_hashes.txt (m 18200), krb5tgs_hashes.txt (m 13100), creds.csv.

Support Services (2)

Tool	Description
start_listener	ncat TCP listener as a background job to catch reverse shells/callbacks. Optional keep-open and TLS. Poll get_job for received data.
smb_share	Host a directory over SMB via impacket-smbserver (background job). Serve payloads to targets, or require auth to capture NTLMv2 hashes from incoming connections.

---

How It Works

Structured Output

Every typed tool parses its output into structured JSON. Instead of Claude reading raw terminal text, it gets data it can reason over:

nmap_scan(target="10.10.10.5", ports="445,3389,5985")
->
{
  "hosts": [{
    "addresses": [{"addr": "10.10.10.5", "type": "ipv4"}],
    "ports": [
      {"port": 445, "state": "open", "service": {"name": "microsoft-ds"}},
      {"port": 3389, "state": "open", "service": {"name": "ms-wbt-server"}},
      {"port": 5985, "state": "open", "service": {"name": "wsman"}}
    ]
  }]
}

Claude sees "445 open + 5985 open" and decides: "SMB + WinRM available, try nxc for cred testing, then evil-winrm for shell."

NetExec — Full Integration

NetExec is implemented as a first-class tool with dedicated parameters for all major features instead of stuffing everything into additional_args:

# Enumerate shares and users
nxc_scan(protocol="smb", target="10.10.10.5", username="admin", password="Pass1", enum="shares,users")

# Dump SAM hashes (auto-added to session)
nxc_scan(protocol="smb", target="10.10.10.5", username="admin", password="Pass1", sam=true)

# Run module
nxc_scan(protocol="smb", target="10.10.10.5", username="admin", password="Pass1", module="lsassy")

# Password spray (continue after success)
nxc_scan(protocol="smb", target="10.10.10.0/24", username="users.txt", password="Spring2024!", continue_on_success=true)

# Execute command
nxc_scan(protocol="smb", target="10.10.10.5", username="admin", password="Pass1", execute="whoami", exec_method="wmiexec")

# Dump NTDS
nxc_scan(protocol="smb", target="10.10.10.5", username="admin", password="Pass1", ntds="drsuapi")

Admin access (Pwn3d!) is automatically recorded as a critical finding. Dumped hashes are auto-added as credentials.

Auto-Discovery Pipeline

Tools automatically populate session state as they find things:

nmap_scan    ->  session.add_host()         # discovered hosts with ports
hydra/john   ->  session.add_credential()   # cracked passwords
hashcat      ->  session.add_credential()   # cracked hashes
secretsdump  ->  session.add_credential()   # dumped NTLM hashes
GetNPUsers   ->  session.add_credential()   # AS-REP hashes
             +   session.add_finding()      # "AS-REP Roastable" finding
GetUserSPNs  ->  session.add_credential()   # TGS hashes
             +   session.add_finding()      # "Kerberoastable" finding
nikto        ->  session.add_finding()      # web vulnerabilities
sqlmap       ->  session.add_finding()      # SQL injection
certipy      ->  session.add_finding()      # ADCS ESC1-ESC8
nxc          ->  session.add_credential()   # validated credentials
             +   session.add_finding()      # admin access (Pwn3d!)
             +   session.add_credential()   # SAM/NTDS hashes
kerbrute     ->  session.add_credential()   # sprayed passwords

Nothing is silently lost. Call get_session() at any point for a full engagement overview.

Async Jobs

Long-running commands don't block. Set async_job: true on any tool that supports it:

nmap_scan(target="10.10.10.0/24", ports="-", async_job=true)
-> {job_id: "a1b2c3d4", status: "submitted"}

get_job(job_id="a1b2c3d4")
-> {status: "running", runtime_ms: 45000}

get_job(job_id="a1b2c3d4")
-> {status: "completed", result: {stdout: "...", exit_code: 0}}

On timeout, partial output is captured and returned instead of being discarded.

Remote Desktop Interaction

Claude can see and interact with remote desktops through the Kali VM:

1. rdp_connect(target="10.10.10.5", username="admin", password="Pass1")
   -> {status: "connected", job_id: "xyz"}

2. desktop_screenshot()
   -> [ImageContent: base64 JPEG Claude can see]

3. desktop_type(text="whoami", key="Return")
   -> {status: "sent"}

4. desktop_screenshot()  # see the result

• Auto-detects xfreerdp3 vs xfreerdp for correct flag syntax
• Kerberos auth disabled by default (avoids KDC unreachable errors)
• DISPLAY and XAUTHORITY automatically set for SSH sessions
• desktop_unlock available if screen locks during operations
• Works with Xvfb for headless Kali VMs (auto-detected and started)

Sliver C2 Integration

Three execution modes based on what Sliver actually supports:

• RC scripts (sliver-client console --rc file.rc) for server operations (listeners, generate, profiles). All scripts auto-append exit to prevent hanging.
• RC scripts with use <id> for session interaction, which enables armory extensions (seatbelt, rubeus, etc.)
• Direct shell for server daemon management

Console noise (banners, prompts, status lines) is automatically stripped from output.

Known Limitations:

• shell command doesn't work via RC scripts — use execute -o cmd.exe /c "command" instead
• portfwd and socks5 are ephemeral (destroyed when RC script exits) — use chisel/ligolo for persistent tunneling
• When passing flags to target executables via execute, wrap in cmd.exe /c to avoid flag collision with Sliver's parser

Tunneling / Pivoting

Reach internal networks through compromised hosts:

# Start chisel server on Kali
chisel(mode="server", port=8080, reverse=true)

# After uploading chisel client to target via sliver:
# Target runs: chisel client KALI_IP:8080 R:socks

# Now route tools through the proxy
proxychains_run(command="nmap -sT 10.10.10.0/24", proxy="socks5 127.0.0.1 1080")

Or use sshuttle for transparent tunneling, ligolo-ng for TUN-based routing, or socat for simple port relays.

Note: Python asyncio tools (like bloodyAD) bypass proxychains' libc hooks. Use non-asyncio tools through proxychains, or use Sliver's port forwarding for specific ports.

---

Safety Guardrails

• Scope enforcement (opt-in): set_engagement(name="...", scope=["10.10.10.0/24"], enforce_scope=true) makes the server reject recon/AD/web/exploit tool calls whose target IP literals fall outside scope — a guardrail against an agent wandering off-target. C2/tunneling/desktop tools are exempt (listener and relay IPs are legitimately foreign), and hostnames are allowed since they can't be verified without DNS.
• Secret redaction: credentials passed via --password/-password/password= or URL userinfo (user:pass@host) are redacted from the audit log, list_jobs, and get_job output.
• Output truncation: tool output is capped at 200 KB per call so a single nmap -p- or NTDS dump can't flood the client's context. The truncation marker tells you to re-run with output redirected to a file.
• Process-group kill: timeouts and cancel_job terminate the entire process group (SIGTERM, then SIGKILL after 5 s), so shell-wrapped children like nmap or responder don't survive as orphans.
• Session files (which contain credentials) are written with 0600 permissions.

---

Output Parsers

Built-in parsers extract structured data from tool output:

Parser	Extracts
parse_nmap_xml	Hosts, ports, services, OS, scripts from nmap XML
parse_ffuf_json	URLs, status codes, sizes from ffuf JSON
parse_gobuster_output	Paths, status codes, sizes from gobuster/dirb text
parse_nikto_output	Server info and vulnerability findings
parse_sqlmap_output	Injection points and discovered databases
parse_hydra_output	Cracked credentials (host, port, service, user, pass)
parse_john_output	Cracked hash:password pairs
parse_hashcat_output	Cracked hashes, GPU speed, progress status
parse_wpscan_output	WordPress version, plugins, vulnerabilities
parse_nxc_output	Hosts, shares, hashes, admin access, success/failure per target
parse_enum4linux_output	Users, shares, groups, password policy
parse_secretsdump_output	SAM hashes, NTDS hashes, LSA secrets, DPAPI keys
parse_getnpusers_output	AS-REP roastable users with hashes
parse_getuserspns_output	Kerberoastable SPNs with TGS hashes

---

Project Structure

server.py                Main entry point - stdio MCP server + auto-provisioning
executor.py              Async subprocess runner with job management
session.py               Engagement state: hosts, creds, findings
requirements.txt         Single dependency: mcp>=1.0.0
requirements-dev.txt     Test dependencies: pytest, mcp
pytest.ini               Test configuration
tools/
  registry.py            Central tool registry, dispatch, and scope-enforcement gate
  parsers.py             14 output parsers for structured data extraction
  _recon.py              nmap, ping_sweep
  _web.py                gobuster, ffuf, dirb, nikto, sqlmap, wpscan
  _ad.py                 nxc, enum4linux, bloodhound, impacket, evil-winrm, kerbrute, certipy, responder, bloodyAD
  _cracking.py           hydra, john, hashcat
  _exploit.py            metasploit, searchsploit, msfvenom
  _sliver.py             10 Sliver C2 tools
  _desktop.py            10 remote desktop interaction tools + unlock
  _tunneling.py          chisel, ligolo, proxychains, sshuttle, socat
  _command.py            execute_command, job management
  _session.py            Engagement session tools + report/loot export
  _services.py           ncat listener, SMB share hosting
  _gui.py                Burp, Wireshark, BloodHound, screenshots
tests/
  test_parsers.py        Parser tests with realistic tool output samples
  test_session.py        Session state, scope matching, save/load
  test_executor.py       Execution, timeouts, jobs, cancellation, redaction
  test_registry.py       Tool registration and the scope-enforcement gate
  test_loot_report.py    Report renderer and loot exporter
SYSTEM_PROMPT.md         Behavioral instructions for Claude during engagements
CLAUDE.md                Project-specific Claude Code instructions
claude_code_config.json  Example Claude Code MCP configuration

Tests

pip install -r requirements-dev.txt
python -m pytest          # 54 tests: parsers, session, executor, registry, loot/report

The suite runs cross-platform for development, but the server itself targets Kali Linux — two POSIX-only tests (process-group semantics, POSIX argv quoting) are skipped on Windows and execute on Kali.

Behavioral Prompt

SYSTEM_PROMPT.md tells Claude how to behave during engagements:

• Start every engagement with set_engagement(..., enforce_scope=true) and stop immediately if a call is blocked as out-of-scope
• State what it's doing before each tool call
• Summarize findings after each call (not raw output dumps)
• Stop after 3 failed attempts and ask before continuing
• Auto-record findings and credentials to session
• Follow pentest methodology: recon -> enum -> vuln assessment -> exploitation -> post-ex
• Not repeat scans already in session state
• Prefer typed tools over execute_command
• Use async jobs for scans > 2 minutes
• Test discovered credentials immediately against other services
• Handle truncated output by re-running to a file instead of guessing
• Deliver payloads via smb_share, catch callbacks via start_listener
• Close out with export_loot + generate_report

Copy SYSTEM_PROMPT.md content into your project's CLAUDE.md to activate.

Requirements

• Kali Linux with standard tools installed
• Python 3.10+
• mcp package (pip install mcp)
• SSH access from your Claude Code machine to Kali (key-based recommended)

Optional Tool Dependencies

Category	Packages
Core (pre-installed on Kali)	nmap, gobuster, ffuf, nikto, sqlmap, hydra, john, hashcat, metasploit, netexec, enum4linux, impacket, responder, evil-winrm, chisel, socat, proxychains4
C2	sudo apt install sliver
Tunneling	sudo apt install ligolo-ng sshuttle
AD	pip install bloodyAD, sudo apt install certipy-ad, kerbrute
Desktop	sudo apt install xdotool xclip scrot xvfb (for headless)
Auto-provisioned	SharpCollection (/opt/SharpCollection/), Chisel Windows (/opt/chisel-windows/chisel.exe)

Contributing

See CONTRIBUTING.md for dev setup, how to add a tool, and the rules of the road. The test suite (python -m pytest) must stay green.

License

MIT — see LICENSE. Use it, fork it, ship it. Just stay legal: authorized testing only.