mcp-server-zap

Python MCP server for OWASP ZAP — Docker-first, extensible, ~37 tools.

A Model Context Protocol server that exposes OWASP ZAP as tools for Claude Code, Claude Desktop, Cursor, Continue, and any other MCP-compatible LLM client. Spider, active scan, fuzzing, brute force, intercept, schema-driven scanning, the Automation Framework, regex search, and HTML/JSON/Markdown/SARIF reporting — all driven from natural-language conversation.

flowchart LR
    Client[Claude / Cursor / Continue]
    Server[mcp-server-zap]
    ZAP[OWASP ZAP daemon]
    Target[Target Application]

    Client -- "MCP (stdio or HTTP)" --> Server
    Server -- "ZAP REST API" --> ZAP
    ZAP -- "HTTP proxy / scans" --> Target

Why this server?

In April 2026 the OWASP ZAP project shipped an official MCP add-on that runs inside the ZAP process with a deliberately limited tool set. If you primarily drive ZAP from its desktop GUI and want one-click MCP, install that add-on.

This project is the alternative for teams that prefer a Python, Docker-first deployment with broader API coverage and explicit auth:

Both projects target the same API. Pick the one that matches your workflow.

Authorized Use Only

This is a security-testing tool. Use it only on systems you own or have written permission to test. Brute-force, fuzzing, and active-scan tools generate traffic indistinguishable from a real attack. Misuse is illegal in most jurisdictions and is solely the operator's responsibility.

Features

• Crawl — Spider and AJAX spider for SPA-heavy targets.
• Scan — Active vulnerability scanning, passive scan status, scan policies and scanner controls.
• Schema import — OpenAPI, GraphQL, SOAP, and Postman collections feed the scanner.
• Attack — Parameter fuzzing and login brute-force.
• Intercept — Toggle break mode, add URL-pattern breakpoints.
• Auth and context — ZAP contexts, sessions, session-token introspection.
• Search — Regex over recorded requests and responses for secret-leak hunting.
• Automation — Run ZAP Automation Framework YAML plans end-to-end.
• Report — HTML, JSON, Markdown, themed templates, and SARIF for GitHub Code Scanning.

Quick Start

Option A — uvx (recommended for local Claude clients)

1. Run a ZAP daemon

docker run -u zap -p 8080:8080 -i ghcr.io/zaproxy/zaproxy:stable \
  zap.sh -daemon -host 0.0.0.0 -port 8080 \
  -config api.disablekey=true \
  -config api.addrs.addr.name=.* -config api.addrs.addr.regex=true

For non-localhost or multi-user setups, drop api.disablekey=true and set ZAP_API_KEY.

2. Add the MCP server

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zap": {
      "command": "uvx",
      "args": ["mcp-server-zap"],
      "env": {
        "ZAP_URL": "http://localhost:8080",
        "ZAP_API_KEY": ""
      }
    }
  }
}

Claude Code:

claude mcp add zap -- uvx mcp-server-zap

Cursor / Continue / other MCP clients use the same JSON shape under their mcpServers block.

Option B — Docker Compose (bundles ZAP + MCP server)

git clone https://github.com/Karacali/mcp-zap.git
cd zap-mcp
cp .env.example .env  # set MCP_API_KEY
docker compose up -d

This spins up ZAP and mcp-server-zap on the same network. The MCP server exposes the HTTP transport on 127.0.0.1:8765. Auto-remap rewrites localhost targets to host.docker.internal so you can scan apps running on your dev machine from inside the container.

Connect a remote-MCP-aware client to http://127.0.0.1:8765/ with Authorization: Bearer $MCP_API_KEY.

For local debugging (binds ZAP UI to localhost:8080):

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

3. Try it

Run a spider scan against https://target.example.com
What's the status of the active scan?
List High-risk alerts
Search responses for "api_key|token|secret"
Generate an HTML report

Environment Variables

Tool Reference

Example Scenario

A typical conversation that runs an end-to-end scan:

You: Open https://juice-shop.example via the proxy and start a spider on it.
Claude: [calls open_url, then spider_scan → returns scan_id 0]

You: How's the spider going?
Claude: [calls spider_status with scan_id=0 → "100%, 184 URLs found"]

You: Now run an active scan on the same target.
Claude: [calls active_scan → scan_id 1]

You: Show me the High-risk alerts when it's done.
Claude: [polls active_scan_status, then get_alerts(risk_level="High")]

You: Generate an HTML report.
Claude: [calls generate_html_report → writes ./reports/zap-report.html]

Troubleshooting

Local Development

git clone https://github.com/Karacali/mcp-zap.git
cd zap-mcp

# uv (recommended)
uv sync --all-extras
uv run mcp-server-zap

# or pip
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
mcp-server-zap

Quality gates:

uv run pytest -q
uv run ruff check src tests
uv run pyright src

Security

For responsible-disclosure procedures and reporting vulnerabilities in this MCP wrapper, see SECURITY.md. ZAP itself is maintained by OWASP — vulnerabilities in ZAP go to the ZAP project.

Contributing

See CONTRIBUTING.md. PRs welcome — run ruff, pyright, and pytest before submitting.

License

MIT.