mcpguard

Security scanner and firewall for MCP (Model Context Protocol) servers. Checks your configs for known issues, blocks sketchy tool calls at runtime, and keeps audit logs.

Maps to the OWASP MCP Top 10 (2026).

Why

MCP is everywhere now - Claude, Cursor, VS Code, OpenAI. But most setups ship with zero security review. Studies found 82% of MCP implementations have path traversal issues, 67% have code injection vectors, and about 5.5% of public servers have tool poisoning baked in.

This tool helps you catch that stuff before it bites you.

Quick Start

npm install -g @gtprojects/mcpguard

# scan your MCP config
mcpguard scan

# generate a starter policy
mcpguard init

# run the firewall proxy
mcpguard proxy --policy mcpguard.policy.yaml --port 9090

Commands

mcpguard scan [target]

Scans MCP server configs for security issues.

mcpguard scan                              # scan current directory
mcpguard scan claude_desktop_config.json   # scan a specific file
mcpguard scan --format json                # JSON output
mcpguard scan --format sarif               # SARIF for GitHub Code Scanning
mcpguard scan --ci                         # exit code 1 on critical/high
mcpguard scan --severity high              # only show high+ severity

mcpguard proxy

Sits between your agent and MCP servers. Checks every tool call against your policy, blocks anything that doesn't pass, and logs everything.

mcpguard proxy --port 9090
mcpguard proxy --policy mcpguard.policy.yaml --port 9090
mcpguard proxy --policy mcpguard.policy.yaml --upstream http://localhost:3000
mcpguard proxy --policy mcpguard.policy.yaml --audit-file ./audit.log

mcpguard init

Drops a default policy file you can customize.

mcpguard init
mcpguard init --output custom-policy.yaml

Policy Format

Policies are YAML. You define rules with conditions and actions (allow/deny/audit):

version: "1.0"
name: my-security-policy
description: Custom security rules

rules:
  - id: deny-shell-exec
    name: Block shell execution
    action: deny
    priority: 100
    conditions:
      - field: tool.name
        operator: matches
        value: "(exec|shell|bash|cmd)"

  - id: audit-file-writes
    name: Audit all file writes
    action: audit
    priority: 50
    conditions:
      - field: tool.name
        operator: contains
        value: write

Condition Fields

| Field | What it matches | |-------|-----------------| | tool.name | Tool name | | tool.description | Tool description text | | param.name | Parameter names (comma-separated) | | param.value | Parameter values (comma-separated) | | server.name | MCP server name | | server.url | MCP server URL |

Operators

equals, contains, matches (regex), startsWith, endsWith, in (list)

What It Checks

| ID | Category | What we look for | |----|----------|------------------| | MCP01 | Tool Poisoning | Hidden instructions, zero-width chars | | MCP02 | Excessive Permissions | Root-level access, wildcard permissions | | MCP03 | Insecure Transport | Unencrypted HTTP, SSRF via metadata endpoints | | MCP04 | Command Injection | Shell metacharacters in args, template injection (Jinja, EJS, Mustache) | | MCP05 | Path Traversal | .. in paths, access to sensitive system paths (.ssh, .aws, .kube, .env) | | MCP06 | Secret Exposure | 15+ token patterns (AWS, Stripe, GitHub, Slack, etc.), sensitive env vars with literal values | | MCP07 | Insecure Defaults | Missing security config for remote servers, Docker socket exposure | | MCP08 | Input Validation | Shell interpreters, curl|sh pipe-to-shell patterns | | MCP09 | Audit Gaps | No logging configured | | MCP10 | Privilege Escalation | sudo, --privileged, writable host mounts in containers |

Try It

Scan the included example configs to see mcpguard in action:

# Scan a deliberately dangerous config (lots of findings)
mcpguard scan examples/dangerous-config.json

# Scan a clean config (should pass)
mcpguard scan examples/safe-config.json

GitHub Actions

Use the action directly in your workflow:

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

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: GT-Projects256/mcpguard@main
        with:
          fail-on: high
          sarif-upload: true

Action Inputs

| Input | Default | Description | |-------|---------|-------------| | target | . | File or directory to scan | | format | text | Output format: text, json, sarif | | severity | low | Minimum severity to report | | fail-on | high | Fail if findings at this level or above (set to none to never fail) | | sarif-upload | false | Upload results to GitHub Code Scanning | | version | latest | mcpguard version to install |

Manual Setup

If you prefer to install manually:

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

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @gtprojects/mcpguard
      - run: mcpguard scan --ci --format sarif > results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Programmatic API

import { Scanner, PolicyEngine, McpFirewall, AuditLogger } from '@gtprojects/mcpguard';

const scanner = new Scanner();
const results = scanner.scanFile('claude_desktop_config.json');
console.log(results.summary);

const engine = new PolicyEngine();
engine.loadFromFile('mcpguard.policy.yaml');
const decision = engine.evaluate({
  toolName: 'shell_exec',
  paramNames: ['command'],
  paramValues: ['rm -rf /'],
});
console.log(decision); // { allowed: false, action: 'deny', ... }

Contributing

PRs welcome. Open an issue first if it's anything big.

git clone https://github.com/GT-Projects256/mcpguard.git
cd mcpguard
npm install
npm test

License

MIT