How to Connect n8n to Claude Code With MCP (Build Workflows From Your Terminal) | Simple AI Tools
Simple AI Tools.
AboutContactPrivacyTerms

How to Connect n8n to Claude Code With MCP (Build Workflows From Your Terminal)

Reading time
How to Connect n8n to Claude Code With MCP (Build Workflows From Your Terminal)

Stop Using the Old n8n MCP Server: The Official Claude Code Setup Nobody Told You About

A complete, verified walkthrough for connecting Claude Code to n8n's built-in MCP server — and building real workflows without ever opening the visual editor.




Here is an uncomfortable truth about most of the "n8n + Claude Code" tutorials currently ranking on Google: they are teaching you an architecture that n8n has already replaced.

Almost every guide you will find walks you through installing a third-party npm package, pasting an n8n API key into a shell command, and wiring up a local stdio process. That approach still works. It is a genuinely excellent project. But it is no longer the default answer, and if you set things up that way in 2026 without knowing the alternative exists, you are choosing a harder path for reasons you never actually evaluated.

Because n8n now ships its own built-in, instance-level MCP server — with OAuth, per-workflow access control, revocable client permissions, and an official Claude Code connection flow that takes a single terminal command.

This guide covers both paths, explains precisely when each one wins, and gives you the exact commands to get from zero to "Claude Code just built and deployed my workflow" without guessing.

The Myth: "You Need the n8n-mcp Package"

Let us be precise about what is being busted here, because the community package is not bad software. It is very good software, maintained actively, and it does something the built-in server does not.

The myth is not "n8n-mcp is broken." The myth is "n8n-mcp is the only way."

These two tools solve genuinely different problems:

The built-in instance-level MCP server answers: "What is in my n8n instance, and can you change it?"

It connects directly to your live instance. It can search your workflows, read their structure, create new ones, edit existing ones, trigger test executions, and work with your data tables. Authentication is centralised through OAuth, and every connected client shows up in a management panel where you can review or revoke its access individually.

The community n8n-mcp package answers: "How does node X actually work?"

It is fundamentally a documentation and validation layer. It indexes thousands of n8n nodes — core and community — with property schemas, operations, and extracted real-world configurations from popular templates. Where the built-in server gives your agent access, the community package gives your agent knowledge.

The genuinely optimal setup for most people is not choosing between them. It is understanding that the built-in server is your foundation, and deciding afterwards whether you need the extra node-documentation layer on top.

Prerequisites You Actually Need

✅ Checklist before you run a single command

  • A running n8n instance — Cloud or self-hosted. Self-hosted works fine, but see the reverse-proxy note in the security section.
  • Instance owner or admin permissions — enabling MCP access is an admin-level action.
  • Claude Code installed and authenticated on your machine.
  • A reasonably current n8n version. Workflow building through MCP arrived in n8n 2.13.0. The guided per-client connection dialog arrived in 2.33.0. If you are on something older, you can still connect manually — the commands below work either way.
  • Public reachability if you plan to use cloud-based MCP clients. A purely localhost instance will connect fine to a local Claude Code, but not to web clients.

Step 1 — Enable Instance-Level MCP in n8n

This is a deliberate, explicit switch. Nothing is exposed by default, which is exactly how it should be.

  1. Open your n8n instance and navigate to Settings → Instance-level MCP.
  2. Select Enable MCP access. You need owner or admin rights for this button to appear.

Once enabled, that settings page reorganises into three sections that are worth understanding before you go further:

Section What It Controls
Connection details Shows MCP status and the Connect button that opens client-specific setup steps. Your Server URL lives here.
Access How many workflows (and agents, if enabled) are exposed. Admins also configure Allowed callback URLs here.
Connected clients Every OAuth client currently holding access, its permission level, and a per-client revoke action.

If you are self-hosting and want the feature gone entirely rather than merely switched off, set the environment variable N8N_DISABLED_MODULES=mcp. That removes the endpoints and hides the UI completely.

Step 2 — Connect Claude Code (OAuth or API Key)

You have two authentication routes. Use OAuth unless you have a specific reason not to.

Option 1 — OAuth (recommended)

One command. Replace the domain placeholder with your actual n8n domain, which you will find under Settings → Instance-level MCP → Connect a client → Server URL.

claude mcp add --transport http n8n https://<your-n8n-domain>/mcp-server/http

