# n8n MCP

Canonical: https://cqbase.net/zh/entry/n8n-mcp
Chinese: https://cqbase.net/zh/entry/n8n-mcp
English: https://cqbase.net/en/entry/n8n-mcp

> 让 Claude、ChatGPT、Cursor 等助手通过 MCP 调试、编辑和构建 n8n 工作流。

czlonkowski/n8n-mcp 是 MIT 许可的 MCP 服务器，用来让支持 MCP 的助手操作 n8n：调试、编辑、校验、测试和构建工作流。它把自动化画布交给代理，而不只是让模型口头描述节点。

先连到一个没有生产密钥的测试 n8n 实例。工作流里往往带有第三方令牌，代理一旦能改节点，就等于可能改这些连接。范围要写小，变更要人看过再启用。

推荐来源：

- [@HermesWatcher](https://x.com/HermesWatcher/status/2115081092118032871) 在 2026 年 10 月 27 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：1149 次喜欢，126 次转发）。
- [@skizzyy2](https://x.com/skizzyy2/status/2120856666451083515) 在 2026 年 11 月 12 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：20 次喜欢，0 次转发）。

## 解决什么问题

[czlonkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp) 是社区维护的 MCP 服务器（MIT 许可），用来让 Claude、Cursor、ChatGPT 等助手调试、校验、编辑和构建 n8n 工作流。它不是 n8n 官方产品。n8n 较新的版本已经内置实例级 MCP；本项目是另起的服务器，通过 n8n 的 Public API（以及可选的官方 MCP 令牌）工作。

官方 README 的对照是：只需一台较新的 n8n 2.x、并且自己在界面里管凭证时，用内置 MCP 往往就够了。在要同时管多台实例、让助手创建或更新凭证、使用旧版 n8n，或需要模板、自动修复和安全审计时，再考虑 n8n-MCP。两者可以一起用，但先要分清你装的是哪一套。

## 适合谁

适合已经有 n8n 实例、并在用支持 MCP 的客户端的人。工作流里常有第三方密钥，助手一旦能改节点，就可能改到这些连接。请先连到没有生产密钥的测试或预发实例。项目作者还提供托管服务 [dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com)，README 写明免费档为每天 100 次工具调用；自托管则按文档用 npx 或 Docker。

## 怎么装

核验日期为 2026-11-15（Asia/Shanghai），命令来自仓库 README 以及 [Claude Code](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/CLAUDE_CODE_SETUP.md) 和 [Cursor](https://github.com/czlonkowski/n8n-mcp/blob/main/docs/CURSOR_SETUP.md) 指南。最快试用方式是走托管控制台，把 n8n 实例连上去，再把 MCP 客户端连到托管服务。自托管时，若只使用文档和校验工具，可不提供 n8n API；要管理工作流，需要 `N8N_API_URL` 和 `N8N_API_KEY`。

在 Claude Code（Linux、macOS 或 WSL）里添加完整配置的示例：

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

请换成你的测试实例地址和密钥。本地 n8n 常用 `http://localhost:5678`。不要把密钥提交进 Git。添加后用 `claude mcp list` 或会话里的 `/mcp` 检查。

在 Cursor 中，可在项目的 `.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"
      }
    }
  }
}
```

不含 `N8N_API_URL` / `N8N_API_KEY` 时，只有文档和校验类工具。可选的 Claude 技能在 [n8n-skills](https://github.com/czlonkowski/n8n-skills)，与本服务器不是同一仓库。

## 一个实际例子

下面是一个未在本机实跑的校验流程，因此不编造工作流 JSON 或校验报告。

1. 准备一台测试用 n8n，创建一个可丢弃的工作流副本，不要直接连生产。
2. 按上一节完成 MCP 配置，确认客户端能看到 n8n-MCP 工具。
3. 发送：`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. 按官方工具说明，带 API 配置时，助手应能列出工作流并做校验；没有 API 时只能用文档类工具。请你自己在 n8n 界面核对结果。需要修改时，先在副本上做，并用 `n8n_workflow_versions` 确认已有快照再依赖回滚。

## 常见坑

- 直接改生产工作流。官方安全节要求：重要流程先在副本或预发上试。默认会在改节点或连线前保存快照（每个工作流最多 10 份），但快照失败不会阻止编辑，不能想当然以为一定能回滚。
- 与 n8n 界面同时编辑。README 写明它会读出工作流、改完再整份写回，因为 Public API 没有条件写入；你在界面里同时改的内容可能被覆盖。
- API 认证失败。[issue #262](https://github.com/czlonkowski/n8n-mcp/issues/262) 报告过直接调用 API 成功、经 MCP 却认证失败；[issue #773](https://github.com/czlonkowski/n8n-mcp/issues/773) 报告过托管控制台间歇出现 403「API key invalid」。先检查 URL、密钥权限和实例是否可访问。这些 issue 已关闭，请以当前报错为准。
- 把它当成 n8n 内置 MCP。两者能力范围、凭证权限和版本要求不同，不要混用安装说明。

## FAQ

### 这是 n8n 官方 MCP 吗？

不是。这是社区项目。n8n 自己也有实例级 MCP。README 有对照表，先分清再决定用哪一个，或是否两者一起用。

### 没有 n8n API key 能用吗？

可以，但只有文档和校验类工具。要列出、修改、测试或管理工作流，需要 `N8N_API_URL` 和 `N8N_API_KEY`。

### 托管服务收费吗？

README 写明托管控制台有免费档，每天 100 次工具调用。更高档以官网为准，本文不编造其他价格。自托管则按文档自行部署。

### 默认会改我的生产流程吗？

只有在你提供了 API 并让助手调用管理类工具时，它才能改实例。即便如此，官方仍要求先在副本或预发上试验，并可用只读部署关掉写操作。

### 本地 n8n 的地址填什么？

Claude Code 指南写明，本地实例常用 `http://localhost:5678`。若 n8n 在别的端口或域名上，填实际可达的地址。

## 来源与许可

仓库 [czlonkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp) 使用 MIT 许可。本文依据 2026-11-15 查阅的 README 以及 Claude Code、Cursor 安装指南，用自己的话写成，供 CQBase 上下文库使用。若安装命令或免费额度有变，以仓库为准。

## 收录信息

- 作者: czlonkowski
- 许可证: MIT
- 来源: https://github.com/czlonkowski/n8n-mcp
- 收录: 2026-11-15
- GitHub 星标: 23255（采集 2026-11-15）

