n8n MCP + Claude Code: Setup, Prompts, Guardrails

I set up self-hosted n8n for clients, on Oracle Cloud's free tier and on Hostinger VPS servers, and I build with Claude Code every day (one recent client project, brand-locked listing documents, ships with a Claude Code handover). Put them together and you can describe a workflow in plain English while Claude looks up the nodes, builds it, checks it and runs it on your own instance.

The setup takes a few commands. The sharp edges are what the guides I read skip: four different things are called "n8n MCP", the project's own Claude Code doc gets scopes wrong, n8n-mcp now blocks localhost by default, its default test needs a live workflow, and its telemetry is on out of the box. One published guide even tells you to install @n8n/mcp-server, a package the npm registry returns a 404 for. Every command, version and limit below links to the official docs, the n8n blog or the project's GitHub as of 19 September 2026. Where the docs leave a gap, I say so.

Four things called "n8n MCP", and which ones build workflows

1. n8n-mcp, the community server. czlonkowski/n8n-mcp is an MIT-licensed MCP server built by Romuald Członkowski (AiAdvisors, Poland), not by n8n. It gives Claude documentation for n8n's nodes (the README currently lists 2,791), a validator, a template library and, once you add an API key, tools that create, edit, test and delete workflows on your instance. At the time of writing it is on v2.87.0 (16 September 2026), with over 22,000 GitHub stars. The project also offers a hosted version with a free tier of 100 tool calls a day. For client instances I'd run it locally with npx, so the n8n API key stays in your own Claude Code config.

2. n8n's built-in MCP server. Every n8n edition, Cloud and the free self-hosted Community Edition included, now ships its own instance-level MCP server. n8n's docs say building and editing workflows arrived in 2.13.0, and n8n announced it on 29 April 2026 as a public preview, recommending version 2.18.4 or later.

3. The MCP Server Trigger and MCP Client nodes. These build nothing. The MCP Server Trigger turns a single workflow into an MCP server so AI clients can call that workflow's tools. The MCP Client nodes go the other way and let a workflow call external MCP servers. If the protocol is new to you, start with what MCP is and how it works.

4. n8n's docs MCP servers. n8n also publishes two knowledge servers: a GitBook server that searches the docs, and a Kapa.ai server that also draws on the community forum and blog (it asks you to sign in). They answer questions and never touch your instance. The docs one is a single line: claude mcp add --transport http n8n-docs https://docs.n8n.io/~gitbook/mcp.