Then, inside Claude Code, run /mcp and select n8n to complete the OAuth authorisation in your browser. Approve the access request when n8n redirects you, and you are connected.

Prefer editing config directly? The equivalent entry in your claude.json is:

{
    "mcpServers": {
        "n8n": {
            "type": "http",
            "url": "https://<your-n8n-domain>/mcp-server/http"
        }
    }
}

Option 2 — API key (bearer token)

Open the Connect a client dialog and switch to the API key tab. n8n generates a personal access token tied to your user account the first time you open it.

⚠️ Copy it immediately. Once you leave that tab, n8n only ever shows a redacted value. Your only recovery path is rotating the token — which revokes the old one and forces you to update every connected client.

claude mcp add --transport http n8n-mcp https://<your-n8n-domain>/mcp-server/http \
  --header "Authorization: Bearer <YOUR_N8N_MCP_TOKEN>"

Or as a config entry:

{
    "mcpServers": {
        "n8n-mcp": {
            "type": "http",
            "url": "https://<your-n8n-domain>/mcp-server/http",
            "headers": {
                "Authorization": "Bearer <YOUR_N8N_MCP_TOKEN>"
            }
        }
    }
}

One operational difference worth knowing: clients authenticating with an API key do not appear in the Connected clients panel, because they use a bearer token rather than an OAuth connection. If you want per-client visibility and revocation, that alone is a strong argument for OAuth.


Step 3 — Expose Workflows Without Over-Exposing

This is where people either set things up sensibly or accidentally hand an agent far more reach than they intended. Understanding the exposure model properly takes about ninety seconds and saves genuine grief.

The rule that surprises people

Enabling MCP at the instance level does not expose your workflows. You must additionally enable each workflow individually.

There is exactly one carve-out, and it matters: the search_workflows tool can see every workflow the connected user has permission to view — regardless of the "Available in MCP" setting. It returns previews only, never full workflow data, but if you assumed an un-exposed workflow was completely invisible, it is not. Its name and metadata are discoverable.

Eligibility requirements

A workflow can only be MCP-enabled if it is published and contains a webhook, form, schedule, or chat trigger node. If the toggle is missing, that is almost always why.

Three ways to enable a workflow

  • From MCP settings: Settings → Instance-level MCP → Workflows exposed → Enable workflows.
  • From the editor: open the workflow, click the ... menu, choose Settings, toggle Available in MCP.
  • From the workflow list: open the card menu and select Enable MCP access.

For bulk operations, project and folder-level toggles arrived in n8n 2.24.0 — use the Options menu next to a project or folder name and choose Manage MCP access. Be aware this only affects workflows currently in that folder. Newly created ones are unaffected unless you turn on Auto-expose new workflows (rolling out gradually from 2.36.0, so it may not be visible on your instance yet).

Write descriptions — your agent reads them

An exposed workflow named "wf-final-v3-REAL" tells an agent nothing. n8n lets you attach a free-text description to each exposed workflow, either from the Workflows exposed page or via Edit description in the workflow menu. This is one of the highest-leverage five-minute investments in the entire setup: it is the difference between an agent confidently picking the right workflow and an agent guessing.

⚡ Here Is Where Most Setups Quietly Fail

At this point your connection works. You can ask Claude Code to list your workflows and it will. So people stop here — and then spend the next two weeks fixing broken expression syntax, malformed node parameters, and workflows that validate but never actually run.

The next step is the one that separates a demo from a working system. Keep reading.

Step 4 — Install n8n Skills (The Step Everyone Skips)

Connecting an agent to your n8n instance gives it hands. It does not give it expertise.

A freshly connected coding agent can call every MCP tool correctly and still produce workflows that fail, because it does not inherently know n8n's conventions: how expressions must be written, how specific nodes expect their parameters, how error handling should be structured, how sub-workflows pass data.

n8n's answer is a published set of capability modules in the n8n-io/skills repository. According to n8n's documentation, the set includes:

  • 13 capability skills covering workflow best practices — sub-workflows, expressions, loops, AI agents, error handling, credentials, data tables, and debugging.
  • 50+ reference documents and examples with per-node guidance, decision trees, and copy-paste workflow snippets.
  • Hooks that load the relevant guidance automatically before the agent makes high-impact MCP calls.
  • A 14th meta-skill, using-n8n-skills-official, which routes the agent to the right capability skill per task.

