Automatelab N8n

n8n-mcp

一个用于 n8n 的 MCP 服务，为 Claude、Cursor 和其他 AI Agent 提供生成工作流、检查代码、诊断执行失败和操作运行中的 n8n 实例的工具。

我们为何打造它

我们每天都在 AutomateLab 内使用 n8n，却总是遇到相同的大模型问题：工作流 JSON 虽然可以导入，却在运行时失败；AI Agent 集群连接类型错误；执行过程悄悄丢弃条目，却无从查找原因。把整个 n8n 目录都塞进上下文也无济于事——这些故障模式太隐蔽了（typeVersion 不匹配、IF v1 架构、导入后失效的凭据）。

因此，我们打造了一个小巧、专注的服务：将检查工具能够捕获的故障模式、生成器必须遵循的集群拓扑，以及 Agent 无法独自完成的诊断封装起来。 如需查看历史发布演示，了解最初的九种工具及其示例输出，请参阅 automatelab.tech 上的发布文章。

与众不同之处

其他 n8n MCP 服务（尤其是 czlonkowski/n8n-mcp）侧重于覆盖范围——提供 20 多种工具和涵盖所有 n8n 节点的索引语料库。它们在这一领域独树一帜。

本服务是面向 n8n 的调试与首次运行正确性 MCP：

• execution_explain 是我们的切入点。粘贴执行 JSON，即可获取逐节点分析结果：哪些节点返回了 0 个条目，哪些节点包含未解析的 ={{ ... }} 表达式，以及附有具体提示的错误消息。其他 MCP 服务都无法很好地做到这一点；它直击 n8n 社区最主要的调试痛点（节点间的数据悄然丢失）。
• workflow_generate 对 AI Agent 拓扑有明确规范——会生成正确的 LangChain 集群，并使用 ai_languageModel / ai_memory / ai_tool 连接（子节点向上连接到 Agent，而不是通过 main 连接）。可在 n8n 1.x 中顺利导入。
• workflow_lint 可捕获那些悄无声息的失败：已弃用的节点类型（Function → Code、spreadsheetFile → convertToFile）、AI Agent 缺少语言模型、IF v1 架构、Webhook 缺少 webhookId，以及所有连接类型（而不仅仅是 main）中的断开连接。
• 5 种 REST 工具（需配置 N8N_API_URL + N8N_API_KEY）可用于列出、获取、创建和激活工作流，以及获取执行记录——这样，检查和解释工具就能针对运行中的工作流执行，而不仅限于聊天中粘贴的 JSON。

此外，还配有一个 Agent Skill，用于指导模型何时使用哪种工具，以及从何处加载更深入的上下文（拆分到 references/ 中，避免提示词过于臃肿）。

工具

工具名称遵循点号表示法，并构成可导航的树：node.*、workflow.*、execution.*。每个工具都声明了 outputSchema（以便调用方对响应进行类型检查）和 MCP annotations（只读 / 破坏性 / 幂等 / 开放世界提示）。

无状态（无需运行中的 n8n 实例）：

工具	用途
workflow_generate	纯英文描述 → 工作流 JSON。可识别 AI Agent 意图。
node_scaffold	描述 → 用于自定义 n8n 包的单个 INodeType TypeScript 文件。
workflow_lint	工作流 JSON → 错误和警告列表（20 多条规则）。
workflow_diff	两个工作流 → 语义差异（新增 / 移除 / 修改的节点、连接、设置）。
execution_explain	失败的执行 JSON → 按节点提供诊断和提示。
execution_replay	工作流 + 节点 → 自包含的重放工作流，仅测试该节点。
execution_timeline	执行 JSON → 按节点排列的时间线表格（开始时间、持续时间、输入 / 输出项、错误）。

实时实例（需要 N8N_API_URL + N8N_API_KEY 环境变量）：

工具	用途
workflow_list	对工作流进行分页；可按 active / 标签 / 名称筛选。
workflow_get	按 id 获取工作流。
workflow_create	POST 一个工作流。会剔除只读字段。
workflow_activate	切换 active 状态。
execution_list	浏览执行记录；设置 includeData: true 可获取完整内容。

v0.5.0 变更。 新增三个工具：workflow_diff、execution_replay、execution_timeline。Lint 新增 10 条规则（速率限制、凭据漂移、表达式过时、代码沙箱、webhook 测试路径、active 工作流中的 manualTrigger、DST 排程风险、已禁用但仍连接、空 Set、HTTP 方法 / 请求体不匹配）。新增运行时策略环境变量：N8N_MCP_READ_ONLY、N8N_MCP_DISABLED_TOOLS、N8N_MCP_ALLOWED_WORKFLOW_IDS、N8N_MCP_ALLOWED_TAGS。新增 DXT 打包文件 + Dockerfile + Render/Railway/Fly 部署配置。

