This MCP server integrates OWASP ZAP with MCP clients and AI assistants to enable automated security testing from your development workflow. It launches ZAP, loads or creates a session, and exposes an MCP endpoint at http://localhost:8082/mcp for clients to connect and issue security scan commands such as Active, Passive, AJAX Spider, and Complete scans. The server also handles automatic URL transformation when running inside container environments, mapping localhost URLs to the appropriate host gateway so your tests target the correct service. You can pair MCP-compatible AI assistants to interpret scan results, annotate findings, and suggest remediation steps, enabling AI-assisted security analysis during development.

To use the server, start it and point your MCP clients at the provided MCP URL. The client can request scans, fetch reports, and review vulnerability details. The configuration supports tuning ZAP and MCP behavior via environment variables, such as enabling autostart of ZAP, setting the MCP port, and adjusting the logging level for debugging. The included Docker/Podman deployment path simplifies containerized usage, while the local Python execution path is ideal for development and testing on a workstation.

Prerequisites:

• Python 3.8+ installed and available on PATH
• OWASP ZAP installed and accessible via PATH (zap.sh or zap.bat)
• Java runtime (OpenJDK 11+ recommended)
• (Optional) Docker or Podman for containerized deployment

Option A: Local installation (Python package)

1. Clone the repository git clone https://github.com/LisBerndt/zap-custom-mcp.git cd zap-custom-mcp

2. Install Python dependencies pip install -r requirements.txt

3. Ensure ZAP is installed and accessible via PATH

   • Verify: zap.sh on Linux/macOS or zap.bat on Windows

4. Run the MCP server locally python -m zap_custom_mcp

Option B: Docker/Podman deployment

1. Clone the repository and navigate to it git clone https://github.com/LisBerndt/zap-custom-mcp.git cd zap-custom-mcp

2. Build and start containers (auto-detects Docker/Podman) ./build.sh ./start.sh

   Windows users can use the provided batch files: build.bat and start.bat

3. Access the MCP endpoint at http://localhost:8082/mcp

Prerequisites for container deployments are documented in DOCKER.md and PODMAN.md within the repository.

Tips and common issues:

• Ensure ZAP_BASE points to the correct ZAP API endpoint. If ZAP runs inside a container, adjust the base URL accordingly.
• The MCP port (ZAP_MCP_PORT) must be exposed and not blocked by firewalls.
• The server will auto-start ZAP if it is not already running; this can take around a minute to initialize fully.
• When running in containers, automatic URL transformation will map localhost URLs to the appropriate host gateway (host.docker.internal or host.containers.internal). If you encounter connection issues, verify that the host gateway mapping is correct for your environment.
• If you need more verbose logs for debugging, set ZAP_LOG_LEVEL to DEBUG.
• The recommended local command for reliability is python -m zap_custom_mcp.