Pentest MCP Toolkit

Kali security tools driven by an MCP client over Docker stdio. For authorized self-environment pentests of systems you own. You are responsible for authorization.

Pick a tier, run one command, connect your client.

Quick start

50 tools — full verified set (default, recommended)

# one command: checks Docker, builds the image, writes the client config.
# --client <codex|claude-desktop|claude-code|cursor|gemini-cli|lm-studio|open-webui>
curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 50 --client codex

Or build by hand:

git clone https://github.com/KoaBrown/pentest-mcp-toolkit.git
cd pentest-mcp-toolkit
docker build -f docker/Dockerfile.50 -t pentest-mcp-toolkit:50 .
# then write your client config:  bash install/install.sh --tier 50 --client codex

Download/first build pulls Kali + tool packages (~5–10 min). Image ~1.5 GB (metasploit is large). Needs Docker + git + curl on the box.

25 tools — lightweight TCP-only subset

curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 25 --client codex

docker build -f docker/Dockerfile.25 -t pentest-mcp-toolkit:25 .

Faster build, ~370 MB image. No raw-socket or heavy tools.

Related MCP server: redteam-mcp

Connect your client

The canonical launch command (every client speaks stdio, so only the config file + key differs per client):

docker run -i --rm \
  --cap-add=NET_RAW --cap-add=NET_ADMIN \
  -e MCP_PENTEST_SCOPE= \
  -e MAX_OUTPUT=50000 \
  -e CMD_TIMEOUT=300 \
  -e PENTEST_TIER=50 \
  -v "$(pwd)/work:/work" \
  pentest-mcp-toolkit:50

• Claude Desktop / Codex / Claude Code / Cursor / Gemini CLI / LM Studio / Open WebUI — exact file path + snippet in docs/CLIENTS.md. The installer writes it for you: bash install/install.sh --tier 50 --client claude-desktop.

Tier 25: swap :50→:25 and drop the two --cap-add flags.

Scope ⚠️ important

MCP_PENTEST_SCOPE controls where the AI may scan, not whether it may. By default it is empty = the toolkit can scan any host. This matches "any device, no configuring" but means: you are the only authorization check. Tighten it to your lab when scanning real targets:

-e MCP_PENTEST_SCOPE=10.0.0.0/8,192.168.0.0/16,my-lab.local
# or at install time:
bash install/install.sh --tier 50 --client codex --scope 192.168.1.0/24

See docs/ARCHITECTURE.md § Scope guard for the full behavior (IP-in-CIDR, CIDR subnet_of, domain suffix).

Capabilities (raw-socket scans)

Raw-socket scans need both file caps (baked at build time) and the runtime cap on docker run:

The canonical launch command above already includes them. Default nmap_scan is -sT (TCP connect), needs no caps. Tier 25 ships TCP-only by default (no --cap-add needed); setcap on nmap/naabu is baked so you can add the flag.

Tools by tier

Tier 25 (25 tools — lightweight)

Tier 50 (50 tools — everything)

Tier 25 is a strict subset. Tier 50 adds:

Build from source / verify

# syntax check (no deps needed)
python -m py_compile src/_helpers.py src/server.py src/tools/*.py

# MCP round-trip: confirm the tier serves the right tool count
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  docker run -i --rm pentest-mcp-toolkit:50

# full smoke test (init + tools/list + a real tools/call)
python scripts/smoke_test.py --tier both          # hermetic
python scripts/smoke_test.py --tier 50 --net      # + live scanme.nmap.org scan

Architecture

One src/ tree, two Dockerfiles; the PENTEST_TIER env gates which tools register. Tool functions are bare async defs in src/tools/<category>.py; src/server.py applies @mcp.tool() at registration time. The contract — no shell, validate before run, scope guard, strings out, single-line docstrings — lives in docs/ARCHITECTURE.md. Dev rules in docs/CLAUDE.md.

License

MIT. Kali tool licenses are their upstream projects'; this toolkit only packages and orchestrates them.