ZAP MCP Server

A powerful Model Context Protocol (MCP) Server that integrates OWASP ZAP (Zed Attack Proxy) with AI assistants and MCP clients. Enable AI-powered security testing through automated vulnerability scanning.

🎯 Why ZAP MCP Server?

Shift Left Security - Empower developers to integrate security testing early in the development lifecycle. Instead of waiting for security reviews at the end of development, developers can now:

🔧 Test during development - Run security scans on localhost applications
🤖 AI-assisted security - Get intelligent vulnerability analysis through AI assistants
⚡ Rapid feedback - Identify security issues before they reach production
🔄 CI/CD integration - Automate security testing in development workflows
📊 Developer-friendly - Simple MCP interface for non-security experts

🚀 Features

🔍 Multiple Scan Types: Active, Passive, AJAX Spider, and Complete scans
⚡ Asynchronous Processing: Background scan execution with real-time status updates
🐳 Docker Support: Easy deployment with Docker Compose
🤖 AI Integration: Seamless integration with MCP-compatible AI assistants
📊 Rich Reporting: Detailed vulnerability reports with risk scoring
🔄 Session Management: Flexible session handling strategies
🛡️ Production Ready: Robust error handling and logging
🔄 Automatic URL Transformation: Automatically maps localhost URLs to container host gateways

📋 Prerequisites

Python 3.8+
OWASP ZAP installed and accessible via PATH
Java (required by ZAP)
Docker or Podman (optional, for containerized deployment)
Firefox ESR (included in Docker/Podman containers for AJAX scans)

📖 For container-specific prerequisites, see:

DOCKER.md - Docker prerequisites and setup
PODMAN.md - Podman prerequisites and setup

🛠️ Installation

Package Structure

This project uses a proper Python package structure (zap_custom_mcp/) which provides several benefits:

✅ Clean imports - Proper module organization
✅ Docker compatibility - Works seamlessly in containers
✅ PyPI ready - Can be published as a proper Python package

Execution methods:

python -m zap_custom_mcp (recommended)
python -m zap_custom_mcp.http_server (alternative method)

Option 1: Local Installation

Clone the repository

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

Install OWASP ZAP
- Download from OWASP ZAP Downloads
- Ensure zap.bat is accessible via PATH
- Test: where zap.bat (Windows) or which zap.sh (Linux/Mac)
Install Python dependencies
```
pip install -r requirements.txt
```

Linux-specific notes

Install Java (OpenJDK 11+ recommended):

# Debian/Ubuntu
sudo apt-get update && sudo apt-get install -y default-jre

# Fedora
sudo dnf install -y java-11-openjdk

Install OWASP ZAP:

# Debian/Ubuntu (from official repos)
sudo apt-get update && sudo apt-get install -y zaproxy

# If not available in your distro repos, download from ZAP website:
# https://www.zaproxy.org/download/

Verify ZAP is on PATH (Linux/Mac):

which zap.sh || echo "zap.sh not found in PATH"

Option 2: Docker/Podman Deployment (Recommended)

🐳 Docker/Podman is the easiest and most reliable method!

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

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

# Windows:
build.bat
start.bat

# 3. Check status
docker-compose ps  # or podman-compose ps

📖 For detailed Docker/Podman setup and localhost scanning instructions, see:

DOCKER.md - Complete Docker setup guide
PODMAN.md - Complete Podman setup guide

✅ AUTOMATIC URL TRANSFORMATION: The server automatically detects Docker/Podman environments and transforms localhost/127.0.0.1 URLs to the appropriate host gateway:

Docker: localhost:3000 → host.docker.internal:3000
Podman: localhost:3000 → host.containers.internal:3000
Local: URLs remain unchanged

This means you can use localhost URLs directly - they will be automatically transformed when running in containers!

⚙️ Configuration

The server uses environment variables for configuration. Key settings:

Variable	Default	Description
`ZAP_BASE`	`http://127.0.0.1:8080`	ZAP API port - Change port by modifying URL
`ZAP_MCP_PORT`	`8082`	MCP server port - Port for MCP client connections
`ZAP_MCP_HOST`	`127.0.0.1`	MCP server host (use `0.0.0.0` for all interfaces)
`ZAP_AUTOSTART`	`true`	Auto-start ZAP if not running
`ZAP_LOG_LEVEL`	`INFO`	Logging level

Custom Port Configuration

Using .env file (Recommended):

# Copy the example file
cp env.example .env