Because the install steps track the repository rather than the docs site, follow the README in n8n-io/skills directly for current instructions. The skills are plain Markdown — you can read them, fork them, and rewrite them to encode your own team's conventions, which is genuinely useful if you have house rules about naming, error routing, or credential handling.

Bonus: connect the n8n docs MCP server too

Separate from your instance server, n8n exposes its documentation as an MCP server. One command gives your agent searchable access to the official docs while it works:

claude mcp add --transport http n8n-docs https://docs.n8n.io/~gitbook/mcp

Step 5 — Build a Workflow From the Terminal

With the connection live and skills installed, the workflow loop looks nothing like clicking through a canvas.

Understand the tools your agent has

The instance-level server exposes tools across workflow management, workflow building, agent management, and data tables. A few worth knowing by name:

Tool Behaviour Worth Knowing
search_workflows Returns previews with filters for tags, folders and sort order. Result limit is 200, sorted by most recently updated. Sees all accessible workflows, not just exposed ones.
execute_workflow Defaults to production mode and runs the published version. Supports a manual mode to run the current unpublished version instead.
create_workflow_from_code Accepts a resolved project ID. If a user names a project, the agent should resolve it first rather than guessing.
list_workflow_tags Tags are global rather than project-scoped. Requires the tag:list permission and only works when tags are enabled.

🚨 The production-mode trap. Because execute_workflow defaults to production, a casual "just run it and see" instruction can trigger your live workflow — sending real emails, writing to real databases, hitting real paid APIs. Be explicit about manual mode when you are testing, and be deliberate about which workflows you expose at all.

The practical loop

A realistic session looks like this. Start by orienting the agent, then work incrementally rather than asking for a finished twelve-node workflow in one shot:

# 1. Orient
"List the workflows in my Marketing project and show me their descriptions."

# 2. Inspect before changing
"Get the full structure of the 'Lead Enrichment' workflow.
 Explain what each node does and where it could fail."

# 3. Build incrementally
"Create a new workflow in the Marketing project with a schedule trigger
 that runs daily at 09:00 UTC. Just the trigger for now — do not add
 downstream nodes yet."

# 4. Extend, one step at a time
"Add an HTTP Request node after the trigger. Include retry-on-fail
 and route errors to a separate branch."

# 5. Test deliberately
"Execute that workflow in manual mode and show me the execution output."

The reason this beats the visual editor for experienced builders is not raw speed on any single node. It is that describing intent in one sentence replaces a dozen clicks, dropdown hunts, and parameter-panel scrolls — and the agent can read an existing workflow's full structure faster than you can visually trace it.

Where it does not beat the visual editor: exploratory design when you do not yet know what you want, and debugging anything where seeing the data flow visually is the whole point. Use both.

Built-In Server vs Community n8n-mcp

Here is the honest comparison so you can choose deliberately rather than by whichever tutorial you found first.

Factor Built-In Instance MCP Community n8n-mcp
Primary purpose Access and control your live instance Deep node documentation and validation
Transport Remote HTTP Local stdio via npx
Auth OAuth or bearer token n8n API key in env vars (optional)
Access control Per-workflow, per-client, revocable Whatever the API key permits
Node knowledge Via separately installed n8n Skills Built in — thousands of indexed nodes
Works without n8n creds No Yes — docs/validation only mode

If you want to add the community server alongside the built-in one, the documented Claude Code command is:

claude mcp add n8n-mcp \
  -e MCP_MODE=stdio \
  -e LOG_LEVEL=error \
  -e DISABLE_CONSOLE_OUTPUT=true \
  -- npx n8n-mcp

Note that claude mcp add defaults to local scope, which keeps configuration in your global user settings and your keys private. Use --scope project only when you intend to commit an .mcp.json to a shared repository — and never with a token baked in.

Security Hardening You Should Not Skip

Restrict OAuth callback URLs

By default, n8n permits any callback URL to complete an OAuth sign-in — which is the less secure option. Go to Settings → Instance-level MCP → Access → Allowed callback URLs and switch to Only trusted URLs, then list the specific URLs you accept. This takes two minutes and meaningfully narrows your attack surface.

Audit connected clients regularly

