How do you connect Claude Code to n8n through MCP, and what can the agent do then?

What does MCP add to Claude Code working with n8n?

MCP, the Model Context Protocol, is the standard through which an agent such as Claude Code attaches external tools. Without it the agent builds an n8n workflow from memory: it guesses node names, mixes up parameters, does not know what changed in the last release, and nobody checks whether the result will run in n8n at all.

n8n-mcp is an MCP server that closes that gap. I built it because agents promised to build automations on their own and in practice they guessed. The server gives an agent three things:

• Knowledge instead of guessing. Complete, current documentation for all 1,800+ n8n nodes, with configuration examples and templates from the library.
• Validation before running. Checks on a single node and on the whole workflow: required fields, connections, expressions, AI agent configuration. Errors surface before deployment, not after.
• Operations on a live instance. Creating, updating, validating and testing workflows, reading executions, managing credentials, folders and Data Tables, auditing instance security.

More than 143,000 people use it, including teams at Deutsche Telekom, PayPal, Mercado Libre, MIT and NYU.

How do you connect Claude Code to n8n?

One command in the terminal. The version with operations on your instance needs the n8n address and an API key, generated in n8n settings under "n8n API":

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

Without the last two variables the server runs in documentation-only mode: the agent knows the nodes and validates configurations but does not touch the instance. It is a good mode to start with, to see how the agent designs a workflow before you grant it write access.

If the instance sits behind Cloudflare Access, two more variables with the service token id and secret let the server through. If you use n8n Agents, a separate instance MCP access token enables agent management.

The same configuration works in Cursor, VS Code with Copilot, Windsurf, Codex and Antigravity; each has its own guide in the n8n-mcp repository.

Hosted or self-run n8n-mcp?

Two routes, the same server, different consequences.

Self-run, through npx as above or through the Docker image. n8n-mcp is open source and free, and nothing leaves your machine except calls to your n8n instance. In return you update the package after every release, make sure the node database keeps up with new n8n versions, configure environment variables for every client and ensure two clients do not launch npx with the same cache directory. The server runs locally, so you can connect it to Claude Code, Cursor or VS Code, but not to ChatGPT on the web or Claude in the browser: those need a server reachable from the internet.

Hosted at dashboard.n8n-mcp.com. Sign up, get an API key or use OAuth, connect your client. n8n instances, several at once if you like, are connected in the dashboard: address, key, done, with no environment variables and no configuration files. Updates, the node database and the infrastructure are my job. It works where a local server cannot: in ChatGPT on the web, in Claude in the browser and in any client that reaches MCP servers over the network. The free tier is 100 calls a day, enough to build and test a few workflows daily; paid plans raise the limit for teams that build all day.

People who live in a terminal and want everything on their own machine are fine with npx. Everyone else, especially teams without an engineer and anyone building workflows in ChatGPT or Claude in the browser, should take the hosted route.

What does the agent actually do when it builds a workflow?

n8n-mcp telemetry, published weekly in the n8n AI Automation Index, shows agents' work without retouching. In one week agents made 1.87 million tool calls and created 98,000 workflows.

• They read four times more than they write. 57% of calls read workflows, executions and lists; 15% write. Fetching executions alone is 28% of all calls: the agent checks what happened after a run before fixing the workflow.
• They work incrementally. Each workflow creation is followed by 9 updates. Large workflows grow through many small, checked changes, which is why workflows of 31–100 nodes fail validation less often than those of 2–3 nodes.
• They maintain more than they build from scratch. The most common first step of a session is reading an existing workflow, not creating a new one.

A well-configured agent works in a loop: node documentation, configuration validation, workflow creation, n8n-side validation, test, execution read, fix. The n8n skills for Claude Code, a separate package, teach the agent that loop and the conventions that avoid classic mistakes, such as putting agent instructions into the user message.

What won't the agent do well without you?

The same data shows where a person or a rule is needed.

Error handling. Only 2% of AI-built workflows have an Error Trigger. The agent builds the happy path because that is what it was asked for. Write a rule into the agent's memory: every production workflow, active and scheduled, gets an error workflow with an alert. Then nobody has to remember it for each automation.

