Connect n8n to Claude Code via MCP: Build and Run Workflows From Prompts

To use n8n MCP in Claude Code, turn on Instance-level MCP in your n8n settings, run claude mcp add --transport http n8n https://<your-n8n-domain>/mcp-server/http, then approve the connection from /mcp inside Claude Code. After that, Claude Code can search your workflows, write new ones as code, validate, test, run and publish them, within the scopes you grant and the workflows you expose.

Checked October 2026 against n8n's docs on connecting to the n8n MCP server, its client examples and tools reference, the Claude Code docs on MCP and permissions, and the source of n8n 2.42.6. n8n ships MCP changes in most releases, so feature versions are noted where they matter.

This guide belongs to our n8n hub. It goes end to end: connect, build a workflow from a prompt, test it, run it, and put limits around the whole thing. The limits get the most space here, because an agent with write access to your automations deserves more thought than a one-line install.

Which "n8n MCP" is this?

The one built into n8n. Three different things answer to the name, and tutorials mix them up:

The rest of this page uses the first one. If MCP itself is new to you, our plain-language MCP guide covers hosts, clients and servers first.

What you need before you start

If Claude Code is not installed yet, start with our install walkthrough. For a local n8n to practise on, the Docker Compose setup guide sets one up on your own machine.

How to use n8n MCP in Claude Code: the setup

The command, from n8n's client examples:

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

By default Claude Code stores the server for the current project only. Add --scope user to have it in every project, or --scope project to write a .mcp.json file your team can share. The same entry as JSON:

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

OAuth or the API key?

Use OAuth. n8n recommends it, and it is the only route that lets you limit what Claude Code can do. The API key tab hands out a personal access token tied to your user, and n8n's source is explicit that such a token "grants access to all tools" (mcp-scopes.ts).

Claude Code n8n workflow: build, test and run one from a prompt

Once connected, you work in sentences. Start with something small and say where it should stop:

Use the n8n MCP server. In my personal project, build a workflow named
"Lead intake": a Webhook trigger that receives { email, message },
an If node that drops empty messages, and a Slack node that posts the
message to #leads. Validate it, create it, then test it with pinned data.
Do not run it for real and do not publish it.

What happens next is a fixed sequence of tool calls. Knowing it lets you spot when the agent cuts a corner:

Four behaviours from the tools reference matter in practice:

• A workflow built over MCP is exposed over MCP. create_workflow_from_code sets the Available in MCP flag on what it creates, so every connected client can reach it from then on.
• A test is not a sandbox. test_workflow pins triggers, nodes with credentials and HTTP Request nodes. Other nodes run for real, including credential-free ones that execute commands or write files.
• Manual mode uses real credentials. execute_workflow in manual mode runs the current draft against live services. If the Slack node is real, the message is sent.
• Runs are asynchronous. execute_workflow returns an execution ID immediately. Claude Code has to call get_workflow_execution to see whether the run passed.

Editing follows the same pattern. update_workflow applies a batch of targeted changes and saves nothing if one fails. It can also set workflow settings, including the error workflow, so "add error handling to this workflow" is a fair request. Read our Error Trigger guide first, because the handler has to exist and be published before the link does anything.

Guardrails: read-only mode, scopes and what Claude Code may touch

Limit the connection in four places, because each one covers a gap the others leave. n8n decides which workflows are reachable and which tools a client holds. Claude Code decides which of those tools run without asking you.

1. Expose workflows on purpose

A client cannot read, run or change a workflow until you mark it Available in MCP. Three caveats from the docs: search_workflows still returns previews of every workflow your user can view, exposure is not per client (every connected client sees the same set), and Auto-expose new workflows is off by default. Leave it off.

2. Grant scopes per client

On the approval screen, Read only lets a client view workflows and data without making changes. Custom lets you tick individual scopes. This is how the scopes map to tools in n8n 2.42.6:

Note where publishing sits: inside workflow:write. A client that can edit a workflow can also publish it, so n8n alone cannot give you "may draft, may not ship". That gap is what the next layer closes.

3. Add permission rules in Claude Code

Claude Code names MCP tools mcp__<server>__<tool> and accepts them in allow, ask and deny rules. Put this in .claude/settings.json in the project where you work on n8n:

{
  "permissions": {
    "allow": [
      "mcp__n8n__search_workflows",
      "mcp__n8n__get_workflow_details",
      "mcp__n8n__validate_workflow"
    ],
    "ask": [
      "mcp__n8n__update_workflow",
      "mcp__n8n__execute_workflow"
    ],
    "deny": [
      "mcp__n8n__publish_workflow",
      "mcp__n8n__unpublish_workflow",
      "mcp__n8n__archive_workflow"
    ]
  }
}

Deny rules win over everything else, so publishing stays a human job even in a session where you have approved other tools. The names assume you called the server n8n in claude mcp add; change the middle segment if you used another name.

4. Shrink the account behind the connection

MCP access is user-scoped: a client sees only what the connecting user can see. Connecting as the instance owner hands the agent the whole instance. Where your plan allows extra users and projects, connect as a member who can reach only the sandbox project. Owners and admins can also set Allowed callback URLs to Only trusted URLs, and revoke any client from Connected clients.

Should you add the official n8n Skills?

Yes, once the plain connection works. The MCP server gives Claude Code the tools, but not n8n's conventions for expressions, loops or error handling. The n8n Skills repository, built by the n8n team, adds 13 capability skills and hooks that load the right guidance before high-impact MCP calls. Inside a Claude Code session:

/plugin marketplace add n8n-io/skills
/plugin install n8n-skills@n8n-io
/reload-plugins

The installer asks for your instance URL (the base URL, without a path) and bundles its own MCP connection named n8n-mcp. If you already added a server called n8n, you now have two copies of every tool, and the README says to disable the duplicate from /mcp. Mind the names when you do: Claude Code calls a plugin's tools mcp__plugin_<plugin>_<server>__<tool>, so rules written for mcp__n8n__ do not cover the plugin's copy. Deny and ask rules accept wildcards, so mcp__*__publish_workflow blocks publishing through either one. For other servers worth pairing with it, see our list of the best MCP servers for coding.

Connecting tools is one module of a bigger skill set. Our AI SaaS Builder program spends two modules on Claude Code and MCP, including building your own MCP server and wiring MCP into a product you sell.

Troubleshooting the n8n MCP connection

Most failures are one of seven, and each has a specific message. Check /mcp in Claude Code first, then the n8n settings page.

If Claude Code itself is the unfamiliar part, our Claude Code complete guide explains permission modes, settings files and the /mcp panel in more depth.

n8n MCP and Claude Code: FAQ