{"_id":"n8n-mcp-guard","_rev":"4-05973fec3265277e6fc5f2e56d209871","name":"n8n-mcp-guard","dist-tags":{"latest":"1.2.2"},"versions":{"1.1.0":{"name":"n8n-mcp-guard","version":"1.1.0","keywords":["n8n","mcp","model-context-protocol","modelcontextprotocol","automation","ai-agents","claude-code","codex"],"author":{"name":"Faraz Hayder"},"license":"MIT","_id":"n8n-mcp-guard@1.1.0","maintainers":[{"name":"farazhayder","email":"farazhayder2004@gmail.com"}],"homepage":"https://github.com/FarazHayder/n8n-mcp-guard#readme","bugs":{"url":"https://github.com/FarazHayder/n8n-mcp-guard/issues"},"bin":{"n8n-mcp-guard":"dist/index.js"},"dist":{"shasum":"a6ac854bbf432ffb9915e1e0280d68a5367aa4ac","tarball":"https://registry.npmjs.org/n8n-mcp-guard/-/n8n-mcp-guard-1.1.0.tgz","fileCount":40,"integrity":"sha512-/28imenfpR0GVGi9753hOQU4Fupe1FLVesP6kDzDirJ1cmg8+w7mKaJdk5I/Z5CIJ94+4+hyoCUl15sPFwrP7w==","signatures":[{"sig":"MEYCIQC1+bnyetLE+Le/MChsTO6KAvIR4BUrstM2aazGuHrcGQIhALLvn+yzj3O3c+ffVDGhejKiNtd1t+q5/lZ6Tubd4eXn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":174184},"type":"module","engines":{"node":">=22"},"gitHead":"838427b255d853729a015f43f6f10be0c1b16ab8","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc -p tsconfig.json","check":"npm run typecheck && npm test && npm run build && npm run smoke","smoke":"node scripts/smoke.mjs","start":"node dist/index.js","prepare":"npm run build","typecheck":"tsc --noEmit","prepublishOnly":"npm run check"},"_npmUser":{"name":"farazhayder","email":"farazhayder2004@gmail.com"},"repository":{"url":"git+https://github.com/FarazHayder/n8n-mcp-guard.git","type":"git"},"_npmVersion":"11.19.0","description":"Safety-conscious MCP server for n8n workflow inspection and controlled automation changes","directories":{},"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^2.1.9","typescript":"^5.5.3","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/n8n-mcp-guard_1.1.0_1789174903756_0.9315308356940708","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"n8n-mcp-guard","version":"1.2.0","keywords":["n8n","mcp","model-context-protocol","modelcontextprotocol","automation","ai-agents","claude-code","codex"],"author":{"name":"Faraz Hayder"},"license":"MIT","_id":"n8n-mcp-guard@1.2.0","maintainers":[{"name":"farazhayder","email":"farazhayder2004@gmail.com"}],"homepage":"https://github.com/FarazHayder/n8n-mcp-guard#readme","bugs":{"url":"https://github.com/FarazHayder/n8n-mcp-guard/issues"},"bin":{"n8n-mcp-guard":"dist/index.js"},"dist":{"shasum":"32c0ec7c0136cdac511079958863d91c04c220ed","tarball":"https://registry.npmjs.org/n8n-mcp-guard/-/n8n-mcp-guard-1.2.0.tgz","fileCount":43,"integrity":"sha512-Mly+FGG+r0M7DXK38SMjNqHgiZYaXAXvrdSF3cdyul8ffQtqO2lUUflllwcF6JN9fuGKWd6boegck/mMsdGzjg==","signatures":[{"sig":"MEYCIQDGCyFWlVJKEedVt5tkmZc0PwApITalNul3fAgF20QMCQIhAIRHLICzp/UoxiK9eG52pOAXxgkUAUZmph7Pj/Zpr2Cp","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIE/pkd5lfDpKKQ0l5tGeMWModihCsvjA7dKD1vAH+3gDAiBCAxcyyYzxEkRxeWKAwIQgdwZiPtFIM7Wx7nLdsLCuqQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":178480},"type":"module","engines":{"node":">=22"},"gitHead":"b096d50a6f1615227709019c729d3a15d22383a2","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc -p tsconfig.json","check":"npm run typecheck && npm test && npm run build && npm run smoke","smoke":"node scripts/smoke.mjs","start":"node dist/index.js","prepare":"npm run build","typecheck":"tsc --noEmit","prepublishOnly":"npm run check"},"_npmUser":{"name":"farazhayder","email":"farazhayder2004@gmail.com"},"repository":{"url":"git+https://github.com/FarazHayder/n8n-mcp-guard.git","type":"git"},"_npmVersion":"11.19.0","description":"Safety-conscious MCP server for n8n workflow inspection and controlled automation changes","directories":{},"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^2.1.9","typescript":"^5.5.3","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/n8n-mcp-guard_1.2.0_1789175992878_0.5874703229341545","host":"s3://npm-registry-packages-npm-production"}},"1.2.1":{"name":"n8n-mcp-guard","version":"1.2.1","keywords":["n8n","mcp","model-context-protocol","modelcontextprotocol","automation","ai-agents","claude-code","codex"],"author":{"name":"Faraz Hayder"},"license":"MIT","_id":"n8n-mcp-guard@1.2.1","maintainers":[{"name":"farazhayder","email":"farazhayder2004@gmail.com"}],"homepage":"https://github.com/FarazHayder/n8n-mcp-guard#readme","bugs":{"url":"https://github.com/FarazHayder/n8n-mcp-guard/issues"},"bin":{"n8n-mcp-guard":"dist/index.js"},"dist":{"shasum":"3a62e2e980a40e0ca82133b9466e82efaa2e866c","tarball":"https://registry.npmjs.org/n8n-mcp-guard/-/n8n-mcp-guard-1.2.1.tgz","fileCount":43,"integrity":"sha512-OTzPBHztEP+1sYUE0aM/klVaJPLk3PhZCoh4dlH4an2D6nBL2uhN0BjHntfWxjIHYwOpsLeHArlpDSs0NYyiSw==","signatures":[{"sig":"MEUCIEdKg+5jim8/wGXHeLiss2wqiYfwZENHQPk/HzYgBCprAiEA8AmG2oeUyAfpWbU1MzkwGuUUAtTgpFVEXPNYxy3Y6mI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIDvKKHPU1Qm50MrAp2U1abNol77LZQbHMFUVmPYg++jYAiEA8MkYzNvSamx9qwp3QZyM1jtIcteyDp4IdDC59CiXb6c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":179077},"type":"module","engines":{"node":">=22"},"gitHead":"8c99f53d912e941d5347cd266aff8bdb2c3fa33e","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc -p tsconfig.json","check":"npm run typecheck && npm test && npm run build && npm run smoke","smoke":"node scripts/smoke.mjs","start":"node dist/index.js","prepare":"npm run build","typecheck":"tsc --noEmit","prepublishOnly":"npm run check","test:integration":"node scripts/integration.mjs"},"_npmUser":{"name":"farazhayder","email":"farazhayder2004@gmail.com"},"repository":{"url":"git+https://github.com/FarazHayder/n8n-mcp-guard.git","type":"git"},"_npmVersion":"11.19.0","description":"Safety-conscious MCP server for n8n workflow inspection and controlled automation changes","directories":{},"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^2.1.9","typescript":"^5.5.3","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/n8n-mcp-guard_1.2.1_1789176651299_0.2917781714055385","host":"s3://npm-registry-packages-npm-production"}},"1.2.2":{"_id":"n8n-mcp-guard@1.2.2","bin":{"n8n-mcp-guard":"dist/index.js"},"bugs":{"url":"https://github.com/FarazHayder/n8n-mcp-guard/issues"},"dist":{"shasum":"95cc543d5ffcd7d00852ba4e5ada1d34dea29676","tarball":"https://registry.npmjs.org/n8n-mcp-guard/-/n8n-mcp-guard-1.2.2.tgz","fileCount":43,"integrity":"sha512-Cakk0bvw5Pr8W/5vj0r8eKD8RW/Ue4HB/B5vDw2hiNUg+ANKP2JJzZcnZs3GbJhXHkJpASqNBOxGCfX/e3nIyA==","signatures":[{"sig":"MEQCIHPZO6tXl2af1LJxuEtgyaaY2PIKm+64kFIvx+EhkpTSAiAgz42VEtYUw3IaApQajHS/QaptiEVRpPKXW/w9/e6q6w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDWrlgLOU+y7ZB+OHULF50d7dvj2S96dVI+8uTDX64gxAiAed4V9I6SXDX3731cxnN2XwucUzJcytW9FKKLIXqlquw=="}],"unpackedSize":179772},"name":"n8n-mcp-guard","type":"module","author":{"name":"Faraz Hayder"},"engines":{"node":">=22"},"gitHead":"7ec7c7daa556f98803c11b346a268282b0889d94","license":"MIT","scripts":{"dev":"tsx src/index.ts","test":"vitest run","build":"tsc -p tsconfig.json","check":"npm run typecheck && npm test && npm run build && npm run smoke","smoke":"node scripts/smoke.mjs","start":"node dist/index.js","prepare":"npm run build","typecheck":"tsc --noEmit","prepublishOnly":"npm run check","test:integration":"node scripts/integration.mjs"},"version":"1.2.2","_npmUser":{"name":"farazhayder","email":"farazhayder2004@gmail.com"},"homepage":"https://github.com/FarazHayder/n8n-mcp-guard#readme","keywords":["n8n","mcp","model-context-protocol","modelcontextprotocol","automation","ai-agents","claude-code","codex"],"repository":{"url":"git+https://github.com/FarazHayder/n8n-mcp-guard.git","type":"git"},"_npmVersion":"11.19.0","description":"Safety-conscious MCP server for n8n workflow inspection and controlled automation changes","directories":{},"maintainers":[{"name":"farazhayder","email":"farazhayder2004@gmail.com"}],"_nodeVersion":"24.20.0","dependencies":{"zod":"^3.23.8","dotenv":"^16.4.5","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.0","vitest":"^2.1.9","typescript":"^5.5.3","@types/node":"^20.14.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/n8n-mcp-guard_1.2.2_1789176897504_0.6094739170460541"}}},"time":{"created":"2026-09-12T01:01:43.519Z","modified":"2026-09-12T01:34:57.764Z","1.1.0":"2026-09-12T01:01:43.910Z","1.2.0":"2026-09-12T01:19:53.013Z","1.2.1":"2026-09-12T01:30:51.383Z","1.2.2":"2026-09-12T01:34:57.595Z"},"bugs":{"url":"https://github.com/FarazHayder/n8n-mcp-guard/issues"},"author":{"name":"Faraz Hayder"},"license":"MIT","homepage":"https://github.com/FarazHayder/n8n-mcp-guard#readme","keywords":["n8n","mcp","model-context-protocol","modelcontextprotocol","automation","ai-agents","claude-code","codex"],"repository":{"url":"git+https://github.com/FarazHayder/n8n-mcp-guard.git","type":"git"},"description":"Safety-conscious MCP server for n8n workflow inspection and controlled automation changes","maintainers":[{"name":"farazhayder","email":"farazhayder2004@gmail.com"}],"readme":"# n8n-mcp-guard\n\n[![npm version](https://img.shields.io/npm/v/n8n-mcp-guard.svg)](https://www.npmjs.com/package/n8n-mcp-guard)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)\n[![CI](https://github.com/FarazHayder/n8n-mcp-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/FarazHayder/n8n-mcp-guard/actions/workflows/ci.yml)\n\n**Let an AI agent build and change your n8n workflows — with a guaranteed way back.**\n\nAgents are good at writing workflow logic and bad at knowing when they have\nbroken something. `n8n-mcp-guard` sits in between. Every change is backed up\nbefore it happens, checked against the exact version it was designed for, and\nverified against the live instance after saving. If anything does not line up,\nthe write is refused rather than attempted and hoped for.\n\nSet it up once, use it from any MCP-capable agent, in every repository.\n\n## Who it's for\n\n**You're building something new.** Describe the automation you want, let the\nagent write it, and create it as an inactive workflow you can inspect before\nanything runs. Iterate with a reviewable diff at every step. You never have to\nread raw JSON to know what changed, and you can always get back to the last\nversion that worked.\n\n**You have something already running.** The workflow that quietly emails your\ncustomers or syncs your orders is the one you least want an agent improvising\non. Here, a change to it is a two-phase commit: plan it, review the diff,\nrehearse it on a disposable clone with every trigger and outbound call\ndisabled, then commit — and only if nothing moved underneath you in the\nmeantime.\n\n## Why you can trust it\n\n- **68 unit tests** covering every path where a write is supposed to be refused,\n  plus a **live integration suite** that drives the write tools through the real\n  MCP surface against a real n8n instance: create, plan, apply, stale-plan\n  refusal, clone neutralization, the delete guard, and verified cleanup.\n  Run it yourself with `npm run test:integration`.\n- **Validated against a real instance**: workflow fingerprinting, diffing,\n  clone construction and the backup gate were run across **99 real production\n  workflows** spanning **40 distinct node types**, correctly neutralizing\n  **114 triggers** and **304 outbound nodes** — zero failures.\n- **Nothing can write until you say so.** With no write token configured, the\n  mutating tools are not merely unused, they are never registered at all.\n- **CI on Node 22 and 24.** MIT licensed. No telemetry, no network calls except\n  to your own n8n instance.\n\n## Quick start\n\n**1. Install**\n\n```bash\nnpm install -g n8n-mcp-guard\n```\n\n**2. Configure once, for every project**\n\nCreate one file and every repository is covered:\n\n- Windows: `%APPDATA%\\n8n-mcp-guard\\.env`\n- macOS / Linux: `~/.config/n8n-mcp-guard/.env`\n\n```dotenv\nN8N_BASE_URL=https://your-instance.example.com\nN8N_API_KEY=your-api-key\n\n# Set this to enable the write tools. Leave empty for a read-only server.\nMCP_WRITE_AUTH_TOKEN=a-long-random-value\n```\n\nCreate the API key in n8n under **Settings → n8n API**.\n\n**3. Register with your agent, once**\n\n```bash\n# Claude Code\nclaude mcp add --transport stdio --scope user n8n-guard -- n8n-mcp-guard\n\n# Codex\ncodex mcp add n8n-guard -- n8n-mcp-guard\n```\n\nBoth register at user scope, so the server is available in every repository\nwithout adding anything to any project. Nothing goes in your project's\n`package.json` — an MCP server is a process your agent launches, not a\ndependency you install per repo.\n\n## How a change actually works\n\n```text\nn8n_plan_workflow_update    backs up, diffs, hands you a plan_id\n      ↓                     you read the diff and agree to it\nn8n_create_test_clone       rehearse: no triggers, no outbound calls\nn8n_delete_test_clone       cleaned up, verified gone\n      ↓\nn8n_apply_workflow_update   commits only if nothing moved; verifies by readback\n```\n\nWhat that buys you, concretely:\n\n- **Plan and apply are separate.** The plan records a fingerprint of the exact\n  live state your change was designed against. If a colleague edits the\n  workflow in the n8n UI while you are reviewing the diff, the apply aborts —\n  including the case where the content changed but the version ID did not.\n- **A backup must exist to write.** Not advice in a document: the apply step\n  looks for a checksum-verified backup of that exact version and refuses\n  without one. Tampered backups do not count.\n- **The result is proven, not assumed.** After saving, the graph is re-fetched\n  and fingerprinted. An instance that stores something other than what it was\n  sent fails loudly instead of reporting success.\n- **Rehearsals cannot reach the outside world.** A test clone has every trigger\n  and every outbound node — HTTP, email, Slack, Telegram, shell — disabled\n  unless you name an exception. The deleter refuses to touch any workflow that\n  isn't one of these clones.\n\n## Tools\n\nRead-only, always available:\n\n| Tool | Description |\n| --- | --- |\n| `n8n_get_workflow` | Workflow summary, or the full updateable definition. Never returns credential secrets. |\n| `n8n_diff_workflow` | Structured diff of a proposed definition against the live one. Stores nothing. |\n| `n8n_plan_workflow_update` | Phase 1: backs up, diffs, returns a `plan_id`. Changes nothing in n8n. |\n| `n8n_backup_workflow` | Writes a checksum-verified local backup. |\n| `n8n_list_test_clones` | Finds leftover rehearsal clones so nothing is left running. |\n\nWrite tools, registered whenever `MCP_WRITE_AUTH_TOKEN` is set:\n\n| Tool | Description |\n| --- | --- |\n| `n8n_create_workflow` | Creates a new workflow from an agent-authored definition. Always inactive, read back and verified, backed up immediately. |\n| `n8n_apply_workflow_update` | Phase 2: commits a plan only if the live workflow still matches it and a verified backup exists, then confirms by readback. |\n| `n8n_create_test_clone` | Inactive clone with every trigger and outbound node disabled unless explicitly allowed. |\n| `n8n_delete_test_clone` | Deactivates, deletes, verifies removal. Refuses anything that isn't a rehearsal clone. |\n| `n8n_restore_workflow_backup` | Restores from a backup as a normal plan, so it still shows a diff and needs an explicit apply. |\n\nEvery write additionally requires `approved: true` and the token on each call,\nso an agent cannot mutate anything by accident. To keep the server strictly\nread-only even with a token present, set\n`ENABLE_N8N_WORKFLOW_WRITE_TOOLS=false`.\n\n## Configuration\n\n| Variable | Required | Default | Purpose |\n| --- | --- | --- | --- |\n| `N8N_BASE_URL` | Yes | — | Instance root URL, or an explicit `/api/v1` URL. |\n| `N8N_API_KEY` | Yes | — | Created under Settings → n8n API. |\n| `MCP_WRITE_AUTH_TOKEN` | For writes | — | Long random value. **Setting it is what enables the write tools.** |\n| `ENABLE_N8N_WORKFLOW_TOOLS` | No | `true` | Registers the read-only tools. |\n| `ENABLE_N8N_WORKFLOW_WRITE_TOOLS` | No | `true` | Set `false` to force writes off even with a token configured. |\n| `N8N_MCP_BACKUP_DIR` | No | `<user config>/backups` | Where verified backups are written. |\n| `ENABLE_EXAMPLE_TOOLS` | No | `false` | Registers two topology-specific reference tools (see below). |\n\nValues resolve in this order, first match wins:\n\n1. **The process environment** — what your client passes in its `env` block.\n2. **`N8N_MCP_ENV_FILE`** — an explicit path to a dotenv file.\n3. **A `.env` beside the package** — how a cloned checkout is set up.\n4. **A user-level `.env`** — the path from the quick start above.\n\nOption 4 is recommended: your API key never appears in a client config file or\na project repository. On startup the server reports which source it used, on\nstderr.\n\n> Never commit a real `.env`. It is git-ignored here and excluded from the\n> published npm package.\n\n## Client setup\n\nAny client that speaks MCP over stdio works. Cursor, Windsurf, Claude Desktop\nand most others use this shape — check your client's docs for the file\nlocation:\n\n```json\n{\n  \"mcpServers\": {\n    \"n8n-guard\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"n8n-mcp-guard\"]\n    }\n  }\n}\n```\n\nWith a user-level `.env` in place, no `env` block is needed. VS Code uses the\nsame entry shape under a `servers` key instead of `mcpServers`; add it through\n**MCP: Add Server** in the Command Palette.\n\n## The division of labour\n\n**The server owns recoverability.** Backups, version matching, readback\nverification, clone neutralization and cleanup are enforced in code and\ncovered by tests. You can always get back to the version that worked.\n\n**You own judgement.** Whether the new routing is the routing you wanted, and\nwhether the test email read correctly, are calls only you can make. `CLAUDE.md`,\n`AGENTS.md` and the bundled agent skill encode that review procedure so your\nagent walks you through it rather than skipping it.\n\n### Bundled examples\n\n`n8n_test_supplier_email_action_routing` and\n`n8n_configure_supplier_email_action_routing` are worked examples of a\nworkflow-specific guarded tool built on the generic layer. They target one\nexact Shopify-triggered order-email topology, so they stay unregistered unless\nyou set `ENABLE_EXAMPLE_TOOLS=true`. Read `src/n8n/emailActionRouting.ts` and\n`src/n8n/emailActionTestClone.ts` if you want to build your own.\n\n## Install from source\n\n```bash\ngit clone https://github.com/FarazHayder/n8n-mcp-guard.git\ncd n8n-mcp-guard\nnpm ci          # also builds, via the prepare script\nnpm run check   # typecheck, tests, build, MCP handshake\n```\n\nThen point your client at the absolute path to `dist/index.js`.\n\n## Development\n\n```bash\nnpm run dev        # run from TypeScript source\nnpm run typecheck\nnpm test\nnpm run build\nnpm run smoke      # MCP handshake against the built server\nnpm run check      # all of the above\n```\n\nRun `npm run check` before opening a pull request.\n\n## Roadmap\n\n- Run the integration suite in CI against an ephemeral n8n container.\n- Generic execution rehearsal: drive a clone with synthetic input and assert\n  which nodes ran, without workflow-specific code.\n- Richer diffs, including expression-level changes inside Code nodes.\n\n## Contributing\n\nBug fixes, documentation, tests, safety hardening, and new *generic* n8n tools\nare all welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.\n\nNever include API keys, `.env` files, production workflow exports, customer\ndata, or anything from `n8n-workflow-backups/` in an issue or pull request.\n\n## Security\n\nSee [SECURITY.md](SECURITY.md). Report suspected vulnerabilities privately\nthrough GitHub's private vulnerability reporting, not a public issue.\n\n## License\n\n[MIT](LICENSE) © Faraz Hayder\n","readmeFilename":"README.md"}