cqbase.net · English & Chinese

CQBase

Context & Query Base

MCP

n8n MCP

An MCP server that lets Claude, ChatGPT, Cursor, and similar assistants debug, edit, and build n8n workflows.

czlonkowski/n8n-mcp is an MIT-licensed MCP server. It lets an MCP client operate n8n: debug, edit, validate, test, and build workflows. The agent works on the canvas, instead of only describing nodes in prose.

Connect it first to a test n8n instance that has no production secrets. Workflows often hold third-party tokens. If the agent can edit a node, it may also change those connections. Keep the scope small, and review a change before you enable it.

Mentioned by:

  • @HermesWatcher mentioned this project on 27 October 2026 (1149 likes and 126 reposts, captured 15 November 2026).
  • @skizzyy2 mentioned this project on 12 November 2026 (20 likes and 0 reposts, captured 15 November 2026).

This page is a guide, not the original text.

What problem it solves

czlonkowski/n8n-mcp is a community MCP server (MIT license) that lets assistants such as Claude, Cursor, and ChatGPT debug, validate, edit, and build n8n workflows. It is not an official n8n product. Recent n8n releases already ship an instance-level MCP server; this project is a separate server that talks to n8n through the Public API, and optionally through n8n’s official MCP token.

The official README comparison is: if you have a current n8n 2.x instance and you manage credentials yourself in the UI, the built-in MCP is often enough. Consider n8n-MCP when you need to cover multiple instances, let the assistant create or update credentials, work with older n8n versions, or use templates, autofix, and security audit tools. You can run both, but you should know which one you are installing.

Who it is for

It is for people who already have an n8n instance and a client that supports MCP. Workflows often hold third-party secrets, and an assistant that can edit nodes can also change those connections. Connect it to a test or staging instance that does not hold production keys first. The author also runs a hosted dashboard at dashboard.n8n-mcp.com. The README states that the free tier includes 100 tool calls per day. Self-hosting is documented with npx or Docker.

How to install it

Verified on 2026-11-15 (Asia/Shanghai). The commands come from the repository README and the Claude Code and Cursor guides. The fastest trial path is the hosted console: connect your n8n instance there, then point your MCP client at the hosted service. For self-hosting, documentation and validation tools work without an n8n API key; workflow management needs N8N_API_URL and N8N_API_KEY.

A full Claude Code setup on Linux, macOS, or WSL looks like this:

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

Replace the URL and key with values for a test instance. A local n8n install commonly uses http://localhost:5678. Do not commit the key. After adding the server, check with claude mcp list or /mcp in the session.

In Cursor, you can put this in the project’s .cursor/mcp.json:

{
  "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"
      }
    }
  }
}

Without N8N_API_URL and N8N_API_KEY, only documentation and validation tools are available. Optional Claude skills live in the separate n8n-skills repository.

A worked example

This is a validation flow that was not run against a live instance, so this page does not invent workflow JSON or a validator report.

  1. Use a test n8n instance and a disposable copy of a workflow. Do not point the server at production.
  2. Finish the MCP setup from the previous section and confirm that the client can see n8n-MCP tools.
  3. Send: List the workflows on this n8n instance and validate the one named TEST-demo. Report unknown nodes or broken connections, but do not update or activate anything.
  4. Official tool docs say that, with API credentials, the assistant should be able to list workflows and validate them. Without the API, only documentation-style tools remain. Check the result in the n8n UI yourself. If you later ask for edits, do them on a copy, and use n8n_workflow_versions to confirm a snapshot exists before you rely on rollback.

Common pitfalls

  • Editing production workflows. The official safety section says to try important flows on a copy or a staging instance first. The server saves snapshots before node or connection edits by default (up to 10 per workflow), but a failed snapshot does not block the edit, so rollback is not guaranteed.
  • Editing in the n8n UI at the same time. The README explains that the server reads the workflow, changes it, and writes the whole document back, because the Public API has no conditional write. Concurrent UI edits can be overwritten.
  • API authentication failures. Issue #262 reported a case where a direct API call worked but the MCP path failed auth. Issue #773 reported intermittent 403 “API key invalid” errors on the hosted dashboard. Check the URL, key permissions, and whether the instance is reachable. Both issues are closed; trust the current error message.
  • Confusing this project with n8n’s built-in MCP. The two have different scope, credential permissions, and version requirements. Do not mix their setup instructions.

FAQ

Is this the official n8n MCP server?

No. This is a community project. n8n also ships an instance-level MCP server. The README has a comparison table. Decide which one you need, or whether to use both, before you install anything.

Can I use it without an n8n API key?

Yes, but only documentation and validation tools will be available. Listing, editing, testing, or otherwise managing workflows requires N8N_API_URL and N8N_API_KEY.

Does the hosted service cost money?

The README says the hosted dashboard has a free tier of 100 tool calls per day. Higher tiers belong on the official site; this page does not invent other prices. Self-hosting follows the project’s own docs.

Will it change my production workflows by default?

It can change an instance only after you provide API credentials and the assistant calls management tools. Even then, official guidance is to try changes on a copy or on staging, and a read-only deployment can disable writes.

What URL should I use for a local n8n instance?

The Claude Code guide says a local instance commonly uses http://localhost:5678. If n8n is on another port or hostname, use the address you can actually reach.

Sources and license

The czlonkowski/n8n-mcp repository is licensed under MIT. This page is a paraphrase, for CQBase — Context & Query Base, of the README and the Claude Code and Cursor setup guides, checked on 2026-11-15. If install commands or the free-tier allowance change, the repository wins.

Subscribe to CQBase Weekly

One email a week with newly catalogued public AI skills, prompts, MCP servers, and methods. Unsubscribe at any time. We will not hand your address to a third party for their marketing.