Under Connected clients → View all you can see every OAuth client, its granted permissions, and when it connected. Revoking is immediate — the client must reconnect and sign in again. Make this a monthly habit, particularly if multiple people connect tools to a shared instance.

Fix your reverse proxy header allowlist

This one causes a disproportionate share of mysterious connection failures on self-hosted setups. MCP clients send three routing headers:

MCP-Protocol-Version
Mcp-Method
Mcp-Name

If n8n sits behind a reverse proxy, load balancer, or WAF that strips unknown headers or forwards only an allowlist, add all three. Otherwise clients may fail outright or silently fall back to an older protocol version — which produces confusing, intermittent behaviour rather than a clean error.

Understand what "not scoped per client" means

Every client you connect sees every workflow you have exposed. You cannot restrict specific workflows to specific clients. Visibility does remain user-scoped — users only see MCP-enabled workflows they already have access to — but within a single user's connections, exposure is all-or-nothing. Plan your exposure list with that in mind.


Troubleshooting Table

Symptom Most Likely Cause & Fix
Client will not connect at all MCP access not enabled at instance level, or the instance is not publicly reachable from your client.
Connects but sees no workflows Workflows are not marked Available in MCP, or they are unpublished, or they lack an eligible trigger node.
"Available in MCP" toggle missing Workflow is unpublished or has no webhook, form, schedule, or chat trigger.
Intermittent failures / protocol downgrade Reverse proxy stripping the three MCP headers. Add them to the allowlist.
Auth rejected with a valid-looking token Token was rotated. Generating a new one revokes the previous immediately — update every client.
Agent builds broken workflows n8n Skills not installed. The agent has access but not conventions.
Cannot find a specific error cause Check n8n server logs for MCP-related messages before assuming it is a client problem.

Frequently Asked Questions

What is the difference between instance-level MCP and the MCP Server Trigger node?

Instance-level MCP creates one connection per n8n instance with centralised authentication, letting you choose which workflows to expose. The MCP Server Trigger node is configured inside a single workflow and exposes tools only from that workflow — useful when you want to craft specific MCP server behaviour within one workflow rather than instance-wide access.

Do I need an n8n API key to connect Claude Code?

Not for the built-in server — OAuth is the recommended path and requires no manual key handling. An API key is only one of two available authentication options. For the separate community n8n-mcp package, API credentials are optional: without them you get documentation and validation tools only; with them you get workflow management too.

Can Claude Code create workflows, or only run existing ones?

Both. MCP supports running existing workflows through the execution tools, and building or editing workflows — the latter available from n8n 2.13.0 onward.

Will connecting MCP expose all my workflows?

No. You must enable MCP at the instance level and then enable each workflow individually. The single exception is search_workflows, which can discover previews of any workflow the current user can view — but it returns previews only, never full workflow data.

Why does my agent write workflows that fail validation?

Because MCP access alone does not teach n8n conventions. Install the official n8n Skills from the n8n-io/skills repository — they load the right guidance at the moment the agent needs it, rather than relying on the model's general knowledge.

Can I turn the MCP feature off completely?

Yes. Disable it from Connection details — which disconnects and revokes access for every connected client — or, on self-hosted instances, remove the feature entirely with the environment variable N8N_DISABLED_MODULES=mcp.

The Takeaway

The myth this article set out to bust was never that the community package is bad. It was that you have only one option, and that option involves npm packages and pasted API keys.

You have two. The built-in instance-level MCP server is now the default answer for connecting Claude Code to a live n8n instance: one command, OAuth, per-workflow control, revocable clients. The community package remains genuinely valuable as a node-knowledge layer on top.

Set up the built-in server first. Install the official Skills second — that is the step that turns a working connection into a working system. Then decide whether you need anything else at all.

One last practical note: n8n ships fast, and several features referenced here have specific version gates. If a menu or toggle does not match what you see, check your n8n version before assuming something is broken.

🚀 Stay Connected With Simple AI Tools

Practical AI automation guides, tools and workflows — no fluff.

👇 💬 Drop your comment below and let us know your thoughts! ✨

The AI Explorer

Written by

The AI Explorer

Contributor at Simple AI Tools, covering AI tooling, applied machine learning and developer workflows. Every tool featured here is tested hands-on before it is written about.

  • Hands-on tested
  • Independent reviews
  • Updated

Related Articles

Comments

Post a Comment

Share