Reference

n8n-MCP, end to end

How to run the server, connect it to Claude Code, and fix the failures that actually happen. Written from production use, not from the README.

n8n-MCP connects an AI coding client to a live n8n instance. Instead of pasting workflow JSON back and forth, the model reads your node catalogue and your existing workflows, then builds against the versions you actually run. The setup is short. The failures are repetitive, and nearly all of them happen in the same three places.

Setup

1. Run the server

The published image is ghcr.io/czlonkowski/n8n-mcp. Run it with your n8n base URL and an API key created in n8n under Settings, then n8n API. The key needs full access: MCP tooling reads the node catalogue as well as your workflows.

docker run -i --rm \
  -e N8N_API_URL="https://your-n8n-host" \
  -e N8N_API_KEY="<your key>" \
  ghcr.io/czlonkowski/n8n-mcp

2. Register it with Claude Code

Add the server to your MCP config. Claude Code reads it on start, so restart the session after editing. If the tools do not appear, the config was not picked up: that is far more often the cause than a broken server.

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "N8N_API_URL",
               "-e", "N8N_API_KEY",
               "ghcr.io/czlonkowski/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n-host",
        "N8N_API_KEY": "<your key>"
      }
    }
  }
}

3. Verify before you build

Ask the model to list your workflows. If that returns real names, the transport, credentials and permissions are all good and any later failure is a workflow problem rather than a connection problem. Establishing that boundary early saves most of the debugging time.

When it breaks

Ordered by how often they come up in practice.

The MCP tools never appear in Claude Code

Almost always the config file, not the server. Confirm you edited the config Claude Code actually reads, and restart the session fully. A running container proves nothing on its own: the client has to be told about it.

401 or 403 from the n8n API

The API key is wrong, expired, or was created on a different n8n instance than N8N_API_URL points at. Regenerate it in the same instance you are targeting. Watch for a trailing slash on the URL, which is a common cause.

Connection refused when n8n is self-hosted

Inside a container, localhost is the container, not your machine. Use the host gateway address or the service name on the shared Docker network. This is the single most common self-hosting failure.

The agent writes workflows that will not import

Usually invented node types or an incompatible version. Ask it to read an existing working workflow first so it copies your actual node shapes rather than guessing from training data.

It edits the wrong workflow

Identify workflows by ID rather than name. Names are not unique in n8n and a fuzzy name match will happily overwrite the wrong thing. Take a backup export before letting anything write.

Frequently asked

What is n8n-MCP?

An MCP server that exposes your n8n instance to an AI coding client such as Claude Code, so the model can read the node catalogue, inspect existing workflows, and create or edit them through the n8n API rather than by pasting JSON.

Is it safe to point at production n8n?

Only with deliberate limits. The API key it uses can modify workflows, so start against a non-production instance, export backups before granting write access, and review every change before activating it.

Does it work with clients other than Claude Code?

Yes. It speaks the Model Context Protocol, so any MCP-capable client can use it. The configuration format differs per client but the server and credentials are identical.

Why do generated workflows fail to import?

The model has invented a node type or used parameters from a different n8n version. Have it read a working workflow from your instance first so it mirrors the node shapes you actually run.

Still stuck?

The full n8n MCP and Claude Code guide covers setup, config and the common errors step by step.

Read the full guide →