mcp-guard

Find hardcoded secrets, command injection, SSRF, and policy violations in MCP server configs before they ship. Static scanner + runtime gateway for Model Context Protocol servers.

npx @mcp-guard/cli scan ./mcp-config.json

That's it. Exit 0 means clean, exit 1 means you have work to do.

Why

MCP servers run with the same credentials as your agent. A poisoned tool description, a leaked API key in env, or a missing auth check on a database server becomes an attacker's foothold the second Claude calls it. mcp-guard scans your config before you ship and can sit in front of any MCP server at runtime to enforce policy on every call.

What it catches (static scanner)

• Leaked secrets — OpenAI keys in args, database URLs with passwords, GitHub tokens in env vars, private keys, bearer tokens. 20+ regex families covering AWS, Stripe, Anthropic, and more.
• Injection risks — shell metacharacters in commands, prompt injection vectors, tool poisoning via misleading descriptions, path traversal in args.
• Auth gaps — missing auth on database servers, weak passwords, OAuth without PKCE, localhost authorization servers.
• SSRF — internal IP ranges, cloud metadata endpoints (169.254.169.254), dangerous protocols (gopher://, file://), URL parameter injection.
• Compliance — maps findings to GDPR, SOC 2, HIPAA, ISO 27001, and PCI DSS controls.

Everything runs locally. Nothing leaves your machine.

What it fixes

mcp-guard fix interactively hardens a config:

• Secrets — extracts hardcoded keys into ${ENV_VAR} placeholders and tells you which env vars to set.
• File permissions — detects configs world-readable by other users and chmod 600s them. Scans Claude Desktop, Claude Code, Cursor, VS Code, and Windsurf locations.
• Tool restrictions — writes permissions.deny rules in your Claude Code settings.json to block dangerous tool patterns (shell exec, file delete, etc.).
• Git safety — adds any config containing secrets to .gitignore.
• Config hygiene — warns about configs at silently-ignored paths (e.g. ~/.claude/mcp.json, which Claude Code does not load).
• Transport — flags deprecated SSE transport and recommends Streamable HTTP.

Every fix is a checkbox. Use --dry-run to preview, --auto to apply all, --backup to snapshot first.

What it prevents (runtime gateway)

@mcp-guard/gateway is a stdio proxy that sits between Claude and any MCP server and enforces a YAML policy on every JSON-RPC frame.

mcp-guard-gateway run --policy ~/.mcp-guard/policy.yaml --server my-server -- node /path/to/server.js

From that moment on, every tools/call is checked against your policy before it reaches the server, and every response is scanned for exfiltration targets before it reaches Claude. Full audit log at ~/.mcp-guard/audit.jsonl.

See packages/gateway/README.md for policy syntax.

Install

One of:

# Quick scan with no install
npx @mcp-guard/cli scan ./mcp-config.json

# Global install
npm install -g @mcp-guard/cli

# As a dev dep in your own project
pnpm add -D @mcp-guard/cli

# Docker (distroless, non-root, multi-arch amd64+arm64)
docker run --rm ghcr.io/0xrake/mcp-guard:latest scan /config.json

Use as an MCP server

Add mcp-guard as an MCP server so Claude / Cursor / VS Code can scan configs on demand. The config format is the same for all clients.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mcp-guard": {
      "command": "npx",
      "args": ["-y", "@mcp-guard/mcp-server"]
    }
  }
}

Claude Code

Add to your project root .mcp.json, or to ~/.claude/settings.json (user-level, all projects):

