n8n MCP Server: Complete Guide (2026)

One-sentence definition

The n8n MCP server (czlonkowski/n8n-mcp) is a Model Context Protocol server — a standard adapter that exposes tools to an AI client — that gives an agent complete knowledge of n8n’s node catalogue plus tools to build, validate, and execute n8n workflows from a natural-language request.

In practice: you install it into Claude Desktop, Claude Code, Cursor, or any MCP client, say “build me a workflow that watches a Gmail label and posts new threads to Slack,” and the agent searches the right nodes, generates a valid workflow, and — with an API key — drops it straight onto your n8n instance.

Two different things are called “n8n MCP”

This is the confusion worth clearing before anything else. Search “n8n MCP” and you get two unrelated capabilities pointing in opposite directions. Mixing them up is the single most common mistake in this space.

So: czlonkowski/n8n-mcp helps an AI build n8n. n8n’s native MCP nodes let n8n participate in the MCP ecosystem as a server or client. Different tools, different repos, different problems. The rest of this guide is about the first one. n8n’s own MCP nodes are documented in the n8n MCP Server Trigger docs.

One more wrinkle worth naming: in mid-2026 n8n shipped the ability for its own native MCP server to build and update workflows from a prompt, no external service required (n8n blog). That overlaps with what czlonkowski/n8n-mcp does. We compare the two below — the short version is the community server still wins on node-documentation depth and on working without an n8n login.

Why it exists

Ask a bare LLM to write an n8n workflow and it will confidently produce JSON that n8n rejects. n8n workflows are graphs of typed nodes, each with dozens of specific parameters, exact credential references, and connection rules the model half-remembers. The output looks plausible and fails to import. That is the status quo n8n-mcp was built to kill.

The fix is grounding. Instead of letting the model hallucinate node schemas, n8n-mcp ships a real index of every node — its properties, operations, and example configs — and exposes tools so the agent looks up the truth before it writes a line. Then a validate_workflow tool checks the result against n8n’s own rules before you ever try to run it. The agent stops guessing and starts reading the docs.

The named pieces

Four parts make up how this works. Keep these straight and the rest of the guide lands.

The takeaway: the build/validate half works offline and unauthenticated; the deploy/execute half needs an API key. You can get a lot of value before you ever paste a credential.

Install

The fastest path is the install panel below — pick your client, copy the snippet, done. It pulls configs from our catalog so it stays current.

One-line install · n8n

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

For Claude Code, the README’s one-liner registers the server over stdio with logging tuned down so console noise doesn’t corrupt the MCP stream:

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

That gives you the documentation and build tools. To unlock the management tools — creating and running workflows on your instance — add your n8n API credentials:

claude mcp add n8n-mcp \
  -e MCP_MODE=stdio \
  -e LOG_LEVEL=error \
  -e DISABLE_CONSOLE_OUTPUT=true \
  -e N8N_API_URL=https://your-n8n-instance.com \
  -e N8N_API_KEY=your-api-key \
  -- npx n8n-mcp

For Claude Desktop, Cursor, Windsurf, or VS Code, the equivalent JSON block goes in that client’s MCP config:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Generate the API key inside n8n under Settings → n8n API. There’s also a Docker image (ghcr.io/czlonkowski/n8n-mcp) and a Railway template if you’d rather run it hosted than via npx. Browse every client and its config path at mcp.directory/servers, or jump straight to the n8n server page.

Smallest end-to-end run

With n8n-mcp registered and an API key set, the smallest thing that proves the whole loop works is one prompt. In Claude Code or Claude Desktop:

> Build an n8n workflow: when a webhook receives a POST,
  send the body to a Slack channel. Validate it, then create
  it on my n8n instance.

The agent runs the tools in order. A typical trace:

search_nodes("webhook")        -> n8n-nodes-base.webhook
search_nodes("slack")          -> n8n-nodes-base.slack
get_node(slack)                -> message.post params + auth shape
validate_workflow(draft)       -> { valid: true, warnings: [] }
n8n_create_workflow(draft)     -> { id: "wf_8tQ...", active: false }

You get back a workflow ID and a link. Open it in n8n, attach your Slack credential (the agent can reference a credential but won’t paste your secrets), activate it, and the webhook is live. The first three calls needed no credentials; only the last one touched your instance.

The tools, walked through

n8n-mcp splits its toolset cleanly into two tiers. The split matters because it decides what you can do before handing over an API key.

Documentation & build tier (no key)

These let the agent learn n8n and assemble a workflow without ever connecting to your instance:

• search_nodes — find nodes by free-text (“send email”, “Postgres”, “if”).
• get_node — pull one node’s full property schema and operations.
• validate_node / validate_workflow — check a node config or a whole graph against n8n’s rules before you run it.
• search_templates / get_template — pull from a library of tested workflow templates as a starting point.
• tools_documentation — the agent’s self-help index for the rest of the toolset.

Management tier (needs N8N_API_KEY)

These read and write your live n8n instance over its REST API:

• n8n_create_workflow, n8n_get_workflow, n8n_list_workflows — create and inspect workflows.
• n8n_update_full_workflow / n8n_update_partial_workflow — edit an existing workflow, fully or surgically. The partial path is the one you want for small diffs.
• n8n_autofix_workflow — let the server repair a workflow it knows is broken.
• n8n_test_workflow / n8n_executions — trigger a run and read execution history.
• n8n_health_check / n8n_validate_workflow — confirm the instance is reachable and a deployed workflow is sound.

