mcpnuke

MCP Red Teaming & Security Scanner

Security scanner for Model Context Protocol servers. Combines static metadata analysis with active behavioral probing — connects to MCP servers, enumerates tools/resources/prompts, calls tools with safe payloads, and analyzes what comes back.

Works against standard MCP (SSE, Streamable HTTP), local stdio servers (npx, python, etc.), non-standard tool servers (POST /execute), and Kubernetes-internal MCP deployments.

Use with DVMCP for training, or point at any MCP server in dev/staging/prod.

See CHANGELOG.md for recent changes and planned work.

Contents

On this page

• Install
  • To use mcpnuke
  • To work on mcpnuke
• Quick Start
• How It Works
• Security Checks
• Identity Lanes & Transports
• CLI Reference
• Kubernetes Deployment
• Exit Code
• Authorized Use
• Contributing
• License

Reference

Ecosystem

agentic-sec — architecture, walkthroughs and cross-project guides for camazotz + nullfield + mcpnuke.

mcpnuke and stoneburner meet at the agent. mcpnuke scans the MCP server — whether the tools will do the dangerous thing. stoneburner grades the model — whether the model will ask them to. An attack chain needs both halves, so the tools complement rather than overlap: mcpnuke's --chain-replay proves the server half, stoneburner's adversarial / toolcall suites measure the model half. Neither scans the other's layer.

Install

To use mcpnuke

One-liner:

curl -LsSf https://raw.githubusercontent.com/babywyrm/mcpnuke/main/install.sh | bash

Picks uv tool, pipx or pip --user, whichever you have. All three install mcpnuke into its own environment, so its dependency pins cannot disturb the rest of your Python. Pass --extras all for the optional features, or --dry-run to see the plan first.

Or install it yourself:

uv tool install mcpnuke          # recommended
pipx install mcpnuke
pip install --user mcpnuke

Verify:

mcpnuke --doctor

Optional extras: ai (Claude analysis), server (the mcpnuke-runner HTTP job API), all (everything). The scanner itself, Kubernetes checks included, needs none of them — uv tool install 'mcpnuke[all]' if you want the lot.

To work on mcpnuke

git clone https://github.com/babywyrm/mcpnuke.git && cd mcpnuke
./quickstart.sh

Creates a .venv, installs every extra including dev, runs the test suite and prints usage. After that ./scan and uv run mcpnuke both work with no activation, because uv run finds the project venv on its own.

Manual equivalents:

uv sync --all-extras                              # uv
python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[all,dev]"

Quick Start

New to mcpnuke? Try the DVMCP Walkthrough — a hands-on guide that scans 10 vulnerable MCP servers and explains every finding, or run ./walkthrough/demo.sh for the fully automated version.

# Single target
./scan --targets http://localhost:2266

# DVMCP challenges 1–10
./scan --port-range localhost:9001-9010 --verbose

# Authenticated endpoint (JWT, PAT, etc.)
./scan --targets https://api.githubcopilot.com/mcp/ --auth-token-file ./token

# OIDC auto-token (Keycloak, etc.)
./scan --targets http://localhost:9090/mcp \
  --oidc-url http://keycloak:8080/realms/myapp \
  --client-id myapp --client-secret SECRET \
  --oidc-resource http://localhost:9090/mcp

# JSON report for CI (includes proof-ranked priority_actions + impact/fix/verify,
# OWASP MCP Top 10 alignment, and an AIBOM-style inventory per target)
./scan --port-range localhost:9001-9010 --json report.json

# Suggest a NullfieldPolicy from findings (proved chains → DENY sink + HOLD sources)
./scan --targets http://localhost:8080/mcp --generate-policy fix.yaml

# Differential scan (compare to baseline)
./scan --targets http://localhost:9001 --baseline baseline.json

# Scan a local MCP server via stdin/stdout (no proxy needed)
./scan --stdio 'npx -y @modelcontextprotocol/server-everything'

# Fast scan (~2min vs ~30min) — static checks read the full catalog; probes sample the top 5
./scan --targets http://localhost:9090 --fast --verbose

# AI-powered analysis (Claude, AWS Bedrock, or local Ollama)
./scan --targets http://localhost:9002/sse --claude --verbose
./scan --targets http://localhost:9002/sse --ollama-analysis http://<ollama-host>:11434

# Run tests
uv run pytest tests/ -v

