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

📋 Prerequisites

Python 3.8+
OWASP ZAP installed and accessible via PATH
Java (required by ZAP)
Docker or Podman (optional, for containerized deployment)

📖 For container-specific prerequisites, see:

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

🛠️ Installation

Option 1: Local Installation

Clone the repository
git clone https://github.com/LisBerndt/zap-mcp-server.git cd zap-mcp-server
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

Option 2: Docker/Podman Deployment (Recommended)

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

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

# 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

⚠️ CRITICAL: When using containers, localhost applications must be accessed via host.docker.internal (Docker) or host.containers.internal (Podman) instead of localhost. This is the only supported method for localhost scanning.

⚙️ 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/YOUR_USERNAME/zap-mcp-server.git
cd zap-mcp-server

# 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

⚠️ CRITICAL: For localhost scanning, use host.docker.internal (Docker) or host.containers.internal (Podman) instead of localhost. This is the only supported method.

💻 Local Installation

1. Start the Server

python http_server.py

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
  }
}

📖 For Docker/Podman localhost scanning examples, see:

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

Basic Security Scan

{
  "tool": "start_complete_scan",
  "arguments": {
    "url": "https://example.com",
    "include_findings": true,
    "include_evidence": false
  }
}

Quick Passive Scan

{
  "tool": "start_passive_scan",
  "arguments": {
    "url": "https://example.com",
    "timeout_seconds": 300
  }
}

Custom Active Scan

{
  "tool": "start_active_scan",
  "arguments": {
    "url": "https://example.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 localhost scanning
PODMAN.md - Complete Podman setup guide with localhost scanning

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://example.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 http_server.py

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
Commit changes: git commit -am 'Add feature'
Push to branch: git push origin feature-name
Submit a Pull Request

📄 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!

ZAP MCP Server

ZAP MCP Server

🎯 Why ZAP MCP Server?

🚀 Features

📋 Prerequisites

🛠️ Installation

Option 1: Local Installation

Option 2: Docker/Podman Deployment (Recommended)

⚙️ Configuration

Custom Port Configuration

🚀 Quick Start

🐳 Docker/Podman (Recommended)

💻 Local Installation

1. Start the Server

2. Connect Your MCP Client

MCP Configuration Example

3. Available Tools

📖 Usage Examples

Development Workflow Integration

Basic Security Scan

Quick Passive Scan

Custom Active Scan

🔄 Shift Left Security Integration

Development Workflows

Benefits for Development Teams

🐳 Container Deployment

📊 Scan Results

🔧 Troubleshooting

Server Takes Too Long to Start

ZAP Won't Start

Connection Issues

MCP Client Connection Issues

Container Issues

🤝 Contributing

📄 License

🙏 Acknowledgments

Special Thanks

📞 Support

New MCP Servers

MCP directory API