convez.ai
MCP Server
ekhodzitsky

mcp-guard

ekhodzitsky/mcp-guard

Ver no GitHub
InicialPluginScore · de 0 a 100

Production-ready guardian and proxy for MCP servers. Process management, timeouts, audit logging, rate limiting, and tool permissions.

Instalação

$npx convez-ai ekhodzitsky/mcp-guard

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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1.2
Issues abertas
0
Contribuidores
1

README

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

MCP Guard 🛡️

Go Version License Build MCP

Production-ready guardian for MCP servers.

Process management, hard timeouts, audit logging, rate limiting, and tool permissions — all in one lightweight stdio proxy.


Why MCP Guard?

Running MCP servers in production is fragile:

  • Processes crash and never come back.
  • Tool calls hang forever with no way to cancel them.
  • Any tool can be invoked with no access control.
  • No audit trail of what the AI actually did.
  • Schema requests flood the server on every context window.

MCP Guard fixes all of that. It sits between your AI client and MCP servers, adding reliability, security, and observability without changing a single line of server code.


Features

FeatureDescription
🖥️ Process PoolStart, monitor, and auto-restart multiple MCP servers
💓 Health ChecksPing every 5s; auto-restart after 3 consecutive failures (~15s)
⏱️ Hard Timeouts30s for tools/call, 10s for tools/list — no more hangs
📝 Audit LoggingJSON Lines + SQLite dual logging of all JSON-RPC traffic
🔒 Tool PermissionsWhitelist / blacklist tools per server (deny takes precedence)
🚦 Rate LimitingPer-tool RPM/RPD sliding-window limits
⚡ Schema Cachetools/list responses cached with TTL; auto-invalidated on list_changed
🌐 Web UIHTMX-based dashboard + SSE live events at localhost:8787
📊 OpenTelemetryDistributed tracing out of the box

Quick Start

Install

go install github.com/ekhodzitsky/mcp-guard/cmd/mcp-guard@latest

Or download a pre-built binary from Releases.

Configure

Create mcp-guard.toml:

[server.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
timeout = { tools_call = "30s", tools_list = "10s" }
restart = { max_attempts = 5, backoff = "exponential" }
permissions = { allow = ["read_file", "list_directory"], deny = ["write_file"] }
rate_limit = { rpm = 60, rpd = 1000 }

[server.echo]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-echo"]

[guard]
health_check_interval = "5s"
audit_log_path = "~/.mcp-guard/audit"
schema_cache_ttl = "5m"
max_concurrent_calls = 100

[api]
enabled = true
addr = "localhost:8787"

Run

mcp-guard -c mcp-guard.toml

Then point your MCP client (Claude Desktop, Cline, etc.) at mcp-guard instead of the raw server command.


Architecture

┌─────────────┐      stdin       ┌─────────────┐      stdin       ┌─────────────┐
│   MCP       │ ───────────────→ │  MCP Guard  │ ───────────────→ │   MCP       │
│   Client    │                  │   Proxy     │                  │   Server    │
│ (Claude,    │ ←─────────────── │  + Guard    │ ←─────────────── │  (Pool)     │
│  Cline…)    │     stdout       │             │     stdout       │             │
└─────────────┘                  └──────┬──────┘                  └─────────────┘
                                        │
                    ┌───────────────────┼───────────────────┐
                    ↓                   ↓                   ↓
              [Audit Log]      [Timeout Check]      [Permission / Rate Limit]
                    ↓
              [Schema Cache]
                    ↓
              [Web UI / API]

Configuration Reference

SectionKeyDefaultDescription
server.<name>command—Executable to run
server.<name>args[]Arguments
server.<name>env{}Extra environment variables
server.<name>timeout—tools_call, tools_list durations
server.<name>restart—max_attempts, backoff
server.<name>permissions—allow, deny tool lists
server.<name>rate_limit—rpm, rpd
guardhealth_check_interval5sHealth ping frequency
guardaudit_log_path""Path prefix for .jsonl + .db
guardschema_cache_ttl0Cache TTL (disabled if 0)
guardmax_concurrent_calls100Semaphore per server
apienabledfalseEnable HTTP dashboard
apiaddr:8787Bind address

Roadmap

  • Process pool & health checks
  • Hard timeouts & audit logging
  • Tool permissions & rate limiting
  • Schema cache & Web UI
  • mTLS / auth for HTTP API
  • Prometheus metrics endpoint
  • Plugin system for custom guards

Development

Requires Go 1.26+.

make race   # tests with race detector
make lint   # golangci-lint
make build  # build binary

License

MIT © Eugene Khodzitsky

Ver o original no GitHub

Relacionados