MCPGuard 🛡️

Runtime security proxy for the Model Context Protocol (MCP) and Agent-to-Agent (A2A) protocols.

MCPGuard sits between MCP clients and servers, inspecting every JSON-RPC message in real time to detect and block security threats. Supports HTTP SSE, stdio, and WebSocket transport modes.

What makes MCPGuard unique

Features

Installation

pip install mcpguard-proxy

From source:

git clone https://github.com/Carlos-Projects/mcpguard.git
cd mcpguard
pip install -e ".[dev]"

Quick Start

# HTTP mode (intercept an upstream MCP server)
mcpguard proxy --target http://localhost:8000 --port 8080

# Stdio mode (wrap a local MCP server process)
mcpguard proxy --mode stdio --cmd python3 --cmd /path/to/server.py --port 8080

# With auth, TLS, and circuit breaker
mcpguard proxy --target http://localhost:8000 --port 8443 \
  --api-key my-secret --tls-cert cert.pem --tls-key key.pem

# With config file (YAML/JSON)
mcpguard proxy --config mcpguard.yaml --hot-reload

Clients connect to http://localhost:8080 instead of the server directly. Dashboard at /_mcpguard/.

CLI Reference

mcpguard proxy [OPTIONS]

mcpguard analyze [LOG_DIR]

Analyze logged events with optional --severity, --type, --limit filters.

Architecture

                           ┌──────────────────┐
                      ┌───▶│   MCPGuard Proxy  │───▶  MCP Server (HTTP/SSE)
                      │    │  (port 8080)      │
   MCP Client (Host)──┤    └──────────────────┘      ┌──────────────────┐
                      │           │                   │  MCP Server      │
                      │           ├──────────────────▶│  (stdio process) │
                      │           │                   └──────────────────┘
                      │    ┌──────────────────┐
                      └───▶│  /_mcpguard/      │
                           │  Dashboard        │
                           └──────────────────┘
                                      │
                           ┌──────────┴──────────┐
                           │   /metrics           │
                           │   /health            │
                           │   /health/ready      │
                           └─────────────────────┘

Detection Plugins

Config File Example

mode: http
target_url: http://localhost:8000
listen_host: 127.0.0.1
listen_port: 8080
rate_limit: 100
rate_window: 60
block_on_injection: true
block_on_poisoning: true
max_sse_connections: 50
request_timeout: 30.0
api_key: your-secret-key
allowlisted_tools:
  - get_weather
  - search
denylisted_tools:
  - execute_bash
  - delete_files
tls_cert_path: /path/to/cert.pem
tls_key_path: /path/to/key.pem

Testing

pip install -e ".[dev]"
python -m pytest tests/ -v --cov=mcpguard --cov-report=term-missing

Ecosystem

MCPGuard is a runtime guard — it complements:

• Cisco MCP Scanner — static analysis of MCP servers
• MCPwn — active red teaming framework for MCP

Changelog

v0.4.0 (2025-05-25)

• Security: Timing-attack resistant auth, body size limit (10MB), subprocess command validation, SSRF protection
• Reliability: Circuit breaker (5 failures/30s recovery), async config watcher, graceful shutdown (10s)
• Features: /health/ready endpoint, rate limit headers, configurable timeout, WebSocket transport
• Dashboard: JS event filtering, CDN fallback, uptime/active connections metrics
• Config: Validation on startup, auto-split string commands, request_timeout option
• Tests: 52 → 104 tests, coverage ~85%, 7 new test files, CI coverage reporting
• Infra: .dockerignore, stdio integration tests in CI, codecov integration

v0.3.0 (2025-05-24)

• HTTP SSE + stdio transport modes
• Prompt injection, tool poisoning, resource scanning, anomaly detection
• Live HTMX dashboard, Prometheus metrics, JSONL audit logging
• Auth middleware, TLS support, rate limiting, allow/deny lists
• Docker support, CI/CD, PyPI publishing

License

MIT