v0.4.0 破坏性变更。 工具已从 n8n_*（snake_case）重命名为点号表示法。请更新所有引用旧名称的提示词、Agent 技能或脚本。

运行时策略（v0.5+）

无需分叉即可限制服务。启动前设置以下环境变量：

环境变量	效果
N8N_MCP_READ_ONLY=1	禁用 workflow_create、workflow_activate、node_scaffold。
N8N_MCP_DISABLED_TOOLS=workflow_create,workflow_activate	完全跳过这些工具的注册。
N8N_MCP_ALLOWED_WORKFLOW_IDS=abc,def	REST 工具拒绝操作列表以外的任何工作流。
N8N_MCP_ALLOWED_TAGS=prod,staging	workflow_list 仅筛选至少带有一个标签的工作流。

将 MCP 交给初级 Agent 使用，或将其接入面向客户的助手时，此功能很有用。

部署

• Claude Desktop 一键部署：从 dxt/manifest.json 构建 .dxt 包（参见 dxt/README.md）。
• Docker：docker build -t n8n-mcp . && docker run --rm -i -e N8N_API_URL=... -e N8N_API_KEY=... n8n-mcp。
• Render：放入 render.yaml，然后点击“New from Blueprint”。
• Railway：railway.toml — 在仓库根目录运行 railway up。
• Fly.io：fly.toml — 运行 fly launch --copy-config。

安装

需要 Node 20 或更高版本。

作为 CLI 工具

npm install -g @automatelab/n8n-mcp

作为 GitHub Action

使用 n8n MCP GitHub Action，在 CI/CD 工作流中检查工作流、诊断执行记录并生成工作流 JSON：

- uses: ratamaha-git/n8n-mcp@v1
  with:
    command: 'lint'
    workflow-json: ${{ env.WORKFLOW_JSON }}

示例和发布详情请参阅 ACTION.md 和 GITHUB-ACTION-SETUP.md。

配置 MCP 宿主

Cursor（~/.cursor/mcp.json）或 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@automatelab/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://your-n8n.example.com",
        "N8N_API_KEY": "n8n_..."
      }
    }
  }
}

env 块为可选项——4 个无状态工具无需此配置即可运行。前往 n8n 获取 API 密钥：Settings → API → Create API key。

重启 MCP 宿主。MCP 面板中会显示 12 个点号表示法工具（workflow.*、node.*、execution.*）。

工具示例

workflow_generate

使用 workflow_generate 构建：Stripe webhook → Slack 消息 + 在 Google Sheets 中新增一行。

返回可供 n8n「Import from File」对话框导入的工作流 JSON。

execution_explain

这是 n8n 中一次失败的执行。为什么 Slack 节点没有触发？ [粘贴 JSON]

返回：

WARNING [Filter] Returned 0 items. Downstream nodes will not execute.
  hint: Common causes: (1) IF/Switch routed to the other branch — check `parameters.conditions`. (2) Filter/Set node dropped everything — inspect its output explicitly.

INFO [Last node executed was "Filter". If the workflow stopped here unexpectedly, check its output items below.]

workflow_lint

检查此工作流 JSON。 [粘贴 JSON]

返回：

ERROR [AI Agent] AI Agent has no `ai_languageModel` sub-node connected. Attach a chat model (e.g. lmChatOpenAi).
WARNING [Webhook] Webhook node has no `webhookId`. n8n auto-generates one on import, so the production URL will change.
WARNING [LegacyFunction] Node type "n8n-nodes-base.function" is deprecated. Use "n8n-nodes-base.code".

或 no issues found。

示例

examples/ 目录中提供了两个可直接导入的工作流：

• workflow-stripe-to-slack.json - Stripe webhook 将事件分发到 Slack 和 Google Sheets。
• workflow-rss-to-discord.json - RSS 源触发器将新条目发布到 Discord 频道。

通过 n8n 的 Import from File 对话框导入任一工作流。

开发

git clone https://github.com/ratamaha-git/n8n-mcp
cd n8n-mcp
npm install
npm run build
npm run smoke

npm run smoke 使用 --smoke 标志启动服务，列出已注册的工具后退出，不会绑定 stdio。适用于 CI 或首次运行时的基本检查。

许可证

MIT。请参阅 LICENSE。

---

由 AutomateLab 开发。

维护与验证

请参阅维护指南，了解解释限制、当前工具名称（如适用）以及可复现的验证方法。