# Edit .env file
ZAP_PORT=8081
ZAP_MCP_PORT=8083
ZAP_BASE=http://127.0.0.1:8081

Using environment variables:

# Set custom ports
export ZAP_PORT=8081
export ZAP_MCP_PORT=8083
export ZAP_BASE="http://127.0.0.1:8081"

# Then start containers
./start.sh

📖 For complete configuration details, see:

DOCKER.md - Docker configuration options
PODMAN.md - Podman configuration options

🚀 Quick Start

🐳 Docker/Podman (Recommended)

Fastest start with containers:

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

# 2. Start (auto-detects Docker/Podman)
# Linux/Mac:
./build.sh && ./start.sh

# Windows:
build.bat
start.bat

# 3. Wait (approx. 90 seconds) and then connect:
# http://localhost:8082/mcp

📖 For detailed setup instructions and localhost scanning, see:

DOCKER.md - Complete Docker guide
PODMAN.md - Complete Podman guide

✅ AUTOMATIC URL TRANSFORMATION: The server automatically detects Docker/Podman environments and transforms localhost/127.0.0.1 URLs to the appropriate host gateway. You can use localhost URLs directly - no manual mapping needed!

💻 Local Installation

1. Start the Server

Recommended method (as package):

python -m zap_custom_mcp

Alternative methods:

# As specific module
python -m zap_custom_mcp.http_server

# Direct execution (legacy, may have import issues)
python zap_custom_mcp/http_server.py

💡 Best Practice: Always use python -m zap_custom_mcp for the most reliable execution.

The server will automatically:

✅ Check if ZAP is running
✅ Start ZAP if needed (via PATH)
✅ Create/load a session
✅ Start the MCP server

⏱️ Important: The server takes approximately 90 seconds to become fully operational after startup. This includes:

ZAP initialization and startup
Session creation
MCP server initialization
All components becoming ready

2. Connect Your MCP Client

Connect to: http://localhost:8082/mcp

MCP Configuration Example

For Cursor IDE, add to your mcp.json:

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

For other MCP clients, use the same URL endpoint.

3. Available Tools

Tool	Description
`start_active_scan`	Run active security scan (Spider + Active)
`start_complete_scan`	Run complete scan (AJAX + Spider + Active + Passive)
`start_passive_scan`	Run passive security analysis
`start_ajax_scan`	Run AJAX spider for modern web apps
`get_scan_status`	Get real-time scan status
`cancel_scan`	Cancel running scan
`list_scans`	List all active scans
`create_new_session`	Create new ZAP session

📖 Usage Examples

Development Workflow Integration

Local Development Testing:

{
  "tool": "start_passive_scan",
  "arguments": {
    "url": "http://localhost:3000",
    "timeout_seconds": 60
  }
}

Pre-Commit Security Check:

{
  "tool": "start_active_scan",
  "arguments": {
    "url": "http://localhost:8080",
    "ascan_max_wait_seconds": 300,
    "spider_max_wait_seconds": 120
  }
}

Localhost Scanning Examples

✅ AUTOMATIC URL TRANSFORMATION: The server automatically detects Docker/Podman environments and transforms localhost/127.0.0.1 URLs:

{
  "tool": "start_complete_scan",
  "arguments": {
    "url": "http://localhost:3000",
    "include_findings": true
  }
}

What happens automatically:

Docker: http://localhost:3000 → http://host.docker.internal:3000
Podman: http://localhost:3000 → http://host.containers.internal:3000
Local: http://localhost:3000 → http://localhost:3000 (unchanged)

📖 For Docker/Podman localhost scanning examples, see:

DOCKER.md - Docker localhost examples
PODMAN.md - Podman localhost examples

Basic Security Scan

💡 Example Target: OWASP Juice Shop - A deliberately vulnerable web application designed for security testing and training.

{
  "tool": "start_complete_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "include_findings": true,
    "include_evidence": false
  }
}

Quick Passive Scan

💡 Perfect for: Quick security assessment without active testing.

{
  "tool": "start_passive_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "timeout_seconds": 300
  }
}

AJAX Spider Scan

💡 Perfect for: Modern web applications with JavaScript/AJAX content.

{
  "tool": "start_ajax_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "maxDuration": 5,
    "maxCrawlDepth": 5,
    "numberOfBrowsers": 1,
    "browserId": "firefox-headless"
  }
}

Note: AJAX scans require Firefox to be installed in the container (included by default). Firefox runs in headless mode without requiring any display server.

Custom Active Scan