All ./scan commands also work as uv run mcpnuke (no activation needed), mcpnuke (with venv activated), or .venv/bin/mcpnuke.

More recipes — DPoP + token introspection + JWKS hardening, grouped findings, parallel probes, Ollama ensembles, K8s discovery, per-lane reporting, production safety passes — in QUICKSTART.md.

Exit codes: 0 clean at the --fail-on threshold, 1 findings at or above it, 2 scan error. Full table under Exit Code.

SARIF output: Use --sarif results.sarif to emit a SARIF 2.1.0 report for GitHub Code Scanning, VS Code, and IDE integration. Findings map as: CRITICAL/HIGH — error, MEDIUM — warning, LOW — note. Each result carries the same impact, fix, and verify text as the console priority action, and the rule help repeats it.

See CI/CD Integration Guide for GitHub Actions, GitLab CI, and mcpnuke-runner setup.

How It Works

1. CONNECT        Detect transport (SSE, Streamable HTTP, stdio, or custom tool server)
2. ENUMERATE      initialize → tools/list → resources/list → prompts/list
                  (or probe tool names for non-MCP /execute APIs)
3. STATIC CHECKS  Pattern-match metadata (names, descriptions, schemas)
4. PROBE          Call tools with safe payloads, read resources
5. ANALYZE        Scan responses for injection, exfil, leakage, drift
6. AGGREGATE      Detect attack chains across findings
7. REPORT         Priority actions (fix first) + console/JSON (+ optional policy)

Scan Phases

The scanner runs checks in a deliberate order:

Which checks run in each phase, and under what conditions, is in docs/checks.md.

How the probes are built, how findings are scored and chained, and how to test all of it against DVMCP, is in docs/methodology.md.

Security Checks

mcpnuke runs 104 checks across static, behavioral, infrastructure and aggregate phases, covering 54 of 57 threat IDs (95%) in the agentic-sec threat taxonomy. See docs/checks.md for the full inventory with severities and detection notes.

Identity Lanes & Transports

Every lane-scoped finding carries an identity lane (1–5, the who: human-direct → anonymous) and a transport (A–E, the how: MCP JSON-RPC through native LLM function-calling), resolved automatically from the agentic-sec taxonomy. --by-lane groups findings per lane. --owasp maps them onto the OWASP MCP Top 10 (2025) alignment view. --coverage-report intersects them with a live camazotz lane corpus. tests/owasp_lab is the positive fixture for that report, one planted marker per category. tests/reference_target is the quiet server, and those markers stay out of it.

Full tables and reporting guide: docs/lanes.md.

CLI Reference

Every flag, its argument group, and the environment variable that backs it: docs/cli-reference.md, generated from the parser so it cannot drift.

• Scan modes (--fast, --safe-mode, --no-invoke) and how --fast picks which tools to sample: docs/scan-modes.md
• --claude, --bedrock and --ollama-analysis, and what the AI layer adds over the deterministic checks: docs/ai-analysis.md

Kubernetes Deployment

mcpnuke also deploys as a K8s Job to scan cluster-internal MCP services and audit the Kubernetes posture from inside. Manifests, RBAC, the in-cluster check list and CronJob scheduling: docs/kubernetes.md.

Exit Code

The exit code reports the --fail-on threshold, not the raw finding count. A scan that reports only LOW findings exits 0 under the default threshold.

--fail-on any exits 1 on any finding at all; --fail-on none always exits 0, for informational scans.

Authorized Use

mcpnuke actively probes targets. By default it calls tools and sends injection and SSRF payloads, which on a real server can create data or trigger outbound requests. Multi-step chain replay (--chain-replay) is off unless you ask for it.

Only scan systems you own or have written authorization to test.

Against anything you do not control, start with --no-invoke (static-only, never calls a tool), then --safe-mode (skips tools classified dangerous) once you know the blast radius. Full guidance, plus how to handle the sensitive output a scan produces, is in SECURITY.md.

Contributing

Bug reports about detection quality — false positives and false negatives — are the most valuable contribution, because operator trust in the output is what makes the tool worth running.

Setup, the check-authoring recipe, severity calibration, and the invariants the test suite guards: CONTRIBUTING.md. Working with an AI coding agent (Codex, Cursor, etc.)? It should read AGENTS.md first.

To report a vulnerability in mcpnuke itself, use private reporting as described in SECURITY.md rather than a public issue.

License

MIT © babywyrm