README.md

July 27, 2026 · View on GitHub

MCP ZAP Server

Give AI agents a safe, self-hosted OWASP ZAP operator for guided web security scans, findings, reports, and production guardrails.

GitHub tag GitHub license

Note This project is not affiliated with or endorsed by OWASP or the OWASP ZAP project. It is an independent implementation.

mcp-zap-server exposes OWASP ZAP through MCP over streamable HTTP so agentic tools can run operator-controlled security workflows without brittle glue scripts or unsafe scanner access.

Use it when you want:

safe agentic scanning with guided defaults for spider, active scan, passive scan, API imports, findings, and reports
operator control through API-key or JWT auth, tool scopes, runtime policy bundles, rate limits, and audit events
self-hosted deployment with Docker Compose for local adoption and Helm for Kubernetes
expert ZAP access when you intentionally need lower-level ZAP context, user, scan, and report controls

Full documentation: danieltse.org/mcp-zap-server

Watch the demo: browser demo or YouTube

Quick Start

Prerequisites:

Docker 20.10+
Docker Compose v2 (docker compose)
an MCP-capable client, or the bundled Open WebUI client

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

./bin/bootstrap-local.sh
./dev.sh
./bin/self-serve-doctor.sh

Those scripts are the supported local happy path, not hidden magic:

bootstrap-local.sh creates .env, generates local API keys, and prepares the ZAP workspace.
dev.sh starts the Docker Compose stack with the faster JVM image.
self-serve-doctor.sh checks Docker, auth, MCP initialize, tools/list, guided tools, and a harmless tool call.

The JVM image remains Java 25 end to end: source compilation, bytecode, and runtime all target Java 25. Its final runtime is distroless, so it intentionally contains no shell, package manager, or curl. A small built-in HTTP probe keeps the normal Docker Compose health status; docker compose ps still reports the MCP service as (healthy) after startup.

Then open:

Open WebUI: http://localhost:3000
MCP endpoint for host-side clients: http://localhost:7456/mcp
Cursor config example: examples/cursor/mcp.json

When scanning the bundled demo targets, use the container URLs that ZAP can reach from inside Compose:

Juice Shop scan target: http://juice-shop:3000
Petstore scan target: http://petstore:8080

The default Compose stack publishes host ports on 127.0.0.1 only. Set MCP_ZAP_BIND_ADDRESS=0.0.0.0 only when you intentionally expose the stack behind trusted network controls.

Client setup:

There are two independent authentication layers. The API key or JWT lets Cursor call MCP ZAP Server. An optional target-auth profile lets ZAP log in to an application you are authorized to scan. Most first runs need only the MCP API key; never put a target website password in Cursor or an MCP prompt.

Discovery Metadata

This repository includes MCP Registry metadata in .mcp/server.json. The v0.11.0 Docker images are labeled with the MCP server name expected by registry and catalog tooling.

Docker Compose remains the easiest installation path because the MCP server is designed to operate with an OWASP ZAP sidecar and explicit auth keys. The OCI package metadata is for advanced standalone installs where OWASP ZAP is already running and reachable from the MCP container.

What You Get

Guided scans: intent-first tools for spider, active scan, passive scan, API imports, findings, reports, and scan history.
Expert ZAP control: optional lower-level tools for advanced ZAP context, user, scan, and report workflows.
Authentication: API key mode by default, optional JWT mode with refresh and revocation support.
Runtime policy bundles: dry-run and enforcement support through zap_policy_dry_run and policy-mode configuration.
Scan queue and history: queued active, spider, and AJAX Spider jobs with claim-based recovery, durable Postgres state, and evidence export.
Extension contracts: experimental policy, protection, evidence metadata, and extension metadata APIs with sample extension packaging.
Operational guardrails: request body limits, rate limits, workspace quotas, tool-scope authorization, structured logs, metrics, and audit events.
Deployment paths: local Docker Compose, published JVM container images, and Helm charts for Kubernetes.

Latest Release

v0.11.0 modernizes the runtime and container supply chain without changing MCP tool names or input schemas:

gateway-core and its WebFlux adapter move to 0.8.0, with application data binding migrated to Jackson 3 and managed by the Jackson 3.2.1 BOM
the final Java 25 image is built on a Cosign-verified, digest-pinned distroless runtime with a shell-free HTTP health probe
the unsupported native-image deployment facade is removed; use the versioned JVM image or Helm
main CI no longer publishes rolling main or sha-* images; stable AMD64 and ARM64 images are published only from GitHub immutable-release events
no database migration or authentication configuration change is required; the container remains UID/GID 1000, now stated explicitly in Helm

Read the full notes:

Security Defaults

The default posture is intentionally conservative:

api-key mode is the base runtime default.
none mode is for explicit local dev/test only.
Docker Compose binds published ports to loopback by default.
The Java 25 JVM image uses a digest-pinned distroless runtime with no shell or package manager; debug it through logs, metrics, and external diagnostic containers rather than installing tools into the application container.
URL validation blocks localhost, private networks, and link-local targets by default.
Target authentication is optional and profiles default to an empty list. When enabled, guided auth binds an exact server-side credential reference and login settings to one approved origin; callers provide only profileId and targetUrl.
Public auth exchange endpoints are rate-limited.
MCP request bodies have a hard early size cap.

Production and shared deployments should review:

Architecture

flowchart LR
  Client["Open WebUI / MCP Client"] -->|"MCP over Streamable HTTP"| MCP["MCP ZAP Server"]
  MCP -->|"ZAP API"| ZAP["OWASP ZAP"]
  ZAP -->|"scan"| Target["Authorized target app"]
  MCP -->|"reports / findings / history"| Evidence["Evidence + reports"]

For multi-replica queueing, durable Postgres state, claim recovery, and ingress affinity, use the operations docs instead of this README:

Extension Model

ZAP is the first scanner engine, not the whole product boundary. The current public extension work is intentionally small:

mcp-zap-extension-api packages selected policy, protection, evidence, and metadata contracts without gateway runtime internals.
How extensions work explains the core versus extension boundary.
Build your own extension shows the target standalone repository shape.
Extension API release policy explains publication stages and compatibility gates.
Standalone sample extension proves a separate project can compile against the API artifact.

This is not runtime multi-engine support yet. Additional scanner engines need an adapter design and explicit fail-closed capability boundaries before they become product claims.

Documentation Map

Start here:

Scanning:

Operations:

Open Source Core And Extension Model

mcp-zap-server is the Apache-2.0-licensed open-source core. It is intended to be useful on its own for self-hosted MCP and OWASP ZAP workflows.

Private or enterprise capabilities may be built as separate extensions around this core. Those extensions are not required to run the OSS project, and enterprise implementation code is not shipped in this repository.

The boundary is intentional:

this repository remains the public OSS distribution
extension points should be documented and kept stable where practical
private extensions must not weaken the security, licensing, or usability of the OSS core
security scanning and open-source program entitlements for this repository apply only to this public project

Contributing And Support

If this project saves you time or becomes part of your security workflow, you can sponsor the maintainer to support ongoing maintenance.

Agentic Lab offers optional paid support for teams adopting the public core in production. Commercial support is separate from the Apache-2.0-licensed OSS distribution, and the public core should remain usable without private extensions or paid services.

Contact Agentic Lab