MCP ZAP Server lets AI agents run guided, self-hosted ZAP security workflows through MCP with operator controls.
Start, stop, and monitor guided crawls using HTTP Spider, Client Spider, or AJAX Spider, with optional prepared auth sessions.
Start, stop, and monitor guided active scans with optional scan policy and form-login auth.
Import OpenAPI/Swagger, GraphQL, and SOAP WSDL definitions to prepare API endpoints for testing.
Check passive scan backlog and wait for it to drain.
Read grouped findings summaries and drill into detailed alert instances.
Generate, preview, and page through HTML/JSON reports with checksum verification.
List, inspect, export, and create release or customer handoff evidence from scan history.
Prepare and validate operator-managed authentication sessions for browser or form-login profiles.
Operate with API-key/JWT auth, tool scopes, policy bundles, rate limits, quotas, audit events, and conservative URL/network guardrails.
Provides tools for managing and executing web security scans using OWASP ZAP, including spidering, active scanning, passive scanning, API imports, findings, and reports.
Note This project is not affiliated with or endorsed by the ZAP project. It is an independent implementation.
mcp-zap-server exposes 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
one guided tool catalog with queue-managed scan starts, findings baselines, reports and explicit operator recovery
Full documentation: danieltse.org/mcp-zap-server
An experimental headless Apple Silicon package bundles Java and ZAP for HTTP workflows. It is a maintainer-built local preview; public downloads are not available, and supplied previews are unsigned. The private ChatGPT connection guide explains Secure MCP Tunnel prerequisites and access to a local scanner.
Watch the demo: browser demo or YouTube
Prerequisites:
Docker 20.10+
Docker Compose v2 or newer (docker compose) with --wait and --wait-timeout support
your own MCP client with Streamable HTTP and custom-header support
This source selects image v0.17.1. Verify that the matching
GitHub release and Linux AMD64/ARM64
images are published before starting it. Until then, use the published v0.16.0
release or build local source through the contributor setup. Read the
0.17.1 upgrade guide before changing
an existing installation. Settings and selected versions are preserved; set
IMAGE_TAG in .env deliberately when upgrading.
Prefer to ask Codex to handle setup? Manually install the optional MCP ZAP Connect plugin, then ask it to check prerequisites, start the Docker stack, configure your private MCP connection and verify status. The skill can help install missing prerequisites with your approval, then recheck and continue setup. Scanning is a separate request. The commands below remain available without the plugin.
For Cursor Desktop Free, follow the guided Cursor setup. Use a local Agent chat with available Cursor allowance to set up the scanner, check status, then request a demo crawl and report separately.
Claude Code local preview uses the same scanner and setup skill in a local Claude Code session.
For Claude Desktop Free, follow the download, setup and first-scan guide.
The macOS MCPB preview adds agent-callable setup tools around the same Docker
scripts and reuses existing installations. Choose a
scanner release that includes
the Desktop .mcpb, matching guide and checksum files. If those assets are not
listed, use the local build instructions.
This extension is separate from the Claude Code plugin.
git clone https://github.com/dtkmn/mcp-zap-server.git
cd mcp-zap-server
./bin/bootstrap-local.sh --startThis creates missing settings, preserves existing keys and workspace data,
and starts a versioned release image. It reports ready after container health
and authenticated MCP checks pass. The packaged client uses * for the curated
guided tools; run scans only when requested. Existing settings retain their
permissions. See
quick-start permissions
for the default and optional per-client restrictions.
Use Self-Serve First Run for version selection, configuration, stopping/restarting, startup timeouts, and recovery. For source builds, use the contributor setup.
Connect your MCP client:
MCP endpoint for host-side clients: http://localhost:7456/mcp
Authentication: send MCP_API_KEY from .env in the X-API-Key header
The stack runs the MCP server, ZAP, and demo targets. Install and configure your preferred MCP client separately.
After connecting, try this first prompt:
Use the guided ZAP tools to crawl http://juice-shop:3000. Wait for the crawl
and passive analysis to finish, show a findings summary, generate an HTML
report, and read it back through MCP. Do not run an active scan.Expect a completed crawl, a findings summary, and a report the client can
read. Use the container URL http://juice-shop:3000 for this scan; the host
preview http://localhost:3001 is for your browser. Finding counts vary;
a connection or scan error is not a clean result.
The default stack binds published ports to loopback. Review Quick Start Security before changing access or scan-target settings. Agent install notes cover setup permissions and standalone OCI use.
Related MCP server: Security Scanner MCP Server
This source includes 0.17.1 MCP Registry metadata in
.mcp/server.json. Metadata in source does not publish a
registry version or image. Check the
MCP Registry
and use metadata from the same published version as the image you deploy.
The image includes the MCP server name expected by registry and catalog tooling.
The published 0.16.0 version and its immutable digest remain documented in the
0.16.0 release guide.
Docker Compose remains the easiest installation path because the MCP server is designed to operate with a ZAP sidecar and explicit auth keys. The OCI package metadata is for advanced standalone installs where ZAP is already running and reachable from the MCP container.
Guided scans: intent-first tools for spider, active scan, passive scan, API imports, findings, reports, and scan history.
Guided tool catalog: policy inspection, authentication setup and queued scan operations with status and stop controls.
Authentication: API key mode by default, optional JWT mode with refresh and revocation support.
Runtime policy bundles: configured dry-run and enforcement modes for guided tool calls.
Scan queue and history: queued active, traditional spider, AJAX Spider, and Client 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.
See the Client Spider guide for browser setup, authenticated guided crawling and reports.
The 0.17.1 release and upgrade guide
describes neutral recorded-findings responses, authoritative explicit target
denies, permission-aware next actions, and the local client setup options.
Publication of the tag, images, registry version and Desktop downloads must be
verified separately in GitHub Releases.
Use a version with verified published images until the matching distribution is available.
The v0.17.0 GitHub release is incomplete: its Desktop assets are absent and
its image-release workflow did not complete. See the upgrade guide for availability checks.
See the 0.16.0 release and upgrade guide for that release's behavior and requirements.
See the 0.15.0 release and upgrade guide for that release's behavior and requirements.
See the 0.14.0 release and upgrade guide for that release's behavior and requirements.
The release notes archive and changelog cover earlier versions. For changes to older MCP integrations, use Upgrading to Guided Tools. Verify the matching image and distribution in GitHub Releases before deployment.
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.
For a first private AWS deployment without Kubernetes, use AWS EC2 with Docker Compose and its standalone example.
For Kubernetes, use the EKS infrastructure starter to create a dedicated evaluation cluster in an existing VPC, then deploy with the existing Helm chart. Follow the walkthrough for network configuration, JWT authentication, persistent storage and deployment checks.
Production and shared deployments should review:
flowchart LR
Client["Your MCP Client"] -->|"MCP over Streamable HTTP"| MCP["MCP ZAP Server"]
MCP -->|"ZAP API"| ZAP["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:
The extension API exposes selected contracts for policy, protection, evidence and metadata integrations:
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 shows how a separate project depends on the API artifact.
Extensions do not add runtime multi-engine support. Additional scanner engines require their own adapters and explicit capability boundaries.
Start here:
Scanning:
Operations:
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 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
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.
Apache License 2.0. Copyright 2025-2026 Daniel Tse. See LICENSE.
Start a guided active scan for a specific target host or base URL after crawl/import setup. The server decides direct versus queued execution from deployment topology. When authSessionId is supplied, guided attack currently accepts prepared form-login sessions only.
Inputs: targetUrl (required), policy, recurse, authSessionId, +1 more.
Get status for a guided active-scan operation.
Inputs: operationId (required).
Stop a guided active-scan operation.
Inputs: operationId (required).
Prepare a guided auth session from an operator-managed profile. Use a kind=browser profile for Client Spider, or kind=form for HTTP spider and active scans. The requested target must remain on the profile's authorized origin.
Inputs: profileId (required), targetUrl (required).
Validate a prepared guided auth session before authenticated crawl or attack flows.
Inputs: sessionId (required).
Start a guided crawl for a target host or root URL. The server decides direct versus queued execution from deployment topology. Use strategy=http for traditional server-rendered sites, strategy=client for JavaScript-driven apps using Client Spider, or strategy=browser for the existing AJAX Spider API. strategy=auto starts with HTTP Spider; only an unauthenticated direct HTTP start failure triggers AJAX fallback. Auto does not detect JavaScript coverage. Client Spider requires the Client Side Integration add-on and headless Firefox. Prepared browser authentication sessions require strategy=client; prepared HTTP form-login sessions require http or auto.
Inputs: targetUrl (required), strategy, authSessionId, idempotencyKey.
Get status for a guided crawl operation.
Inputs: operationId (required).
Stop a guided crawl operation.
Inputs: operationId (required).
Drill into findings after reading the summary. Requires a nonblank target baseUrl covered by scan evidence visible to the caller. By default this returns grouped details for matching alerts. Set includeInstances=true when you need bounded raw alert occurrences with concrete URLs, params, evidence, or attack samples.
Inputs: baseUrl (required), limit, pluginId, alertName, +1 more.
Read currently recorded alerts, including while scan work is in progress, as a concise grouped risk summary for fast triage. Alert counts do not establish scan completion, coverage, or safety. Requires a nonblank target baseUrl covered by scan evidence visible to the caller.
Inputs: baseUrl (required).
Get passive scan backlog and completion status.
Inputs: no named parameters.
Wait for the passive scan backlog to drain before reading findings or generating reports.
Inputs: pollIntervalMs, timeoutSeconds.
Generate a human-shareable report artifact using guided defaults. Use this after passive scan backlog drains when you want an export or handoff artifact; use findings summary/details for interactive triage.
Inputs: theme, format, baseUrl.
Preview a generated report artifact through MCP after zap_report_generate. If truncated, use zap_report_read_chunk to retrieve the complete artifact in bounded pages.
Inputs: reportPath (required), maxChars.
Retrieve a generated UTF-8 report in bounded JSON pages. Append content in order, follow nextOffset until endOfFile=true, and supply the first page's artifactSha256 as expectedSha256 on later pages. Offsets and maxChars count Unicode code points. Artifacts are limited to 50 MiB; the SHA-256 identifies the full original UTF-8 file.
Inputs: reportPath (required), offset, maxChars, expectedSha256.
Generate a customer-safe Markdown handoff summary from scan history without raw internal IDs, backend references, workspace IDs, or metadata.
Inputs: limit, target, handoffName.
Export scan history as inline JSON text for internal evidence processing; no export file is created. Use zap_scan_history_list for a readable listing, zap_scan_history_release_evidence for a summary bundle, or zap_scan_history_customer_handoff for a customer-facing summary. Returns version, generatedAt, retentionDays, entryCount, and entries containing scan/job/artifact records, including internal IDs, paths, and metadata; review before sharing. Only records accessible to the caller in the current workspace are included, newest first. Omitted or blank filters select all accessible records; supplied filters combine with AND. The snapshot is capped by limit, has no pagination, and returns an empty entries array when nothing matches. It does not start scans or contact targets. Querying may delete expired stored ledger entries under the configured retention policy; it does not refresh scan outcomes from ZAP.
Inputs: limit, status, target, evidenceType.
Read one scan history or release-evidence entry by ID.
Inputs: entryId (required).
List recent scan history and release-evidence entries, including queued scans, direct scan starts, and generated report artifacts.
Inputs: limit, status, target, evidenceType.
Export a release or pilot handoff evidence bundle with summary counts, target coverage, warnings, and bounded ledger entries.
Inputs: limit, target, releaseName.
Import an OpenAPI/Swagger definition, GraphQL schema, or SOAP WSDL to prepare API endpoints for testing. Use when you have an API definition; use zap_crawl_start to discover ordinary web pages. Requires a reachable, configured ZAP instance with the matching OpenAPI, GraphQL, or SOAP add-on. Import changes the current ZAP session and may send requests to the definition source and API targets; use only authorized targets. It does not start an active scan: after reviewing import messages, call zap_attack_start with the API target URL only when active testing is permitted and approved. Content mode accepts actual OpenAPI JSON/YAML text with a required full HTTP(S) hostOverride and an explicitly enabled shared filesystem; it cannot read chat attachments automatically. Returns plain text containing definition type, source kind, and import status. URL/file mode also includes source and engine messages; content mode withholds contents, internal paths, and raw engine warning text. Review warnings before proceeding. Invalid inputs, blocked URLs, and ZAP API failures raise errors.
Inputs: source (required), sourceKind (required), definitionType (required), endpointUrl, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 21 tools
Crawl, attack, passive scan, auth, report, findings, and history operations are generally well separated by distinct resource+action names. The main overlap is within scan history (list/get/export/release_evidence/customer_handoff) and report_read vs report_read_chunk, but descriptions clarify their roles. A few boundary cases remain, such as choosing among history export variants, which adds mild confusion.
All tools consistently use the zap_ prefix followed by snake_case resource/action naming (e.g., zap_crawl_start, zap_attack_stop, zap_findings_summary). Verb and resource ordering is predictable throughout, with no mixed casing or style deviations.
At 21 tools, the count is on the heavy side but reasonable for a security scanning domain that must cover crawl, attack, auth, reports, findings, import, and history workflows. Each tool appears to serve a distinct lifecycle operation, though the history surface is somewhat expansive.
The surface covers the core lifecycle well: crawl/attack start-stop-status, passive scan wait/status, auth prepare/validate, target import, findings summary/details, report generation/reading, and history inspection/export. Minor gaps exist, such as no explicit alert disposition/false-positive management or session cleanup/configuration tools, but core workflows are covered.
Security scanner for AI-written code: SAST, secrets, dependencies, IaC, containers and DAST.
Autonomous AppSec & DAST scanner across 12 security domains (260+ controls) with 3-Layer Triage.
Authorized security scans, evidence, fix prompts and retests for AI-built web apps.
Zero-config MCP security scanner for AI-generated apps. 25K+ vulnerability patterns.
