🕷️ OWASP ZAP MCP Server

Drive the world's most popular web app scanner from your AI assistant.

Point Claude, Cursor, or any MCP client at OWASP ZAP and run real crawls, authenticated scans, and vulnerability triage — through 67 curated, safety-gated tools built straight from the official ZAP API.

Quick start · See it in action · The 67 tools · Authenticated scanning · Security · Responsible use

⚡ See it in action

Once it's connected, you drive ZAP in plain language. The model picks the right tools and chains them — no REST calls, no ZAP UI:

💬 You: Crawl https://juice-shop.herokuapp.com, run an active scan, and summarise what you find.

Behind that one sentence, the assistant orchestrates the toolchain:

①  zap_access_url            seed the target into ZAP's site tree
②  zap_spider_scan       🎯  crawl for pages, forms, and parameters
③  zap_active_scan       🎯  attack the discovered surface (SQLi, XSS, …)
④  zap_get_alerts_summary    triage findings by severity
⑤  zap_generate_report       export a shareable HTML report

🤖 Assistant: Crawled 41 URLs and completed the active scan. Findings by severity — High: SQL injection on /rest/products/search; Medium: missing CSP and reflected XSS; plus several low-severity header issues. Full report written to /zap/wrk/report.html.

Every attack-capable step (🎯) is checked against the target-authorization policy first, so the model physically cannot fire a scan at an out-of-scope or cloud-metadata host — regardless of what it's asked to do.

Related MCP server: VibeDefender MCP Server

✨ Why this exists

Talking to ZAP's raw REST API from an LLM is clumsy and risky: hundreds of endpoints, no guardrails, and it's easy to point an attack at the wrong host. This project gives your AI assistant a small, opinionated, safe surface:

🔐 Safe by design

• Cloud metadata endpoints (169.254.169.254) are always refused

• Optional scope allowlist + private-range blocking

• Control port bound to localhost by default

🔑 Real authenticated scanning

• Full workflow: context → auth method → indicators → user → forced-user

• scan_as_user for spider, AJAX spider, and active scan

• The thing most ZAP wrappers skip entirely

🧱 Reliable under load

• One pooled async client, bounded retries with backoff

• Typed errors + a uniform result envelope

• A single bad call can never crash the server

🚢 Production posture

• Fail-closed config, secrets never logged

• Pinned, non-root, health-gated containers

• Green CI on every push

🏗️ Architecture

flowchart LR
    A["🤖 LLM client<br/>(Claude · Cursor)"] -->|MCP / Streamable HTTP<br/>127.0.0.1:8000| B
    B["🕷️ zap-mcp-server<br/>67 tools · target policy<br/>pooled async client"] -->|internal docker net<br/>http://zap:8080| C
    C["🛡️ zap-daemon<br/>OWASP ZAP 2.17.0<br/>API restricted to private ranges"]
    B <-->|shared volume<br/>/zap/wrk| D["📁 zap-wrk<br/>reports · imports"]
    C <-->|shared volume<br/>/zap/wrk| D
    B -.->|refuses metadata / out-of-scope| X["⛔ blocked targets"]

• The MCP server reaches ZAP over the internal Docker network.

• Both ports are published on 127.0.0.1 only — nothing is world-exposed.

• Every state-changing ZAP action requires the API key.

• Shared /zap/wrk volume. ZAP resolves every file path in its API against its own filesystem, so both containers mount the same volume at the same path. This is what makes file-based tools work end to end: the agent stages an input (HAR, OpenAPI spec, URL list, automation plan) for ZAP to read, and reads back reports ZAP writes. A one-shot wrk-init service prepares the directory as 1000:1000 mode 2775 (setgid) before ZAP starts; the MCP server joins gid 1000 via group_add, so both unprivileged users can read and write there and new files inherit the shared group automatically.

The optional all-in-one image collapses this into one container: same components and the same MCP endpoint, but ZAP is reached over loopback and /zap/wrk is just a local directory, so no volume sharing is needed. See Quick start.

🚀 Quick start

Fastest path — one image, zero config:

