Kali MCP

An ethical hacking toolkit that connects AI agents to Kali Linux security tools via MCP (Model Context Protocol).

Compatible with any AI agent that supports MCP: Claude Code, Gemini CLI, OpenCode, Cursor, Copilot, Codex, Aider, Windsurf, goose, and others.

> /kali-start 192.168.1.50

  SESSION INITIALIZED
  Target:  192.168.1.50
  Scope:   Passive + Credential testing
  Dir:     sessions/192_168_1_50_20260331_1430/

> /kali-audit 192.168.1.50

  Scanning with nmap...
  PORT    SERVICE       VERSION
  22/tcp  ssh           OpenSSH 8.9
  80/tcp  http          Apache 2.4.54
  443/tcp https         nginx 1.18
  445/tcp microsoft-ds  Samba 4.15

  Launching 10 parallel sub-agents...
    [Service Enum :22]  -> SSH scripts, searchsploit CVEs
    [Service Enum :80]  -> nikto, gobuster, ffuf, dirb
    [Web Dirs :80]      -> ffuf directories, sensitive files
    [Web Fuzz :80]      -> arjun params, nuclei templates
    [OSINT :80]         -> whatweb, wafw00f, searchsploit
    [API Testing :80]   -> IDOR, auth bypass
    [Auth Testing :80]  -> SQLi on login, JWT analysis
    [SMB Enum :445]     -> crackmapexec, enum4linux, smbclient
    [AD Audit :445]     -> impacket, kerberoast
    [Vuln Scan]         -> nmap vuln scripts, nuclei

  All sub-agents completed. Results saved to session assets.

> /kali-finish

  SESSION FINALIZED — 14 findings (2 Critical, 4 High, 5 Medium, 3 Low)
  Report: sessions/192_168_1_50_20260331_1430/findings.md

Prerequisites

• Docker and Docker Compose (v2+)
• An AI agent with MCP support (see Compatibility)
• A terminal with curl (used by init.sh to health-check the container)

Getting Started

1. Clone and start

git clone https://github.com/pabpereza/kali-mcp.git
cd kali-mcp
./init.sh

init.sh builds the Kali Docker image, starts the container, and waits until the MCP server is healthy at http://localhost:666/mcp. First build may take several minutes.

2. Launch your AI agent

Open your agent from the project directory so it auto-detects .mcp.json:

claude          # Claude Code (recommended — supports parallel sub-agents)
gemini          # Gemini CLI
opencode        # OpenCode

3. Start hacking

You can use natural language or slash commands:

> Scan ports on 10.10.10.5 with version detection
> Find hidden directories on http://target.com
> Check if FTP allows anonymous login on 10.10.10.5

Typical Workflow (Claude Code)

The whole workflow is three commands: start, audit, finish. There are no standalone per-tool commands — for anything ad hoc outside this flow, just ask in natural language (e.g. “check if FTP allows anonymous login on 10.10.10.5”) and the agent runs the matching tool directly.

/kali-start 10.10.10.5          # 1. Select target and scope
/kali-audit 10.10.10.5          # 2. Run the audit/pentest (parallel sub-agents)
/kali-finish                    # 3. Double-check + consolidated report + knowledge consolidation

Step 1: Initialize (/kali-start)

The start command asks two questions:

1. Target(s) — IP, hostname, URL, or CIDR range
2. Scope — Passive only, Passive + Credentials, or Full pentest

It creates a session directory with the structure:

sessions/10_10_10_5_20260331_1430/
├── session.md      # Metadata: target, date, scope, status
├── targets.md      # Target list and progress
├── findings.md     # Consolidated findings (generated by /kali-finish)
└── assets/         # Raw output from each sub-agent

Step 2: Run the audit (/kali-audit)

Discovers services with nmap, then launches up to 10+ parallel sub-agents (per-port enumeration plus specialized web/AD sub-agents) across two waves — recon/loot first, brute-force/exploitation second, seeded with anything harvested in the first wave. Saves everything to the session’s assets/.

You can re-run /kali-audit against the same target later in the same session (e.g. after fixing a gap) — it reuses the existing IN PROGRESS session directory.

Step 3: Finalize (/kali-finish)

The finish command:

1. Inventories all sub-agent outputs in assets/
2. Double-checks completeness — flags missing or failed sub-agents
3. Compiles deduplicated findings by severity (Critical/High/Medium/Low)
4. Generates the consolidated report in findings.md
5. Updates session.md with executive summary and statistics
6. Consolidates any new, generalizable tool-efficiency lessons into knowledge/