Only the first two build workflows, and both work in other MCP clients too (n8n-mcp's repo names Claude Desktop, Windsurf and Cursor). Running Claude Code from inside an n8n workflow is a different setup this post doesn't cover.

Which one should you use with Claude Code?

My take: pick the built-in server on a current n8n version if you want nothing to install, no credential creation and simulated test data. It isn't read-only, though. It can publish, unpublish and archive workflows and run the published version, so it needs guardrails too. Pick n8n-mcp for node docs and validation without an API key, template deploy, or tool filtering set in its environment. You can connect both under different names.

Step 1: create an n8n API key

n8n-mcp's management tools talk to n8n's public REST API. That needs a key. From n8n's API docs:

1. Log in to n8n and go to Settings > n8n API.
2. Select Create an API key.
3. Give it a label and set an expiration time.
4. On an Enterprise plan, choose the scopes.
5. Copy the key.

Three things to know before you paste it anywhere:

• The API isn't available during the n8n free trial. n8n's docs say to upgrade first. The n8n pricing breakdown covers the Cloud plans and the self-hosted route.
• Non-Enterprise keys have full access to everything your account can do. Scopes exist, but only on Enterprise. Treat the key like an admin password for your workflows.
• Use one labelled key per project or client, with an expiry. Then you can revoke one without breaking the rest.

Step 2: add n8n-mcp to Claude Code

You need Claude Code installed (see how to install Claude Code and Claude Code pricing) and Node.js 20 or later, which the published n8n-mcp package requires. Claude Code's syntax for a stdio server, one that runs on your machine, is claude mcp add [options] <name> -- <command> [args...]. Everything after the -- goes to the server untouched.

Turn off telemetry before the first run

n8n-mcp's privacy policy says telemetry is on by default. It collects sanitized copies of workflows you create, update or validate, plus the short "intent" text sent with each edit, partly to build workflow-generation datasets and models. Keys, credentials, your instance URL and execution data are excluded, but the policy says its pattern-based sanitization can't guarantee it catches every piece of sensitive data (a second, stricter pass runs server-side). Leaving it on also grants the maintainer a perpetual licence to what you submit, including the right to sublicense anonymized datasets to third parties.

Turning it off doesn't delete anything already sent, so I'd do it before Claude Code ever starts the server. The setting lives in a .n8n-mcp folder in your home directory, not on the n8n instance:

npx -y n8n-mcp telemetry disable
npx -y n8n-mcp telemetry status

Add the server

This is the command I'd start from for an instance on a public HTTPS domain:

claude mcp add n8n-mcp --scope user \
  -e MCP_MODE=stdio \
  -e LOG_LEVEL=error \
  -e DISABLE_CONSOLE_OUTPUT=true \
  -e N8N_API_URL=https://n8n.yourdomain.com \
  -e N8N_API_KEY=your-api-key \
  -e N8N_MCP_TELEMETRY_DISABLED=true \
  -e DISABLED_TOOLS=n8n_delete_workflow,n8n_manage_credentials \
  -- npx -y n8n-mcp

The first five -e lines come from the project's Claude Code setup doc. The rest are mine. N8N_MCP_TELEMETRY_DISABLED is documented for Docker, but n8n-mcp's telemetry code reads it everywhere, so it's a second lock. DISABLED_TOOLS removes the permanent-delete and credential tools. Drop N8N_API_URL and N8N_API_KEY for a docs-and-validation-only setup.

• That's for one instance. Across several client instances, drop --scope user and run the command inside each client's folder, so each folder only sees its own instance (scopes below).
• npx -y and pinning. The project's doc uses plain npx n8n-mcp. The -y skips npx's install prompt, which npm's docs say is assumed anyway when standard input isn't a terminal, as with a server Claude Code launches. It's harmless and explicit. Pin a version (npx -y n8n-mcp@2.87.0) if nothing should update mid-project.
• Running n8n on localhost? Since v2.50.2, n8n-mcp checks N8N_API_URL against an SSRF filter whose default strict mode blocks loopback addresses. Use http://localhost:5678 and add -e WEBHOOK_SECURITY_MODE=moderate, which the setup doc still omits. Private IPs need permissive, which the security doc calls suitable only for a shared private Docker or Kubernetes network, or a CGNAT overlay such as Tailscale.
• On native Windows, Claude Code's MCP quickstart says claude mcp add works in PowerShell and Command Prompt too, but the \ line breaks above are bash. Use Git Bash, or join the command into one line, then check what was stored with claude mcp get n8n-mcp. Skip WSL unless Claude Code runs there: WSL has its own home folder, so Windows Claude Code never sees what it writes.

Pick the right scope

n8n-mcp's setup doc describes the default local scope as if it were user scope. It isn't. Claude Code's MCP docs define three:

• Local (the default): loads only in the project folder where you added it, private to you, stored in ~/.claude.json (on Windows, C:\Users\YourName\.claude.json).
• User: loads in all your projects, private, same file.
• Project: written to .mcp.json in the project root and shared through version control. Claude Code asks for approval before using these.

One instance? Use --scope user. Several client instances? Keep local scope, one server per client folder. Either way the key sits in ~/.claude.json, so treat that file like a secret. Never commit a raw key in .mcp.json; Claude Code expands ${N8N_API_KEY} from your environment there. Scope is fixed at add time: to change it, remove and re-add.

Check the connection

Run claude mcp list to see each server's health status, or /mcp inside a session and select the server to see its tools. The first start can be slow while npx downloads the package, and the default startup timeout is 30 seconds. If it times out, launch with MCP_TIMEOUT=60000 claude, or in PowerShell $env:MCP_TIMEOUT = "60000"; claude.

Before building anything, ask Claude to run n8n_health_check, which checks instance health and API connectivity.

If it won't connect

• URL format. N8N_API_URL is your base URL, such as https://n8n.yourdomain.com. n8n-mcp's example config says "without /api/v1 suffix", whatever other guides tell you.
• Read the error. If claude mcp list reports "Failed to connect", run claude mcp get n8n-mcp. Recent Claude Code versions show the HTTP status or error code on an Issue: line.
• Key expiry. Check the key hasn't passed the expiry date you set in Step 1.
• Public API switched off. With N8N_PUBLIC_API_DISABLED=true (n8n recommends it if you don't use the API), the management tools have nothing to connect to.
• Behind Cloudflare Access? Add N8N_CF_CLIENT_ID and N8N_CF_CLIENT_SECRET, per the README.

Or connect n8n's built-in MCP server to Claude Code

An owner or admin turns it on under Settings > Instance-level MCP > Enable MCP access. The shortest official route from there is n8n's skills plugin. In Claude Code, run /plugin marketplace add n8n-io/skills, then /plugin install n8n-skills@n8n-io, enter your instance URL when prompted, and run /reload-plugins. Then open /mcp, select n8n-mcp and choose Authenticate. You get the connection plus skills that teach Claude n8n's conventions for expressions, node configuration and error handling. The plugin lists n8n 2.2.0 as its minimum, but building workflows needs 2.13.0 or later.

To connect by hand instead, n8n's client examples give:

claude mcp add --transport http n8n https://n8n.yourdomain.com/mcp-server/http

Run /mcp, select n8n and finish the OAuth sign-in. There's also an API-key variant that sends an Authorization: Bearer header with an MCP token. n8n's launch post says Claude Code got better results than Claude chat in its internal tests, with the same prompt and models.

For n8n-mcp, the same author's n8n-skills plugin plays that role: 14 skills, installed with /plugin install czlonkowski/n8n-skills.

Watch the names. n8n's docs call the API-key connection n8n-mcp, the same name as the community package, and Claude Code matches servers you add by name, so two called n8n-mcp collide. Give each a distinct name. The skills plugin adds its own n8n-mcp connection too (Claude Code files it under a plugin: prefix), so if you end up with the built-in server twice, disable one in /mcp.

Know what it can reach. Per the setup docs and tools reference, visibility isn't per client: every connected client sees every workflow enabled for MCP, search_workflows lists previews of every workflow your user can access whatever its MCP setting, and workflows the server creates are enabled automatically. Actions are per client: an OAuth client gets the permissions you grant when it connects (n8n's example is reading workflows without creating or running them), reviewable under Connected clients from n8n 2.33. API-key clients don't appear there.

Step 3: build n8n workflows with Claude Code (plan, copy, validate, test)

Near the top of its README, n8n-mcp puts it bluntly: "NEVER edit your production workflows directly with AI!" The loop below is built around that.

Give Claude house rules first

The project suggests pasting the README's "Claude Project Setup" instructions into a CLAUDE.md in your project folder. Its staged validation and "Never Trust Defaults" sections are worth keeping. Other parts pull against a plan-first, copy-only loop: "Execute tools without commentary", "Templates First", and a deployment step that creates a workflow and then tests it. I'd start from something like this:

# n8n rules for this project
- Plan first. Show me the trigger, every node, the credentials each one needs
  and what happens on failure, then wait for my OK.
- Only work in the workflow ID I give you. Never create, delete or archive workflows.
- Never publish, unpublish, activate or deactivate a workflow. If a test needs
  the workflow published, stop and tell me.
- Never create or change credentials. Tell me which ones to add in the n8n UI.
- Look up each node with get_node before configuring it, and set every
  parameter explicitly.
- Validate each node, then the whole workflow, before saving. Ask before any test run.

These are instructions, not locks. The guardrails section below covers the locks.

The loop, step by step

1. Work on a copy. For an existing workflow, Download it as JSON in the n8n editor, create a new empty workflow, use Import from File there, and give it a DEV prefix. For a new build, create an empty DEV workflow. Leave it unpublished either way. n8n's export docs warn that the JSON includes credential names and IDs, and HTTP Request nodes imported from cURL may carry auth headers, so mind where the file goes. Give Claude the DEV workflow's ID and tell it to touch nothing else. That's an instruction, not a permission: the key still reaches every workflow on the instance.

2. Plan before anything gets built.

Plan only, don't build yet. I want an n8n workflow that runs when a form is
submitted, checks the email domain, adds qualified leads to a Google Sheet and
posts a summary to Slack. List the trigger, every node in order, the credential
each node needs, and what happens when a step fails. Flag any place where two
nodes could do the job, and say which you'd pick and why.

The last line is there because n8n's April launch post listed wrong node picks when options overlap, and small unmentioned design decisions, among its own builder's rough edges. For AI agent workflows, the patterns in how to build an AI agent in n8n still apply.

3. Build with explicit parameters.

Build it in workflow <DEV workflow ID> only. Look up each node with get_node
before configuring it, and set every parameter explicitly instead of relying on
defaults. Don't create credentials. Tell me which ones to add in the n8n UI.

The README calls default parameter values "the #1 source of runtime failures".

4. Validate in stages. The README's pattern is validate_node in minimal mode, then full mode, then validate_workflow, and n8n_validate_workflow once it's on your instance. n8n_autofix_workflow only previews its fixes by default. Read the preview before you let Claude apply them.

5. Test on safe data, and know what "test" means. By default, n8n-mcp's n8n_test_workflow fires the workflow over HTTP through its webhook, form or chat trigger, and its tool docs say that path needs the workflow active. They also tell the model to activate workflows before testing, which your house rules forbid, so expect Claude to stop and ask here. That's intended. Then pick one:

• Publish the DEV copy yourself. First point it at a test sheet and a sandbox channel, check its webhook or form path differs from production's, and remove any Schedule trigger. Then let Claude test it, and treat that as a real run: emails go out, rows get written, APIs get called.
• Use pinned test data. With an N8N_MCP_ACCESS_TOKEN (the MCP key from Settings > Instance-level MCP, on n8n 2.34 or later), n8n-mcp can run method: 'prepare', then method: 'pinned', on an unpublished workflow, swapping trigger, credentialed and HTTP Request nodes for sample data. Every other node, Code nodes included, still runs for real. The workflow needs its "Available in MCP" setting on; I'd switch that on myself in the UI.
• Use the built-in server's test_workflow, which pins the same node types, and n8n's docs say most of its tools work on unpublished workflows. Set, If and Code nodes, and credential-free nodes like Execute Command, still run for real.

6. Review, then publish yourself. Compare before and after with n8n_get_workflow, or the local snapshots n8n-mcp takes before each change (n8n_workflow_versions). Those are a convenience, not a backup: n8n-mcp keeps the 10 most recent per workflow, and they miss edits made in the n8n UI. Then make the same change to the production workflow yourself and publish it in the UI.

One rule throughout: don't edit the workflow in the n8n UI while Claude is working on it. n8n-mcp's docs say every update writes the whole workflow back and n8n's public API has no conditional write, so UI changes made between Claude's read and its write get overwritten. If you do touch it, tell Claude to re-read. And iterate rather than restart, which is n8n's advice too.

Fixing a workflow that already fails

The same loop works for repairs. Give Claude the failed execution's ID and ask it to pull the details (n8n_executions with action: 'get', or get_workflow_execution on the built-in server), explain the cause in plain words, and propose a fix before touching anything. Apply it on the DEV copy, validate and test the same way, then carry it over yourself. Repairing failing workflows is the "Audits and fixes" part of my n8n consulting work.

Guardrails before you point it at a real instance

• Back up first. On a self-hosted server, n8n export:workflow --backup --output=backups/latest/ exports every workflow as separate, pretty-printed files (n8n CLI docs). On Docker, run docker exec -u node -it <n8n-container> n8n export:workflow --backup --output=<folder on a mounted volume>/ so the files outlive the container, then copy them off the server. Don't treat workflow history as your undo button: outside Enterprise, all users get versions from the last 24 hours, and Cloud Pro gets five days. For a full backup of the instance itself (database, encryption key and a tested restore), see my self-hosted n8n production checklist.
• The session has your key's power. n8n-mcp's security doc says whoever has the MCP session has the same privileges as the configured API key, and outside Enterprise that key can do everything. DISABLED_TOOLS removes whole tools; DISABLED_TOOL_OPERATIONS blocks single operations inside tools that bundle reads and writes, keeping list and get. For audit-only sessions, the README's read-only recipe uses both. This is its DISABLED_TOOLS line:

DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable

Copy its matching DISABLED_TOOL_OPERATIONS line too. It names every write operation of every tool that has one; without it, execution deletes, folder changes and version rollbacks stay available.

• Create credentials yourself. n8n-mcp can create them (n8n_manage_credentials has had a create action since v2.47.0), so guides saying agents can't are out of date. I'd still add every credential in the n8n UI and keep that tool disabled. No secret should pass through the chat. The built-in server has no create tool: it auto-assigns credentials you already have, except on HTTP Request nodes, where you attach them yourself.
• Keep deletion human. Disabling n8n_delete_workflow removes the tool that permanently deletes workflows. Other deletes sit inside bundled tools: executions, n8n-mcp's local snapshots, data tables and folders (deleting a folder without naming a target archives every workflow in it). Block them with something like this, using operation names from the README's full list and quoting the value because of the semicolons. Or add n8n_manage_datatable to DISABLED_TOOLS if you don't use data tables:

-e 'DISABLED_TOOL_OPERATIONS=n8n_executions:delete;n8n_workflow_versions:delete,rollback,prune;n8n_manage_folders:delete;n8n_manage_datatable:deleteTable,deleteRows,deleteColumn'

• Keep publishing human, and know the limits. n8n-mcp publishes (activates) workflows through the same partial-update tool Claude uses for edits, and its docs list no switch that blocks publishing alone. Worse, n8n-mcp's changelog says that on n8n 2.39 and later, saving a published workflow re-publishes it. With a normal key, an edit Claude saves to a live workflow is live at once, whatever your CLAUDE.md says. That's the real reason to work on an unpublished copy. On Enterprise, a key without the workflow:activate scope should make n8n keep changes as drafts (n8n-mcp reports PUBLISH_FORBIDDEN), though the changelog says that's untested with narrowed scopes.
• On the built-in server, block publishing yourself. It has publish_workflow, unpublish_workflow and archive_workflow, and execute_workflow can run the published version. The docs don't say whether an OAuth grant can allow edits but not publishing. Claude Code deny rules can. The pattern is mcp__<server>__<tool>, so with the server named n8n, add this to .claude/settings.json (copy exact tool names from /mcp; plugin servers use a longer mcp__plugin_ form):

{
  "permissions": {
    "deny": [
      "mcp__n8n__publish_workflow",
      "mcp__n8n__unpublish_workflow",
      "mcp__n8n__archive_workflow"
    ]
  }
}

• Watch for prompt injection. Workflow names, descriptions and execution results get fed to the model. Anyone who can edit a workflow, or send data into one through a form or webhook, could plant instructions there. Claude Code's docs say to verify you trust every server before connecting it.

Limitations to expect

• Coverage isn't complete. The n8n-mcp README lists 66.5% coverage of available node operations and 86% documentation coverage from n8n's official docs. For anything unusual, check the node in the editor.
• Complex branching needs review. In its April launch post, n8n's team said workflows with many conditional paths or nested logic often needed manual cleanup, and that it was working on it. Plan to review branching by hand with either server.
• No human-in-the-loop runs. The built-in server's execute_workflow doesn't support multi-step forms or human-in-the-loop steps.
• Big outputs hit caps and cost tokens. Claude Code warns when an MCP tool returns more than 10,000 tokens and limits output to 25,000 by default. The README puts one node's full documentation at roughly 3,000 to 8,000 tokens. The Claude Code cost calculator estimates what heavy use costs.
• Rate limits on n8n's server. n8n-mcp's docs report that n8n's built-in MCP server allows 100 requests per window per token (n8n's own docs don't state a limit). If you hit it, wait and retry.

When to hire help instead

Claude Code with n8n-mcp is a good way to get a first draft onto the canvas and iterate on it. It doesn't replace knowing why a workflow should be built a certain way, or owning it when it breaks. Bring in help when:

• the workflow touches money, customer messages or personal data, where one bad run costs more than the build;
• you manage several client instances and need separate keys, scopes and folders that never leak into each other;
• the instance itself needs HTTPS, Postgres, backups and updates, the setup behind my $0-a-month self-hosted AI stack, delivered for more than one client;
• the workflow is one piece of a bigger product with a front end, database and auth. That's full-stack AI app development, not just n8n.

See how I work as an n8n consultant, check how to hire an AI automation consultant for what to ask anyone, or book a 30-minute call and bring the workflow Claude drafted, so we can go through it before it goes live.

Sources

• n8n-mcp README: tool list, node and coverage figures, safety warning, hosted free tier, read-only recipe
• n8n-mcp Claude Code setup: the base claude mcp add command and its scope wording
• n8n-mcp self-hosting guide: npx behaviour and the localhost setting
• n8n-mcp security and hardening: SSRF modes, key privileges, prompt injection
• n8n-mcp official MCP setup: whole-workflow writes, the MCP token, the rate limit
• n8n-mcp test tool docs: test methods and the active-workflow requirement
• n8n-mcp workflow versions docs: local snapshot retention
• n8n-mcp tool definitions: inactive creation, autofix preview, folder delete, health check
• n8n-mcp example config: the N8N_API_URL format
• n8n-mcp privacy policy: telemetry defaults, what is collected, licence, opt-out
• n8n-mcp telemetry code: the telemetry environment variable and config location
• n8n-mcp changelog: credential create (v2.47.0), SSRF gate (v2.50.2), n8n 2.39 re-publish behaviour (v2.87.0)
• n8n-skills (community): skill count and install command
• Claude Code MCP docs: command syntax, scopes, health status, output limits, plugin names
• Claude Code MCP quickstart: Windows paths, shells, startup timeout
• Claude Code permissions: MCP deny rules
• n8n API authentication: key steps, free trial, scopes
• n8n, disable the public API: N8N_PUBLIC_API_DISABLED
• n8n built-in MCP server: enabling it, visibility, per-client permissions, skills
• n8n MCP client examples: Claude Code commands
• n8n MCP server tools reference: publish, archive, test and execution tools
• n8n docs MCP servers: the GitBook and Kapa.ai servers
• n8n MCP Server Trigger node: single-workflow MCP servers
• n8n workflow history: version retention by plan
• n8n export and import: Download, Import from File, credential warning
• n8n CLI commands: backup export and the Docker form
• n8n blog, MCP server announcement (29 April 2026): editions, public preview, recommended version, known rough edges
• n8n official skills: plugin install steps and minimum version
• npm exec docs: when npx assumes --yes

Checked on 19 September 2026 against n8n-mcp v2.87.0 and the n8n and Claude Code docs as published that day. Both projects change quickly, so re-check the linked docs before you rely on a specific flag.