docker build -f Dockerfile.allinone -t zap-mcp-server:all-in-one .
docker run -d --name zap-mcp -p 127.0.0.1:8000:8000 zap-mcp-server:all-in-one

No .env, no API key to invent — ZAP's API is bound to loopback inside the container and its key is generated at startup. First boot takes ~60–90s while ZAP's JVM warms up; wait for healthy, then you're live at http://localhost:8000/mcp:

docker inspect --format '{{.State.Health.Status}}' zap-mcp   # -> healthy

That green status is meaningful: the container reports healthy only when both ZAP's API and the MCP endpoint answer.

For real engagements, the two-container compose setup is recommended — independently upgradable ZAP, and restarting the server won't discard a live scan session.

Which setup should I use?

Running two processes in one container is normally an anti-pattern, so the parts that usually break are handled explicitly:

• s6-overlay is PID 1 — reaps orphaned processes and forwards signals, rather than backgrounding with & and leaking zombies.

• Ordered startup — services run apikey → zap → zap-ready → mcp-server. The zap-ready gate polls ZAP's API and only then starts the MCP server, which is the single-container equivalent of compose's depends_on: service_healthy.

• No degraded state — if ZAP never becomes ready the container exits non-zero instead of serving an MCP endpoint with a dead scanner behind it.

• Self-healing — if either process dies, s6 restarts it.

• Clean shutdown — docker stop exits 0 in ~3s; s6's grace periods are kept under Docker's 10s SIGKILL deadline.

• Unprivileged — s6 sets up as root, then both ZAP and the MCP server drop to uid 1000. Neither runs as root.

• Pinned supervisor — s6-overlay is fetched by version and checksum-verified at build time.

Overridable via -e: ZAP_API_KEY (use a fixed key), ZAP_STARTUP_TIMEOUT (readiness budget, default 300s), plus the usual ZAP_TARGET_ALLOWLIST / ZAP_BLOCK_PRIVATE_TARGETS scope controls.

🅑 Compose (recommended for real use)

# 1. Set your secret (never committed)
cp .env.example .env
#    edit .env -> ZAP_API_KEY=<long-random-value>

# 2. Launch (ZAP starts, becomes healthy, then the MCP server starts)
docker compose up -d --build

# 3. Confirm
docker compose ps                    # both services: healthy
docker compose logs -f mcp-server    # "Registered 67 MCP tools"

Connect your client

Either option serves the same endpoint, so the client config is identical:

{
  "mcpServers": {
    "owasp-zap": { "url": "http://localhost:8000/mcp" }
  }
}

🔑 Authenticated scanning in 6 steps

The capability most ZAP wrappers skip — scan behind a login:

1. create_context ─────────────► scope it (include app, exclude /logout)
2. set_authentication_method ──► e.g. formBasedAuthentication
3. set_logged_in / out_indicator
4. new_user → set_user_credentials → set_user_enabled
5. set_forced_user (+ mode)  ──► keeps the session alive during scans
6. spider_scan_as_user → active_scan_as_user

Prefer repeatable runs? Drive the whole pipeline with a ZAP Automation Framework plan via zap_run_automation_plan.

🧰 The 67 tools

Tools marked 🎯 are gated by the target-authorization policy. Every tool returns a uniform envelope: {"status":"success",...} or {"status":"error","code":...,"retryable":...}.

All tool names are prefixed with zap_ (e.g. zap_active_scan).

🛡️ Security model

🧪 Development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
pytest -q          # policy, config, error envelope, tool behavior

CI runs py_compile + pytest on every push to main.

⚖️ Responsible use

Active scanning is an attack. In most jurisdictions, testing systems without permission is illegal. Before you scan:

• ✅ Confirm the target is in scope for an engagement you're authorized to run

• ✅ Pin scope with ZAP_TARGET_ALLOWLIST; consider ZAP_BLOCK_PRIVATE_TARGETS=true

• ✅ Use a long random ZAP_API_KEY; never commit .env

Cloud metadata endpoints are always refused and this cannot be overridden.

📄 License

MIT © Neeraj829784 — swap the LICENSE file for Apache-2.0 if you want an explicit patent grant.