💡 Advanced configuration: Custom timeouts and scan policies for thorough testing.

{
  "tool": "start_active_scan",
  "arguments": {
    "url": "https://juice-shop.herokuapp.com/#/",
    "ascan_max_wait_seconds": 3600,
    "spider_max_wait_seconds": 900,
    "scanPolicyName": "Default Policy"
  }
}

🔄 Shift Left Security Integration

Development Workflows

1. Local Development

Test your localhost application during development
Get immediate feedback on security issues
Fix vulnerabilities before committing code

2. Pre-Commit Hooks

Integrate security scans into git pre-commit hooks
Prevent insecure code from entering the repository
Automated security validation

3. CI/CD Pipeline Integration

Add security testing to your build pipeline
Scan staging environments automatically
Generate security reports for each deployment

4. AI-Assisted Security

Use AI assistants to interpret scan results
Get recommendations for fixing vulnerabilities
Learn security best practices through AI guidance

Benefits for Development Teams

⚡ Faster feedback - Catch issues in minutes, not weeks
💰 Cost reduction - Fix issues early when they're cheaper to resolve
🎯 Developer education - Learn security through hands-on testing
🛡️ Proactive security - Build secure applications from the start
📊 Continuous improvement - Regular security assessments

🐳 Container Deployment

📖 For complete container setup and usage instructions, see:

DOCKER.md - Complete Docker setup guide with automatic URL transformation
PODMAN.md - Complete Podman setup guide with automatic URL transformation

Quick container commands:

# Start containers (auto-detects Docker/Podman)
# Linux/Mac:
./start.sh

# Windows:
start.bat

# Follow logs
docker-compose logs -f    # Docker
podman-compose logs -f    # Podman

# Stop containers
docker-compose down       # Docker
podman-compose down       # Podman

📊 Scan Results

Scans return structured results including:

{
  "scan_id": "abc12345",
  "target": "https://juice-shop.herokuapp.com/#/",
  "alerts": {
    "High": 2,
    "Medium": 5,
    "Low": 12,
    "Informational": 8
  },
  "totalAlerts": 27,
  "riskScore": 31,
  "vulnerabilityNames": [
    { "name": "SQL Injection", "risk": "High", "count": 1 },
    { "name": "XSS", "risk": "Medium", "count": 3 }
  ],
  "durations": {
    "ajax": 45.2,
    "spider": 120.5,
    "ascan": 1800.0,
    "pscan": 30.1
  }
}

🔧 Troubleshooting

Server Takes Too Long to Start

The server requires approximately 90 seconds to become fully operational. This is normal and includes:

ZAP startup and initialization
Session creation
MCP server initialization

Wait for the startup process to complete before attempting to connect.

ZAP Won't Start

# Check if ZAP is in PATH
where zap.bat  # Windows
which zap.sh   # Linux/Mac

# Check Java installation
java -version

# Enable debug logging
set ZAP_LOG_LEVEL=DEBUG
python -m zap_custom_mcp

Connection Issues

# Check if ZAP is running
curl http://localhost:8080/JSON/core/view/version/

# Check MCP server
curl http://localhost:8082/mcp

# Check firewall settings

MCP Client Connection Issues

If your MCP client cannot connect:

Ensure the server has been running for at least 90 seconds
Verify the URL is correct: http://localhost:8082/mcp
Check that no firewall is blocking port 8082
For Cursor IDE, ensure your mcp.json configuration is correct

Container Issues

📖 For detailed container troubleshooting, see:

DOCKER.md - Docker troubleshooting guide
PODMAN.md - Podman troubleshooting guide

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Install development dependencies: pip install -e ".[dev]"
Run tests: pytest
Commit changes: git commit -am 'Add feature'
Push to branch: git push origin feature-name
Submit a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/LisBerndt/zap-custom-mcp.git
cd zap-custom-mcp

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Start development server
python -m zap_custom_mcp

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

OWASP ZAP - The amazing security testing tool
Model Context Protocol - The protocol that makes AI integration possible
Sovereign Engineering - SEC-05 cohort for inspiring freedom tech and self-sovereign applications

Special Thanks

This project was inspired by the Sovereign Engineering Community and their commitment to building tools for a self-sovereign future. The SEC-05 cohort's dedication to freedom tech, censorship resistance, and permissionless access aligns perfectly with the goals of making security testing tools more accessible and decentralized.

"Build applications and services for a self-sovereign future." — Sovereign Engineering

📞 Support

Vibe coded with ❤️ for the self sovereign engineer - YOLO!