Mcpguard

Find security vulnerabilities in your MCP server configs before attackers do. Maps every finding to the OWASP MCP Top 10. Zero config. Runs locally.

---

Quick Start

pip install guardmcp
mcpguard scan

That's it. mcpguard auto-detects MCP configs from Claude Desktop, Claude Code, Cursor, VS Code, and Windsurf. No API keys, no accounts, everything runs locally.

What It Scans For

mcpguard checks your MCP server configurations against the OWASP MCP Top 10:

| | Risk | What mcpguard detects | |---|------|----------------------| | Y | MCP01 Token & Secret Exposure | Hardcoded API keys (AWS, OpenAI, GitHub, Anthropic, Stripe), high-entropy secrets, JWT tokens, live secret verification | | Y | MCP02 Privilege Escalation | Wildcard alwaysAllow, overpermissioned tool scopes | | Y | MCP03 Tool Poisoning | 14 injection patterns in tool descriptions, suspicious names, long descriptions, tool shadowing, rug pull detection | | Y | MCP04 Supply Chain Attacks | Unpinned @latest versions, missing version locks | | Y | MCP05 Command Injection | Shell metacharacters, dangerous commands, missing input schemas | | Y | MCP06 Intent Subversion | SSRF-prone URLs (cloud metadata, private IPs) | | Y | MCP07 Missing Authentication | HTTP servers without auth headers, plaintext HTTP transport | | Y | MCP08 No Audit Logging | Unsafe shell execution, pipe/redirect in args | | Y | MCP09 Shadow Servers | Localhost/dev URLs, unregistered servers | | Y | MCP10 Context Over-Sharing | Docker host network, sensitive volume mounts, no rate limiting |

Features

• Zero config -- auto-discovers configs from 5 MCP clients
• OWASP mapped -- every finding links to OWASP MCP Top 10
• 16 detection rules -- secrets, auth, permissions, supply chain, injection, shadow servers
• Entropy-based secret detection -- catches secrets that don't match known patterns
• Auto-fix -- mcpguard fix replaces hardcoded secrets with ${VAR} references
• Custom rules -- add your own YAML detection rules
• SARIF output -- integrates with GitHub Security tab
• GitHub Action -- drop-in CI/CD security gate
• Pre-commit hook -- catch issues before they're committed
• No network -- everything runs locally, no API calls

Usage

# Scan all auto-detected configs
mcpguard scan

# Scan a specific config file
mcpguard scan --path /path/to/mcp.json

# Auto-fix hardcoded secrets, HTTP URLs, wildcard permissions
mcpguard fix

# Preview fixes without modifying files
mcpguard fix --dry-run

# JSON output for CI/CD
mcpguard scan --format json

# SARIF output for GitHub Security tab
mcpguard scan --format sarif -o results.sarif

# Only show critical and high findings
mcpguard scan --severity high

# Connect to servers and inspect tool definitions
mcpguard inspect

# Verify detected secrets are live (makes read-only API calls)
mcpguard scan --verify

# Quick pass/fail check (exit code only)
mcpguard check

# Add custom detection rules
mcpguard scan --rules-dir ./my-rules/

Auto-Fix

mcpguard can automatically fix common security issues:

mcpguard fix

What it fixes:

• Replaces hardcoded API keys with ${VAR_NAME} environment variable references
• Upgrades http:// URLs to https://
• Removes wildcard alwaysAllow: ["*"]
• Creates a .mcpguard-backup before modifying any file

Supported Clients

| Client | Config Location | |--------|----------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Code | ~/.claude.json, .mcp.json | | Cursor | ~/.cursor/mcp.json, .cursor/mcp.json | | VS Code | ~/.config/Code/User/mcp.json, .vscode/mcp.json | | Windsurf | ~/.codeium/windsurf/mcp_config.json |

Custom Rules

mcpguard uses YAML detection rules. Add your own:

id: CUSTOM-001
info:
  name: Internal API Key Pattern
  severity: critical
  owasp: MCP01
  description: Detects internal API keys
  remediation: Use vault references
  cwe: CWE-798
detection:
  target: config
  scope: env_values
  match:
    type: regex
    patterns:
      - 'internal_[a-z0-9]{32}'

mcpguard scan --rules-dir ./my-rules/

GitHub Action

name: MCP Security Scan
on: [push, pull_request]

jobs:
  mcpguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: loplop-h/mcpguard@v1

Or manually:

      - run: pip install guardmcp
      - run: mcpguard scan --format sarif -o results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/loplop-h/mcpguard
    rev: v0.1.0
    hooks:
      - id: mcpguard

How It Compares

| Feature | mcpguard | mcp-scan | Tencent AI-Infra-Guard | Cisco mcp-scanner | |---------|----------|----------|------------------------|-------------------| | Zero-config CLI | Y | Y | N (Docker/web) | N (API key) | | Config scanning | Y | Y | Y | Y | | Server inspection | Y | Y | Y | N | | Tool poisoning detection | Y (14 patterns) | Y | Partial | N | | Rug pull detection | Y (hash pinning) | Y | N | N | | Auto-fix (fix) | Y | N | N | N | | OWASP MCP Top 10 mapping | Y (10/10) | N | N | N | | Secret verification | Y (GitHub, OpenAI, Anthropic, Stripe) | N | N | N | | SARIF output | Y | N | N | N | | GitHub Action | Y | N | N | N | | Pre-commit hook | Y | N | N | N | | Custom YAML rules | Y | N | N | N | | Entropy-based detection | Y | N | N | N |

Privacy

• All data stays on your machine
• No telemetry, no tracking
• scan reads config files only (no network)
• inspect connects to local stdio servers only (never sends data externally)
• --verify makes read-only API calls to check if secrets are live
• Open source, MIT licensed

Contributing

git clone https://github.com/loplop-h/mcpguard.git
cd mcpguard
pip install -e ".[dev]"
pytest

Add detection rules in src/mcpguard/rules/ using the YAML schema above.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: loplop-h
• Source: loplop-h/mcpguard
• License: MIT

Install and usage instructions live in the source repository linked above.