Code instead of nodes. 74% of AI-built workflows contain a Code node, 60% an HTTP Request. The agent prefers writing JavaScript and calling an API to finding a ready-made integration with built-in authentication and pagination. A prompt that says to prefer native nodes, plus a review before activation, limits the debt someone will have to maintain later.

Connecting to the instance. 43% of agents' connection checks against the n8n API fail, three quarters of them because of a wrong address or an unreachable network. Instances behind a reverse proxy, with a non-standard path or without public access are the first thing to check at deployment. The second frequent case is a 403 error when fetching credentials: an API key created before an n8n update lacks the new permissions even though it looks complete in the UI. Rotating the key solves it.

Testing without a mess. Before the agent sends anything to a real system, disable action nodes with the D key, or have the agent log results to a Data Table and review them after a few days.

What tools does the agent get?

n8n-mcp exposes two groups of tools. The first always works; the second switches on once you provide the instance address and API key.

Group	Tools	Purpose
Documentation and validation	tools_documentation, search_nodes, get_node, validate_node, validate_workflow, templates	the agent checks how a node works and verifies a configuration before writing anything
Workflows	n8n_create_workflow, n8n_update_partial_workflow, n8n_validate_workflow, n8n_test_workflow, n8n_executions	creation, incremental changes, n8n-side validation, testing and reading the result
Instance	credentials, folders, Data Tables, workflow versions, security audit	housekeeping, auxiliary data and a review of webhooks and credentials
n8n Agents	n8n_manage_agents	managing agents through the instance's built-in MCP server, n8n 2.34 and later

Incremental updates matter here. The agent does not overwrite the whole workflow; it sends operations: add a node, change a field, add a connection, activate the workflow. Telemetry shows a typical edit is two to three such operations, and one in five is activating or deactivating a workflow, in other words the test loop: deactivate, fix, activate, check executions.

What does a good brief for the agent look like?

An example of a brief that regularly ends in a working workflow: "Build a workflow that every day at 7:00 fetches new rows from spreadsheet X, checks whether the Status field is empty, and sends me a summary on Telegram using the credential I have. Attach an error workflow with alerts. Do not activate until I confirm."

Four elements make the difference:

• Specific sources and credentials. The agent does not guess where the data is or which account to use.
• The business condition in words, not in terms of nodes. Choosing between an IF and a Filter node is the agent's job.
• Quality requirements stated explicitly: error handling, no activation without consent, a preference for native nodes. Whatever you do not write, the agent skips.
• Rules in the agent's memory instead of repeating them in every brief. The rule "every production workflow gets an error workflow", written once, applies to every automation that follows.

The n8n skills for Claude Code and ChatGPT add the conventions the agent cannot learn from documentation: where to put the instructions in the AI Agent node, how to return data from a sub-workflow, how to test without creating junk in systems. In the teams I work with the difference after installing the skills is obvious, and the skills are worth maintaining centrally because they do not update themselves.

How do you limit the damage when the agent gets it wrong?

An agent with write access to the instance can overwrite a workflow that used to work. A few rules from implementations:

1. A copy before the agent starts. n8n-mcp has a workflow-versions tool and n8n keeps history; even so, saving a copy before a bigger change costs a second and saves an hour.
2. Documentation-only mode to start. Without the address and API key the agent designs and validates but does not touch the instance. Grant write access once you have seen how it works.
3. A separate API key with an expiry for the agent, rotated every 90 days, instead of a key that never expires.
4. The instance behind Cloudflare Access or a VPN, with a service token for n8n-mcp, if it is not meant to be public.
5. Action nodes disabled during tests and logs to a Data Table instead of sends to real systems.

What does a team that builds this way look like?

At an e-commerce client, a team from finance, warehouse and sales has been building workflows through ChatGPT and Claude with n8n-mcp since May 2026. At the weekly session everyone asks their agent for the same thing, for example a generic error workflow with chat alerts, then to attach it to every active workflow, no clicking. A warehouse team member built an app for expiry-date stocktaking with n8n as the backend that way. The human role shifted from clicking nodes to describing the process, reviewing the result and deciding what is allowed into production.

It is the same method I use in my own implementations: agents build, I design, review and own the result.