{"_id":"@alramalho/mcp-guard","_rev":"2-9c28fad33e2206777ebe8c2d89e973f5","name":"@alramalho/mcp-guard","dist-tags":{"latest":"0.2.2"},"versions":{"0.2.0":{"name":"@alramalho/mcp-guard","version":"0.2.0","keywords":["mcp","proxy","guard","gate","security"],"license":"MIT","_id":"@alramalho/mcp-guard@0.2.0","maintainers":[{"name":"alramalho","email":"alexandre.ramalho.1998@gmail.com"}],"bin":{"mcp-guard":"dist/index.js"},"dist":{"shasum":"72d51f9b5ab5c13a89e64b83c8420c3ad82c4889","tarball":"https://registry.npmjs.org/@alramalho/mcp-guard/-/mcp-guard-0.2.0.tgz","fileCount":20,"integrity":"sha512-KDTgu1BM4v31DpFTDK83js9Oc+A+6YL+wKxloBdKrCuJ5wvTZjjoC21wvDXgFPUKTibuCUj5NjlZXDpl0TF8Bg==","signatures":[{"sig":"MEUCIHor2LgJNJ3Ge1jaUrhj6LysbDbyNWcYUnQoe7Ol//pkAiEAu8dCtegZe0KtoRQXLFuPTlqpvMJaWeobrLFWBFKivJA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":49379},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","scripts":{"dev":"tsc --watch","build":"tsc","start":"node dist/index.js"},"_npmUser":{"name":"alramalho","email":"alexandre.ramalho.1998@gmail.com"},"_npmVersion":"10.9.4","description":"Simple HTTP proxy that gates MCP servers with block rules","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.3.6","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-guard_0.2.0_1772195342949_0.3050733577951257","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@alramalho/mcp-guard","version":"0.2.2","description":"Simple HTTP proxy that gates MCP servers with block rules","type":"module","main":"dist/index.js","bin":{"mcp-guard":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc --watch"},"keywords":["mcp","proxy","guard","gate","security"],"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","zod":"^4.3.6"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0"},"_id":"@alramalho/mcp-guard@0.2.2","gitHead":"f45dff61a9f1a494467a5510f45a02fb34b6a6a9","types":"./dist/index.d.ts","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-H5JQQs8z8JcRS8I0mrL23yingnI8T7fbYk34gnDV+jjxSo+P3N3zZFApTm1hYDGFw/6+6PoiB2/LJTic3LcUWw==","shasum":"0a702b76a636afa793317a14adb1dd5d0311b972","tarball":"https://registry.npmjs.org/@alramalho/mcp-guard/-/mcp-guard-0.2.2.tgz","fileCount":24,"unpackedSize":67668,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDZ8IRhWuT+bjBTMMoA7WjRxRwiQfMu1KeS2CPkrVLTwAIhAJMiB3qoN0nOSK6gfJDONbT46K6L32LTM8mJgLvHhW9c"}]},"_npmUser":{"name":"alramalho","email":"alexandre.ramalho.1998@gmail.com"},"directories":{},"maintainers":[{"name":"alramalho","email":"alexandre.ramalho.1998@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-guard_0.2.2_1773052666873_0.9049289814892976"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-27T12:29:02.878Z","modified":"2026-03-09T10:37:47.133Z","0.2.0":"2026-02-27T12:29:03.513Z","0.2.2":"2026-03-09T10:37:47.015Z"},"license":"MIT","keywords":["mcp","proxy","guard","gate","security"],"description":"Simple HTTP proxy that gates MCP servers with block rules","maintainers":[{"name":"alramalho","email":"alexandre.ramalho.1998@gmail.com"}],"readme":"\n<img width=\"1224\" height=\"618\" alt=\"CleanShot 2026-02-27 at 13 39 30@2x\" src=\"https://github.com/user-attachments/assets/8607026a-854c-4884-9ec6-19705a1232c3\" />\n\n# mcp-guard\n\nA simple HTTP proxy that gates MCP servers with block rules.\n\nNo SDKs. No dashboards. Just a JSON config and a toggle command.\n\n```\nClient (Claude, Cursor, etc.)\n    ↕ http\nmcp-guard (localhost proxy)\n    ↕ http\nUpstream MCP server (supabase, postgres, etc.)\n```\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install -g @alramalho/mcp-guard\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/alramalho/mcp-guard\ncd mcp-guard\npnpm install && pnpm build && npm link --force\n```\n\n### 2. Create `.mcp-guard.json`\n\nIn your project root (or `~/.mcp-guard.json` globally). Config is auto-discovered by walking up from cwd.\n\n```json\n{\n  \"port\": 6427,\n  \"servers\": {\n    \"supabase_production\": {\n      \"url\": \"https://mcp.supabase.com/mcp?project_ref=xxx&read_only=true\",\n      \"block\": [\"DELETE\", \"UPDATE\", \"DROP\", \"TRUNCATE\", \"ALTER\", \"INSERT\"],\n      \"blockMessage\": \"Destructive SQL operations are not allowed in production\"\n    }\n  }\n}\n```\n\n### 3. Update your `mcp.json`\n\nReplace the direct upstream URL with the mcp-guard proxy:\n\n```json\n{\n  \"mcpServers\": {\n    \"supabase_production\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:6427/supabase_production\"\n    }\n  }\n}\n```\n\n### 4. Toggle on/off\n\n```bash\n$ mcp-guard\nMCP Guard on → http://localhost:6427\n\n$ mcp-guard\nMCP Guard off\n```\n\n### Debug mode\n\nRun in foreground to see all tool calls and block decisions live:\n\n```bash\n$ mcp-guard -d\n```\n\n## Config\n\n`.mcp-guard.json` (auto-discovered from cwd up, or `~/.mcp-guard.json`, or `--config <path>`):\n\n| Field     | Type     | Default | Description                        |\n| --------- | -------- | ------- | ---------------------------------- |\n| `port`    | `number` | `6427`  | Port for the local HTTP proxy      |\n| `servers` | `object` | —       | Map of gate name → server config   |\n\nEach server:\n\n| Field          | Type       | Description                                        |\n| -------------- | ---------- | -------------------------------------------------- |\n| `url`          | `string`   | Upstream MCP server URL                            |\n| `enabled`      | `boolean`  | Set to `false` to passthrough without blocking     |\n| `token`        | `string`   | Static Bearer token for upstream auth (optional)   |\n| `block`        | `string[]` | Patterns to block in tool call arguments (case-insensitive) |\n| `matchMode`    | `string`   | `\"substring\"` (default) or `\"word\"` — substring matches anywhere, word requires word boundaries (e.g. `\"UPDATE\"` won't match `\"updated_at\"` in word mode) |\n| `blockMessage` | `string`   | Error message returned when blocked                |\n\n## Authentication\n\nmcp-guard handles OAuth-protected upstream servers (e.g. Supabase) automatically. On first connection, if the upstream requires auth, mcp-guard will open your browser for OAuth authorization. Tokens are cached in `~/.mcp-guard/auth/` and refreshed automatically.\n\nAlternatively, you can provide a static token in the config:\n\n```json\n{\n  \"servers\": {\n    \"my_server\": {\n      \"url\": \"https://example.com/mcp\",\n      \"token\": \"your-access-token\"\n    }\n  }\n}\n```\n\n## How It Works\n\n1. `mcp-guard` starts a local HTTP server\n2. When a client connects to `http://localhost:PORT/<gate_name>`, it connects to the upstream MCP server\n3. It discovers all upstream tools and re-exposes them\n4. On each tool call, all argument values are checked against block patterns\n5. If any pattern matches → error returned, call never reaches upstream\n6. If no match → call is forwarded to upstream as-is\n\n## License\n\nMIT\n","readmeFilename":"README.md"}