{"_id":"@agentopssec/mcp-firewall","name":"@agentopssec/mcp-firewall","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@agentopssec/mcp-firewall","version":"1.0.0","description":"Local policy gateway for MCP tool calls.","type":"module","homepage":"https://AgentOpsSec.com/projects/mcp-firewall","repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/mcp-firewall.git"},"bugs":{"url":"https://github.com/AgentOpsSec/mcp-firewall/issues"},"bin":{"mcp-firewall":"bin/mcp-firewall.js"},"scripts":{"test":"node --test","check":"node --check bin/mcp-firewall.js && node --test"},"keywords":["mcp","firewall","agent","security","policy"],"license":"MIT","engines":{"node":">=20"},"publishConfig":{"access":"public"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"gitHead":"94551b28e2be7ec9052290e1ee25b4fd282a47dc","_id":"@agentopssec/mcp-firewall@1.0.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-iVSfVuVeWXwuYT+uRfKC/UUrjrb2N8zZ/w3z8dQI6TTPAH69tOcqHrSQtXHDLh10QDLv5+6afbC5+q/ctxI1Pw==","shasum":"7c0028c9196969fb27097fa428a22770613dbd77","tarball":"https://registry.npmjs.org/@agentopssec/mcp-firewall/-/mcp-firewall-1.0.0.tgz","fileCount":14,"unpackedSize":44617,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDwoTlhNr9aApX8mPjGL5x1dWUMsN3f0yRQVVYUWTEmIwIgbqath+AXNQfc5yLzN/hLzU6UlT4tuY3jJRZ4pYwPp7Q="}]},"_npmUser":{"name":"agentopssec","email":"agentopssecurity@gmail.com"},"directories":{},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-firewall_1.0.0_1777236553180_0.9169852977531476"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T20:49:13.085Z","1.0.0":"2026-04-26T20:49:13.310Z","modified":"2026-04-26T20:49:13.511Z"},"maintainers":[{"name":"agentopssec","email":"agentopssecurity@gmail.com"}],"description":"Local policy gateway for MCP tool calls.","homepage":"https://AgentOpsSec.com/projects/mcp-firewall","keywords":["mcp","firewall","agent","security","policy"],"repository":{"type":"git","url":"git+https://github.com/AgentOpsSec/mcp-firewall.git"},"author":{"name":"Aunt Gladys Nephew","url":"https://auntgladysnephew.com"},"bugs":{"url":"https://github.com/AgentOpsSec/mcp-firewall/issues"},"license":"MIT","readme":"# MCP Firewall\n\n**Let AI agents use tools without giving them your whole machine.**\n\nMCP Firewall is a local policy gateway for MCP tool calls. It sits between AI\nclients and MCP servers, applies project policies, blocks dangerous actions,\nsupports project approvals, and records what happened.\n\nThink of it as:\n\n```txt\nA firewall for MCP tool calls\n```\n\n## Why This Exists\n\nMCP servers give AI agents access to real tools: filesystems, shells, browsers,\nGitHub, databases, cloud APIs, email, calendars, and more.\n\nThat power needs a control point:\n\n- Which tool calls should be allowed automatically?\n- Which actions should be blocked until a developer approves them?\n- Which paths should agents never read?\n- Which shell commands are safe for this project?\n- Which GitHub or database actions are too broad?\n- What happened when a tool call was allowed or blocked?\n\nMCP Firewall gives developers a local-first way to enforce those decisions.\n\n## Install\n\n```bash\nnpm install -g @agentopssec/mcp-firewall\n```\n\nOr run it without installing:\n\n```bash\nnpx -y @agentopssec/mcp-firewall init\n```\n\n## Update\n\n```bash\nmcp-firewall update          # check the registry, prompt before installing\nmcp-firewall update --yes    # update without prompting\n```\n\n## Primary Workflow\n\nMCP Firewall starts with a local proxy and a human-readable policy:\n\n```bash\nmcp-firewall proxy -- node ./mcp-server.js\n```\n\nNote: the proxy enforces policy on the **client → server** direction\n(typical `tools/call` flow). Server → client traffic is forwarded as-is.\n\nThe workflow should do three things well:\n\n1. Intercept MCP tool calls.\n2. Apply allow, warn, and block rules.\n3. Record tool-call decisions locally.\n\n## CLI\n\n```bash\nmcp-firewall init\nmcp-firewall add ./mcp.json\nmcp-firewall run claude\nmcp-firewall run codex\nmcp-firewall run cursor\nmcp-firewall proxy -- node ./mcp-server.js\nmcp-firewall proxy --check '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"shell.exec\",\"arguments\":{\"command\":\"npm test\"}}}'\nmcp-firewall policy init\nmcp-firewall import-doctor mcp-doctor-scan.json\nmcp-firewall logs\nmcp-firewall approve latest\nmcp-firewall update [--yes]\n```\n\n## Standalone and Stack Use\n\nMCP Firewall runs on its own with local policies and logs:\n\n```bash\nmcp-firewall init\nmcp-firewall check --tool shell.exec --input '{\"command\":\"npm test\"}'\n```\n\nWhen used with the full AgentOpsSec stack, it can import MCP Doctor scan reports\nas optional context and its logs can be reviewed by Agent Review:\n\n```bash\nmcp-doctor scan --json --output mcp-doctor-scan.json\nmcp-firewall import-doctor mcp-doctor-scan.json\nagent-review --from-mcp-firewall\n```\n\n## What MCP Firewall Controls\n\nMCP Firewall applies policy to line-delimited JSON-RPC MCP tool calls passed\nthrough `mcp-firewall proxy`. It can also evaluate individual calls with\n`mcp-firewall check`.\n\nIt controls local MCP activity, including:\n\n- Filesystem reads and writes\n- Shell command execution\n- Network and browser access\n- GitHub repository actions\n- Database queries and mutations\n- Email and calendar actions\n- Secret and credential access\n- Project-level tool permissions\n- Per-server rules\n- Per-client rules\n- Tool-call logging\n- User approval decisions\n\n## Example Approval\n\n```txt\nMCP Firewall Approval by github.com/AgentOpsSec\n\nAgent wants to run a shell command.\n\nCommand:\nrm -rf ./dist\n\nRisk:\nMedium\n\nReason:\nThe command deletes a build directory.\n\nActions:\n[Allow once] [Always allow for this project] [Block]\n```\n\n## Policy Example\n\n```json\n{\n  \"project\": \"my-nextjs-app\",\n  \"defaultAction\": \"warn\",\n  \"rules\": [\n    {\n      \"tool\": \"filesystem.read\",\n      \"scope\": \"./\",\n      \"action\": \"allow\"\n    },\n    {\n      \"tool\": \"filesystem.read\",\n      \"scope\": \"~/.ssh\",\n      \"action\": \"block\"\n    },\n    {\n      \"tool\": \"filesystem.read\",\n      \"scope\": \".env\",\n      \"action\": \"block\"\n    },\n    {\n      \"tool\": \"shell.exec\",\n      \"command\": \"npm test\",\n      \"action\": \"allow\"\n    },\n    {\n      \"tool\": \"shell.exec\",\n      \"action\": \"warn\"\n    }\n  ]\n}\n```\n\nSupported actions:\n\n```txt\nallow\nwarn\nblock\napprove_once\napprove_for_session\napprove_for_project\nlog_only\n```\n\n## What MCP Firewall Records\n\nMCP Firewall keeps local audit logs for:\n\n- Tool name\n- Tool input\n- Tool output\n- Risk score\n- User decision\n- Timestamp\n- Project path\n- Client name\n- Server name\n- Policy matched\n- Whether execution was allowed or blocked\n\n## Example Log Shape\n\n```json\n{\n  \"tool\": {\n    \"name\": \"MCP Firewall\",\n    \"by\": \"github.com/AgentOpsSec\",\n    \"repository\": \"github.com/AgentOpsSec/mcp-firewall\"\n  },\n  \"timestamp\": \"2026-04-25T15:30:00Z\",\n  \"project\": \"my-nextjs-app\",\n  \"client\": \"codex\",\n  \"server\": \"filesystem\",\n  \"tool\": \"filesystem.read\",\n  \"risk\": \"high\",\n  \"action\": \"block\",\n  \"policyMatched\": \"block-env-files\",\n  \"input\": {\n    \"path\": \".env\"\n  }\n}\n```\n\n## Design Principles\n\n- Local-first\n- Open-source\n- No telemetry by default\n- Human-readable policies\n- Terminal-native approvals\n- Per-project control\n- Secure defaults\n- Clear local audit logs\n\n## Initial Release Scope\n\nThe initial release includes a local stdio JSON-RPC proxy, local policy\nenforcement, project approvals, filesystem and shell rules, and local logging.\n\n### 1.0: Local Proxy\n\n- Start MCP Firewall as a local gateway\n- Register existing MCP server configurations\n- Route MCP tool calls through the gateway\n- Identify client, server, tool name, and tool input\n- Preserve normal MCP behavior for allowed calls\n- Print clear terminal activity\n\n### 1.0: Policy Enforcement\n\n- Initialize a project policy file\n- Support allow, warn, and block decisions\n- Apply filesystem scope rules\n- Apply shell command rules\n- Block sensitive paths such as `.env` and `~/.ssh`\n- Allow common project commands such as `npm test`\n- Explain which policy matched a tool call\n\n### 1.0: Approvals and Logs\n\n- Approve logged actions explicitly with `mcp-firewall approve`\n- Support allow once and approve for project decisions\n- Record every tool call decision locally\n- Show recent firewall logs\n- Inspect the latest blocked or approved action\n- Emit JSON logs for automation and review\n\n\n## Output\n\nReports use plain-language status words rather than raw exit codes:\n\n- `ok` — the step ran successfully (green).\n- `failed (exit N)` — the step exited non-zero (red); the original code is preserved.\n- `skipped (reason)` — the step was not applicable (dim).\n\nSeverity colors follow the AgentOpsSec palette (safe = green, warning = amber, risk = red). The palette honors `NO_COLOR` and `FORCE_COLOR`, and JSON / CSV output stays plain.\n\n\n- Repo: https://github.com/AgentOpsSec/mcp-firewall\n- npm: https://www.npmjs.com/package/@agentopssec/mcp-firewall\n- AgentOpsSec stack: https://github.com/AgentOpsSec/stack\n- Website: https://AgentOpsSec.com\n\n## Author\n\nCreated and developed by **Aunt Gladys Nephew**.\n\n- Website: https://auntgladysnephew.com\n- GitHub: https://github.com/auntgladysnephew\n- X: https://x.com/AGNonX\n","readmeFilename":"README.md","_rev":"1-e1a5ca3e62f4d2795c8250d29d5857cc"}