The opinionated takeaway: install with no API key first. Use the build tier to generate and validate a workflow, eyeball it, and only then add credentials. You get most of the value with zero blast radius on your instance.

What we got wrong

Three assumptions cost us time. Writing them down so they don’t cost you the same.

We assumed “n8n MCP” meant one thing. We spent a frustrating hour trying to get czlonkowski/n8n-mcp to expose a workflow as a tool to another agent — which is n8n’s native MCP Server Trigger’s job, not this server’s. The two answer opposite questions. Decide which direction you need before you install anything.

We thought we needed the API key to do anything useful. We didn’t. The entire build-and-validate loop runs with no credentials. We could have explored the whole node library and prototyped workflows before ever touching production. The key is only for the deploy step.

We let console logging corrupt the MCP stream. First install, the server kept dropping the connection. The cause: stdio MCP servers talk JSON over stdout, and n8n-mcp’s default logging was writing to the same channel. Setting LOG_LEVEL=error and DISABLE_CONSOLE_OUTPUT=true — which the README’s command already does — fixed it. If you hand-rolled your config and skipped those, that’s your dropped connection.

Right vs wrong patterns

Common mistakes

Who it’s for

The honest filter: if a 20-line Python script and a cron entry solve your problem, a workflow-automation platform plus an MCP server plus an agent is three layers of machinery you have to maintain. n8n-mcp earns its keep when n8n is already central to how you ship — not as a reason to adopt n8n.

Community signal

The “n8n MCP” tutorial wave is real — YouTube and newsletters are full of “Claude builds my n8n automations now” walkthroughs, and the maintainer (Romuald Członkowski, @czlonkowski) ships an accompanying n8n-skills set that teaches agents n8n expression syntax and workflow patterns. The enthusiasm is well earned — building n8n workflows by hand is fiddly, and grounding the agent in real node schemas genuinely cuts the error rate.

The contrarian case is worth hearing too. On a June 2026 Show HN for a workflow tool that takes a different tack, the founder argued that n8n’s format is the wrong target for agents:

“n8n does have an MCP server so agents can create workflows too, but it outputs raw JSON. That’s fine for n8n’s engine, but painful for a coding agent (or a human reviewing its output) to read, write, diff, or debug.”
— abhishekraj272, Hacker News, June 2026

That critique lands. n8n workflows are large JSON graphs; reviewing an agent-generated 40-node workflow in a diff is genuinely harder than reviewing 40 lines of code. n8n-mcp doesn’t solve the legibility problem — it makes the generated JSON correct, not readable. If your team treats workflows as code you diff and review, factor that in. A separate security thread on HN made the related point that n8n automations are often “invisible to security tools” — agent-generated ones are no exception, so review them like any other production change.

The verdict

The bigger picture

Two trends are converging. First, MCP is becoming the default way agents reach external systems, and workflow platforms are a natural target — n8n is just the most node-rich one. Second, the platforms are racing to make themselves agent-native from the inside: n8n now ships a native MCP server that builds workflows from a prompt with no external tool at all.

That raises a fair question: does the community server still matter once n8n does this natively? For now, yes. The community server’s deep node documentation index and its ability to research and validate without an n8n login give it an edge for development workflows. The native server is the better fit if you want zero setup inside n8n Cloud and don’t want to manage a separate MCP install. Expect both to coexist — and the line between them to keep moving. If you want the protocol fundamentals first, read what is MCP, and browse the broader catalogue under developer tools.

Frequently asked questions

Glossary

MCP

Model Context Protocol — a standard for exposing tools and data to an AI client over JSON-RPC.

n8n

A workflow-automation platform where you connect nodes into pipelines; self-hostable, with a free Community Edition.

Node

One step in an n8n workflow — a trigger, an app integration, a transform, or a condition.

stdio transport

An MCP server run as a local subprocess that talks JSON over standard input/output. n8n-mcp uses this via npx.

MCP Server Trigger

n8n’s native node that turns a workflow into an MCP server other agents can call. Not the same as czlonkowski/n8n-mcp.

MCP Client Tool

n8n’s native node that lets a workflow call an external MCP server mid-run.

N8N_API_KEY

A credential issued by your n8n instance that authorizes the management tools to read and write workflows.

Community node

A node published by the n8n community rather than the core team. n8n-mcp indexes these alongside core nodes.

Sources

Primary

• n8n-mcp repository & README: github.com/czlonkowski/n8n-mcp (MIT, by Romuald Członkowski)
• Claude Code setup doc: docs/CLAUDE_CODE_SETUP.md
• Companion skills: github.com/czlonkowski/n8n-skills

Documentation

• n8n MCP Server Trigger node: docs.n8n.io
• n8n native MCP server builds workflows: blog.n8n.io/n8n-mcp-server

Community

• Contrarian take on n8n’s JSON format for agents: Hacker News, June 2026
• n8n-mcp submissions on Hacker News: item 48134068

Internal

• n8n MCP server on MCP.Directory
• What is MCP?
• Developer tools category