Skip to content

Repository files navigation

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.

About

Native stdio MCP server for Kali Linux pentesting - 72 typed tools, structured JSON output, engagement session state, Sliver C2, desktop interaction, tunneling. Authorized testing only.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages