# n8n MCP

Canonical: https://cqbase.net/en/entry/n8n-mcp
Chinese: https://cqbase.net/zh/entry/n8n-mcp
English: https://cqbase.net/en/entry/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](https://x.com/HermesWatcher/status/2115081092118032871) mentioned this project on 27 October 2026 (1149 likes and 126 reposts, captured 15 November 2026).
- [@skizzyy2](https://x.com/skizzyy2/status/2120856666451083515) mentioned this project on 12 November 2026 (20 likes and 0 reposts, captured 15 November 2026).

## What problem it solves

[czlonkowski/n8n-mcp](https://github.com/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](https://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](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/CLAUDE_CODE_SETUP.md) and [Cursor](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/CURSOR_SETUP.md) 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:

```bash
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`:

```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](https://github.com/czlonkowski/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](https://github.com/czlonkowski/n8n-mcp/issues/262) reported a case where a direct API call worked but the MCP path failed auth. [Issue #773](https://github.com/czlonkowski/n8n-mcp/issues/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](https://github.com/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.

## Catalog record

- Author: czlonkowski
- License: MIT
- Source: https://github.com/czlonkowski/n8n-mcp
- Added: 2026-11-15
- GitHub stars: 23255 (captured 2026-11-15)

