convez.ai
MCP ServerSegurançaIntermediário
GT-Projects256

MCPGuard

GT-Projects256/mcpguard

Firewall + scanner de segurança para servidores MCP com políticas customizáveis

Ver no GitHub
BomPluginScore · de 0 a 100

Firewall de segurança open-source para servidores MCP que detecta vulnerabilidades do OWASP MCP Top 10, enforça políticas de runtime em chamadas de ferramentas de agentes IA e gera logs de auditoria de conformidade. Funciona como proxy entre seus agentes e servidores MCP, bloqueando acessos não autorizados em tempo real.

Instalação

$npx convez-ai GT-Projects256/mcpguard

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
2
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.2.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Escanear configs de MCP em busca de vulnerabilidades conhecidas (path traversal, command injection, tool poisoning)
  • Enforçar políticas de segurança em runtime bloqueando chamadas de ferramentas suspeitas
  • Gerar logs de auditoria e reports SARIF para conformidade e análise forense

Veredito

Ferramenta crítica para quem deploy MCP em produção. Endereça problemas reais (82% das implementações têm path traversal) com scanner sólido e proxy configurável via YAML. Essencial em stacks com agentes IA sensíveis.

README

A tradução para o português deste README ainda está na fila.

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

FieldWhat it matches
tool.nameTool name
tool.descriptionTool description text
param.nameParameter names (comma-separated)
param.valueParameter values (comma-separated)
server.nameMCP server name
server.urlMCP server URL

Operators

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

What It Checks

IDCategoryWhat we look for
MCP01Tool PoisoningHidden instructions, zero-width chars
MCP02Excessive PermissionsRoot-level access, wildcard permissions
MCP03Insecure TransportUnencrypted HTTP, SSRF via metadata endpoints
MCP04Command InjectionShell metacharacters in args, template injection (Jinja, EJS, Mustache)
MCP05Path Traversal.. in paths, access to sensitive system paths (.ssh, .aws, .kube, .env)
MCP06Secret Exposure15+ token patterns (AWS, Stripe, GitHub, Slack, etc.), sensitive env vars with literal values
MCP07Insecure DefaultsMissing security config for remote servers, Docker socket exposure
MCP08Input ValidationShell interpreters, curl|sh pipe-to-shell patterns
MCP09Audit GapsNo logging configured
MCP10Privilege Escalationsudo, --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

InputDefaultDescription
target.File or directory to scan
formattextOutput format: text, json, sarif
severitylowMinimum severity to report
fail-onhighFail if findings at this level or above (set to none to never fail)
sarif-uploadfalseUpload results to GitHub Code Scanning
versionlatestmcpguard 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

Ver o original no GitHub

Bom para

Relacionados