Overview

MCPWatch is an open-source security scanner designed to evaluate an MCP (Model Context Protocol) server for common vulnerabilities and configuration mistakes. It automates a set of targeted checks against an MCP endpoint, producing machine-readable and human-friendly reports to help developers and operators identify and remediate issues before they affect production.

The scanner is useful during development, CI/CD pipelines, and incident response: it can validate authentication and authorization, verify secure defaults, detect misconfigurations (CORS, headers, rate limits), and flag other risk patterns often introduced when deploying model-serving infrastructure. MCPWatch is intended for developers and security engineers who want quick, repeatable assessments of an MCP deployment.

Features

Lightweight CLI for on-demand scans
Docker image for isolated execution
Configurable rules and severity thresholds
Output formats: JSON (machine-readable) and HTML/text reports
Authentication options for scanning protected endpoints
Rule-based checks for common MCP-specific issues (CORS, auth, exposed endpoints, telemetry leaks, headers, rate limiting)
Integration-friendly: suitable for CI pipelines and scheduled audits

Installation / Configuration

Clone the repository and run locally, or use the provided Docker image.

Install from source:

git clone https://github.com/kapilduraphe/mcp-watch.git
cd mcp-watch
# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Run the scanner (example)
python -m mcpwatch --target https://mcp.example.com --output report.json

Run with Docker:

# Pull or build the image
docker build -t mcpwatch:latest .
# Run a scan against a target
docker run --rm mcpwatch:latest \
  --target https://mcp.example.com \
  --output /tmp/mcp-report.json

# Or bind-mount to retrieve results
docker run --rm -v "$(pwd)/reports:/reports" mcpwatch:latest \
  --target https://mcp.example.com --output /reports/report.json

Example configuration (YAML)

target: "https://mcp.example.com"
auth:
  type: token
  token: "REDACTED"
checks:
  cors: true
  headers: true
  auth: true
  rate_limit: true
output:
  format: json
  path: "./reports/mcp-report.json"
severity_threshold: medium

Common CLI options:

–target: URL of the MCP server to scan
–config: Path to YAML config file
–output: Path to report file
–format: json | html | text
–auth-token: Inline token for protected endpoints
–checks: Comma-separated subset of checks to run

Available Resources

GitHub repository: https://github.com/kapilduraphe/mcp-watch
CLI executable for local and automated scans
Docker image for reproducible runs
Configurable ruleset (YAML/JSON)
Reporters producing JSON and HTML summaries suitable for dashboards or issue triage

Typical Checks (sample table)

Check	Why it matters
CORS misconfiguration	Can enable cross-origin access, exposing internal APIs
Missing security headers	Increases risk of content injection, clickjacking
Weak or missing auth	Allows unauthorized model access or data leakage
Exposed debug endpoints	May reveal sensitive internal state or admin controls
Unrestricted Model Upload/Prompting	Can enable malicious content or model tampering
No rate limiting	Enables abusive usage or denial-of-service vectors

Use Cases

Pre-deployment validation
- Run MCPWatch against staging MCP instances before cutting release.
- Example:
```
python -m mcpwatch --config configs/staging.yaml --output reports/staging.json
```
- Address high/critical findings before promoting to production.

CI/CD integration

Add a job that runs MCPWatch and fails the pipeline on critical findings.

Example (GitHub Actions job snippet):

jobs:
  mcp-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run MCPWatch
        run: |
          docker run --rm mcpwatch:latest \
            --target ${{ secrets.MCP_URL }} \
            --auth-token ${{ secrets.MCP_TOKEN }} \
            --format json --output /tmp/mcp-report.json
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: mcp-report
          path: /tmp/mcp-report.json

Regular security audits
- Schedule daily/weekly scans to detect regressions or configuration drift.
- Store results in a central logging system and raise tickets for new critical findings.
Incident response and forensics
- After a suspicious event, run focused checks (auth, exposed endpoints, logs/telemetry) to quickly triangulate potential causes.

Getting Help and Contributing

Consult the GitHub repository for the latest usage docs, issues, and contribution guidelines: https://github.com/kapilduraphe/mcp-watch
Open issues for missing checks, false positives, or integration requests.
Contributions that add checks, improve reporters, or harden scanning logic are welcome.

This guide gives a concise overview and practical examples to get started with MCPWatch. For complete options and advanced configuration, refer to the project’s README and configuration schema in the repository.

MCPWatch MCP Server Vulnerability Scanner