Session output example

After /kali-finish, your session directory looks like:

sessions/10_10_10_5_20260331_1430/
├── session.md                          # Status: COMPLETED, executive summary
├── targets.md                          # Targets with findings count
├── findings.md                         # 14 findings by severity
└── assets/
    ├── nmap_discovery.md               # Initial port scan
    ├── service_enum_port22.md          # SSH audit
    ├── service_enum_port80.md          # HTTP service audit
    ├── web_directory_enum_port80.md    # Hidden directories found
    ├── api_security_port80.md          # API testing results
    ├── auth_session_testing_port80.md  # Auth bypass attempts
    ├── service_enum_port445.md         # SMB audit
    └── vuln_scanning.md                # CVE identification

Architecture

┌─────────────────────────────────────────────────────┐
│  AI Agent (Claude / Gemini / OpenCode / ...)        │
│                                                     │
│  Follows AGENTS.md (single source of truth);        │
│  CLAUDE.md just points Claude Code there            │
│  Uses MCP tools to execute security actions         │
│                                                     │
│  [Claude Code: parallel sub-agents per port]        │
└──────────────────────┬──────────────────────────────┘
                       │ MCP (HTTP) localhost:666
┌──────────────────────┼──────────────────────────────┐
│  Docker: kali-mcp    │                              │
│                      ▼                              │
│  ┌─────────────────────────────────────┐            │
│  │ supergateway :8000                  │            │
│  │ Streamable HTTP    MCP stdio    │            │
│  └──────────────┬──────────────────────┘            │
│                 │                                   │
│  ┌──────────────▼──────────────────────┐            │
│  │ kali-server-mcp :5000 (Flask API)   │            │
│  │                                     │            │
│  │  nmap · gobuster · dirb · nikto     │            │
│  │  sqlmap · hydra · john · wpscan     │            │
│  │  enum4linux · metasploit            │            │
│  │  ffuf · nuclei · crackmapexec       │            │
│  │  whatweb · amass · impacket · ...   │            │
│  │  (50+ tools — see full list below)  │            │
│  └─────────────────────────────────────┘            │
└─────────────────────────────────────────────────────┘

Available Tools

50+ tools across OSINT & recon, web application testing, network & AD pentesting, traffic analysis, password/hash cracking, and forensics — the nmap_scan/hydra_attack/etc. native MCP wrappers are deprecated (unreliable health check, return HTTP 500); every tool is invoked through the single execute_command MCP tool instead.

The full, up-to-date catalog — canonical command per tool, function, and which ones are intrusive — lives in knowledge/tools/index.md, not duplicated here. See Knowledge Base below.

Slash Commands Reference (Claude Code)

Only three commands, by design — see Repository Structure and Knowledge Base for why.

For anything outside this flow (a single ad hoc check, digging into one file, cracking one hash), just ask in natural language — every tool listed below is reachable via execute_command without a slash command.

Authorization Policy

Intrusive tools (sqlmap, hydra, john, metasploit) always require user confirmation before execution.

Three authorization levels:

Compatibility

Note: AGENTS.md is the only file with real content — tools, authorization policy, audit methodology, session system, sub-agent architecture, knowledge base. CLAUDE.md is a one-line pointer that sends Claude Code there, so every agent ends up following the exact same instructions instead of a second, divergent copy.

/kali-start, /kali-audit, /kali-finish are canonically defined once, as runbooks under .claude/commands/. Gemini CLI and OpenCode both support project-local custom slash commands that inject file content, so their adapters under .gemini/commands/ and .opencode/commands/ pull in AGENTS.md + the matching runbook and translate the Claude-only mechanics (parallel sub-agents → sequential steps, AskUserQuestion → plain-text question) — giving native /kali-* invocation there too, off the same source, no duplicated instructions. *OpenCode has its own subagent primitives; if the model judges they can genuinely run tasks in parallel it’s free to use them, but the adapter doesn’t assume it.

Codex CLI’s custom-prompt mechanism (~/.codex/prompts/) is user-home-only, not project-local, and is marked deprecated by OpenAI — it can’t be shipped inside this repo, so there’s no adapter for it. Cursor, GitHub Copilot, Aider, Windsurf, and goose don’t expose a project-shippable custom-command format either as of this writing; on those, just ask in plain text and the agent follows AGENTS.md’s translation notes.

Manual MCP configuration

Most agents auto-detect .mcp.json. If yours requires manual setup, point it to:

{
  "mcpServers": {
    "kali": {
      "type": "http",
      "url": "http://localhost:666/mcp"
    }
  }
}

Supported Services

20 built-in playbooks — HTTP/HTTPS (incl. WordPress), SSH, FTP, SMB/NetBIOS, MySQL, PostgreSQL, MSSQL, SMTP, DNS, RDP, SNMP, LDAP, Kerberos/Active Directory, VNC, Redis, MongoDB, Elasticsearch, Docker API, WinRM, NFS — plus a generic fallback for anything else. Each one is a short “which tool, in what order” checklist in knowledge/protocols/, which is what /kali-audit actually reads at dispatch time — see Knowledge Base.

Repository Structure

kali-mcp/
├── init.sh                  # Bootstrap: build, start, wait for readiness
├── .mcp.json                # MCP endpoint config (auto-detected by agents)
├── AGENTS.md                # Single source of truth: tools, methodology, session system, sub-agent architecture
├── CLAUDE.md                # One-line pointer to AGENTS.md for Claude Code
├── docker/
│   ├── Dockerfile           # Kali Linux image with security tools
│   ├── compose.yml          # Docker Compose service definition
│   └── entrypoint.sh        # Starts Flask API + supergateway
├── .claude/
│   └── commands/            # Canonical runbooks (Claude Code native; source for the adapters below)
│       ├── kali-start.md         # /kali-start — Initialize session
│       ├── kali-audit.md         # /kali-audit — Full audit/pentest (10+ sub-agents)
│       └── kali-finish.md        # /kali-finish — Finalize + consolidated report + knowledge
├── .gemini/
│   └── commands/            # Gemini CLI adapters — inject AGENTS.md + the matching runbook
│       ├── kali-start.toml
│       ├── kali-audit.toml
│       └── kali-finish.toml
├── .opencode/
│   └── commands/            # OpenCode adapters — inject AGENTS.md + the matching runbook
│       ├── kali-start.md
│       ├── kali-audit.md
│       └── kali-finish.md
├── knowledge/                # Knowledge base (git-tracked, OKF format)
│   ├── index.md
│   ├── log.md
│   ├── tools/                # How to use each tool: full catalog + per-tool efficiency notes
│   └── protocols/            # Which tool(s) for each protocol/application (20 playbooks)
└── sessions/                # Session data (git-ignored)
    └── _/
        ├── session.md
        ├── targets.md
        ├── findings.md
        └── assets/

Knowledge Base

knowledge/ is a small, git-tracked bundle in Open Knowledge Format (markdown + YAML frontmatter), split in two:

• knowledge/tools/ — how to use each tool: the full command reference catalog, plus per-tool notes on running it efficiently (flags, timeouts, wordlists, concurrency, pitfalls) that accumulate as real engagements teach us something.
• knowledge/protocols/ — which tool(s) to reach for on a given protocol or application (SSH, SMB, HTTP/WordPress, MySQL, …), one short checklist per service.

AGENTS.md deliberately holds neither — it’s process and methodology only (authorization policy, audit workflow, session system). This is not a vulnerability or target database either: nothing target-identifying (IP, hostname, credentials) is ever written there, only in the gitignored sessions/.

• /kali-audit reads the matching knowledge/protocols/.md before dispatching each service’s sub-agent(s) and copies its steps into their prompts, and consults knowledge/tools/.md for efficiency notes on top of that.
• /kali-finish distills genuinely new, generalizable efficiency lessons from the session back into knowledge/tools/ — most sessions won’t add anything, and that’s expected. A protocol/application worth a dedicated playbook gets added to knowledge/protocols/ the same way.
• Because it’s plain markdown in git, you can read, edit, or review it like any other part of the codebase.

Troubleshooting

Disclaimer

WARNING: This toolkit is intended exclusively for authorized security testing. Misuse may violate local, national, and international laws.

You must ensure that:

• You have explicit written authorization from the system owner before testing.
• You are operating within the agreed scope of the engagement.
• You understand that intrusive tools can disrupt services, corrupt data, or trigger security alerts.

Acceptable use cases:

• Penetration testing engagements with a signed agreement
• CTF (Capture The Flag) competitions
• Lab environments (HackTheBox, TryHackMe, VulnHub, personal labs)
• Defensive security research

The authors assume no liability for damages caused by misuse. You are solely responsible for your actions.

License

This project is provided as-is for educational and authorized security testing purposes. See individual tool licenses (nmap, sqlmap, metasploit, etc.) for their respective terms.