Kali Ethical Hacking MCP Server

A personal, advanced Model Context Protocol (MCP) server for authorized penetration testing and ethical hacking. It lets an MCP client (Claude Desktop, Claude Code) drive the standard Kali/pentest toolchain — reconnaissance, scanning, web application testing, exploitation support, credential work, and reporting — with authorization scoping, exploitation gating, and audit logging enforced on every action.

Built on the Red Hat template-mcp-server (FastMCP, tools-first architecture).

⚠️ Authorized use only

This server operates real offensive security tooling. Use it only against systems you own or have explicit, written authorization to test. Unauthorized scanning, exploitation, or credential attacks are illegal in most jurisdictions. The server enforces an engagement scope and refuses to act on targets you have not declared as authorized — keep REQUIRE_SCOPE=True. You are responsible for operating within the law and your rules of engagement.

How it works

Claude (MCP client)  ──►  Kali MCP Server  ──►  ┌─ host binary (nmap on PATH)        [mode: host]
                          (scope + audit)        └─ Kali container (docker exec ...)  [mode: docker]

• Hybrid execution — each tool runs on a host binary if present, otherwise inside a persistent kalilinux/kali-rolling container the server starts on demand (missing tools are apt-installed into it automatically). Controlled by EXECUTION_MODE (auto | host | docker).
• Scope enforcement — every active tool validates its target against your declared engagement scope (ScopeManager). Out-of-scope targets are refused.
• Exploitation gating — active exploitation / brute-force tools (sqlmap, hydra) additionally require ALLOW_EXPLOITATION=True.
• Audit logging — every invocation is appended to ~/.kali-mcp/audit.jsonl.
• Engagement session — scans and findings are recorded and can be rendered into a report.

Tool catalog (24 tools)

Category	Tools
Recon & Scanning	nmap_scan, masscan_scan, host_discovery, dns_recon, subdomain_enum, whois_lookup
OSINT (passive)	username_osint (Sherlock), email_harvest (theHarvester)
Web App Testing	nikto_scan, dir_bruteforce, vhost_enum, whatweb_fingerprint, nuclei_scan, sqlmap_test†, wpscan_scan
Exploitation & Creds	searchsploit_lookup, hash_identify, hash_crack, hydra_bruteforce†
Reporting & Workflow	scope_manage, list_tools_status, record_finding, session_summary, generate_report

† Gated behind ALLOW_EXPLOITATION=True and an in-scope target.

Requirements

• Python 3.12+ and uv
• Docker (for the Kali fallback). No security tools need to be installed on the host — they run in the Kali container. If you do have tools on your PATH, they're used directly.

Install

uv venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env   # then review the settings

Run

stdio (local — for Claude Desktop / Claude Code):

MCP_TRANSPORT_PROTOCOL=stdio kali-mcp-server

HTTP (shared / remote):

MCP_TRANSPORT_PROTOCOL=http MCP_PORT=5001 kali-mcp-server

Connect it to Claude

Claude Code:

claude mcp add kali-ethical -- /ABSOLUTE/PATH/ethical-mcp/.venv/bin/kali-mcp-server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kali-ethical": {
      "command": "/ABSOLUTE/PATH/ethical-mcp/.venv/bin/kali-mcp-server",
      "env": { "MCP_TRANSPORT_PROTOCOL": "stdio", "EXECUTION_MODE": "auto" }
    }
  }
}

Typical workflow

1. Authorize the engagement — record who approved it and the reference:

   scope_manage(action="set_engagement", client="Acme", authorized_by="J. Smith", ticket="PT-42")
   

2. Declare scope — only targets you're permitted to test:

   scope_manage(action="add", targets=["10.0.0.0/24", "app.acme.com"])
   

3. Check tooling — list_tools_status() shows host vs Docker availability.
4. Recon & scan — nmap_scan("app.acme.com", "service"), subdomain_enum("acme.com"), …
5. Web testing — nikto_scan(...), nuclei_scan(...), dir_bruteforce(...).
6. Exploitation (only with ALLOW_EXPLOITATION=True) — sqlmap_test(...), hydra_bruteforce(...).
7. Record & report — record_finding(...) then generate_report("markdown").

Anything against a target not in scope is refused; gated tools are refused unless explicitly enabled.

Configuration

Key settings (see .env.example for all):

Variable	Default	Purpose
MCP_TRANSPORT_PROTOCOL	stdio	stdio, http, streamable-http, sse
EXECUTION_MODE	auto	auto | host | docker
KALI_DOCKER_IMAGE	kalilinux/kali-rolling	Fallback toolbox image
REQUIRE_SCOPE	True	Refuse out-of-scope targets
ALLOW_EXPLOITATION	False	Enable active exploitation/brute-force tools
TOOL_TIMEOUT_SECONDS	300	Per-run timeout
DATA_DIR	~/.kali-mcp	Scope, audit log, outputs, wordlists

Safety model

• No target contact without scope. Recon/scan/exploit tools call the scope gate first.
• Two-key exploitation. sqlmap/hydra need ALLOW_EXPLOITATION=True and an in-scope target.
• Rate limits. masscan packet rate is capped to avoid turning a scan into a flood.
• Full audit trail. ~/.kali-mcp/audit.jsonl records every command (incl. blocked attempts).
• No DoS / mass-internet scanning helpers. The toolset is engagement-scoped by design.

Development

make test     # run the test suite
make lint     # ruff + formatting checks
pytest tests/ # scope, executor, gating, reporting tests

License

Apache-2.0. This tool is provided for authorized security testing and education only.