{
  "mcpServers": {
    "mcp-guard": {
      "command": "npx",
      "args": ["-y", "@mcp-guard/mcp-server"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (user-level) or .cursor/mcp.json (project-level):

{
  "mcpServers": {
    "mcp-guard": {
      "command": "npx",
      "args": ["-y", "@mcp-guard/mcp-server"]
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "mcp-guard": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mcp-guard/mcp-server"]
    }
  }
}

This exposes scan_config, check_vulnerabilities, monitor_traffic, and generate_report as tools any MCP client can call.

Use in CI

- name: Scan MCP configs
  run: npx @mcp-guard/cli scan mcp-config.json --output sarif --file results.sarif

- name: Upload to code scanning
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Output formats: json, sarif, markdown, html, csv, xml, pdf.

Programmatic

import { MCPGuard } from '@mcp-guard/core';

const guard = new MCPGuard();
const result = await guard.scan({
  command: 'node',
  args: ['server.js', '--api-key', 'sk-live-oops'],
  env: { DATABASE_URL: 'postgres://admin:pass@localhost/db' },
});

console.log(result.summary.score); // 0
console.log(result.summary.grade); // 'F'
console.log(result.vulnerabilities.length); // 9

Works with single configs or the full Claude Desktop format ({ mcpServers: { ... } }).

REST API

@mcp-guard/api is a Fastify server exposing the scanner over HTTP:

npx @mcp-guard/api  # starts on :3001

POST /api/scan    scan a config
POST /api/fix     apply automated fixes
GET  /health      health check
GET  /docs        Swagger UI

CLI reference

mcp-guard scan <config>                               standard scan
mcp-guard scan <config> --depth comprehensive         deep scan
mcp-guard scan <config> -o sarif -f results.sarif     SARIF output for GitHub
mcp-guard fix <config>                                interactive hardening
mcp-guard fix <config> --dry-run                      preview only
mcp-guard fix <config> --scan-home                    include ~/.claude, ~/.cursor, etc.
mcp-guard watch <config> -i 30                        rescan every 30s on change
mcp-guard report <config> --format pdf --output r.pdf PDF report
mcp-guard doctor                                      scan known config paths
mcp-guard doctor --json                               machine-readable output
mcp-guard dashboard <config>                          interactive terminal TUI
mcp-guard init                                        generate example config
mcp-guard list                                        show all scanners

Full flag reference: docs/cli.md.

Packages

Package	Role
@mcp-guard/core	Scanning engine, types, domain scanners
@mcp-guard/cli	Command-line interface
@mcp-guard/gateway	Stdio proxy + policy engine (runtime gateway)
@mcp-guard/mcp-server	MCP server for Claude Desktop, Claude Code, Cursor, VS Code
@mcp-guard/api	REST API server (Fastify)
@mcp-guard/web	Dashboard (Next.js, internal)

Supply chain

Every push and pull request runs:

• CodeQL — JavaScript/TypeScript SAST (security-extended + security-and-quality)
• OSV-Scanner — Google OSV database check across all manifests
• Trivy — filesystem and IaC scanning (Dockerfile, workflows)
• Semgrep — six rulesets (security-audit, secrets, typescript, javascript, owasp-top-ten, nodejs)
• gitleaks — full git history secret scanning
• pnpm audit — prod dependency gate (moderate+ blocks)
• OSSF Scorecard — weekly repo best-practice rating
• actionlint — GitHub Actions workflow linter
• CycloneDX SBOM — generated on push + release, attested on tag
• Self-scan — mcp-guard scans its own config, SARIF uploaded to code scanning

Published packages use npm provenance (SLSA build attestation). Docker images are multi-arch (amd64, arm64), distroless base, non-root, digest-pinned via Dependabot.

Development

git clone https://github.com/0xRake/mcp-guard.git
cd mcp-guard
pnpm install
pnpm build
pnpm test       # 439 tests
pnpm typecheck  # tsc --noEmit across all packages
pnpm lint       # eslint
pnpm audit --prod --audit-level=moderate

Monorepo: pnpm workspaces + Turborepo. Each package builds with tsup.

Docs

• CLI reference
• API reference
• Architecture
• Gateway policies

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md. All PRs require passing supply-chain checks and CODEOWNER review. main is protected with signed commits and linear history.

Security

Report vulnerabilities privately via GitHub Security Advisories. See SECURITY.md.

License

MIT