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

1. Clone the repository

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

2. 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)

3. Install Python dependencies

   pip install -r requirements.txt

4. 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!

📖 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:

Custom Port Configuration

Using .env file (Recommended):

Using environment variables:

📖 For complete configuration details, see:

• DOCKER.md - Docker configuration options

• PODMAN.md - Podman configuration options

🚀 Quick Start

🐳 Docker/Podman (Recommended)

Fastest start with containers:

📖 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):

Alternative methods:

💡 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:

For other MCP clients, use the same URL endpoint.

3. Available Tools

📖 Usage Examples

Development Workflow Integration

Local Development Testing:

Pre-Commit Security Check:

Localhost Scanning Examples

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

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.

Quick Passive Scan

💡 Perfect for: Quick security assessment without active testing.

AJAX Spider Scan

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

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.

🔄 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

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

📖 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:

📊 Scan Results

Scans return structured results including:

🔧 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

Connection Issues

MCP Client Connection Issues

If your MCP client cannot connect:

1. Ensure the server has been running for at least 90 seconds

2. Verify the URL is correct: http://localhost:8082/mcp

3. Check that no firewall is blocking port 8082

4. 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

1. Fork the repository

2. Create a feature branch: git checkout -b feature-name

3. Install development dependencies: pip install -e ".[dev]"

4. Run tests: pytest

5. Commit changes: git commit -am 'Add feature'

6. Push to branch: git push origin feature-name

7. Submit a Pull Request

Development Setup

📄 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

• 📖 Documentation

• 🐛 Issue Tracker

• 💬 Discussions

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