n8n

与 @automatelab/n8n-mcp 服务端配对使用。该服务端暴露了 9 个 MCP 工具；本技能用于指导你在何时使用哪个工具，以及在何处加载更深层的上下文。

工具路由

工具名称采用点号命名法：node.*、workflow.*、execution.*（在 v0.4.0 版本中由原先的 n8n_* 重命名）。

无状态工具（无需运行中的 n8n 实例即可工作）：

• workflow.generate —— 将自然语言描述转换为 workflow JSON；自动识别 AI Agent 意图，并输出 LangChain 集群结构。
• node.scaffold —— 根据描述生成单个 INodeType TypeScript 文件，适用于构建自定义 n8n 包。
• workflow.lint —— 对 workflow JSON 进行静态检查，返回问题列表（例如：已弃用的节点类型、缺失 typeVersion、连接断裂、AI Agent 缺少 ai_languageModel、IF 节点使用 v1 schema 等）。
• execution.explain —— 输入失败或异常的 execution JSON，输出诊断报告。解决 n8n 最常见的痛点：数据项在节点之间“静默消失”。同时标记未解析的 ={{ ... }} 表达式，并展示 LLM 的 token 使用情况。

有状态工具（需连接运行中的实例）（需配置环境变量 N8N_API_URL 和 N8N_API_KEY）：

• workflow.list —— 分页列出 workflows；支持按激活状态、标签或名称过滤。
• workflow.get —— 根据 ID 获取指定 workflow；可与 workflow.lint 配合使用，用于审计已部署的 workflow。
• workflow.create —— 提交生成的 workflow（HTTP POST）；自动剔除只读字段；新建 workflow 默认处于非激活状态。
• workflow.activate —— 切换 workflow 的激活/非激活状态。
• execution.list —— 浏览 executions；传入 includeData: true 可获取完整执行体内容；建议与 execution.explain 配合使用。

默认调用链：

• 生成并上线：workflow.generate → workflow.lint →（若环境变量已配置）workflow.create → workflow.activate。
• 审计已部署 workflow：workflow.list → workflow.get → workflow.lint。
• 诊断执行失败：execution.list {status: "error"} → 选取一个 execution → execution.list {includeData: true, ...} → execution.explain。

当用户以自然语言描述一个流程时

1. 将用户原始描述直接传入 workflow.generate 执行。
2. 对生成结果运行 workflow.lint。
3. 若无任何 lint 错误 → 直接返回 JSON；若仅存在 warning → 返回 JSON 并附带一行 warning 概要；若存在 error → 通常需内联编辑 JSON 或重新向用户提问以修正问题，再返回结果。

当用户粘贴 execution 数据并提问“为什么 X 是空的？”

1. 将 execution JSON 传入 execution.explain。
2. 阅读诊断报告；若答案已在报告中（例如：“Node Y 返回了 0 个 items，因为 IF 条件分支跳转至其他路径”），则进行简明总结；否则需手动检查对应 workflow 节点的 parameters 块。

加载更深层上下文

本技能保持轻量，以节省你的上下文窗口空间。仅当任务确实需要时，才从 references/ 目录加载相关内容：

• references/expressions.md —— 涵盖 $json、$input.all()、$("Node Name")、自动迭代等表达式语法。适用场景：编写或调试表达式；或用户明确说“使用 $json[0]”（常见误用）。
• references/ai-agents.md —— LangChain 集群拓扑结构、ai_languageModel / ai_memory / ai_tool 连接类型、子节点目录。适用场景：构建 AI Agent；或 lint 报告指出某 AI Agent 缺少 language model。
• references/code-node.md —— Code 节点的返回值格式约定、常见错误原因、sandbox 限制。适用场景：编写 Code 节点；或用户反馈“Code 节点静默失败”。
• references/workflow-json.md —— nodes/connections 结构、必需字段、credential 块定义。适用场景：手写或合并 workflow JSON。
• references/iteration.md —— Split Out、Loop Over Items 与 Aggregate 三者的区别与适用场景。适用场景：用户提出“遍历数组”或“每次处理 N 个 items”等需求。
• references/deprecations.md —— 已弃用的节点类型及其替代方案。适用场景：lint 报告弃用警告；或用户正在迁移旧版 workflow。

服务端配置

将以下配置添加至用户的 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 个无状态工具无需该配置即可运行。API Key 可在 n8n 后台获取：Settings → API → Create API key。

由 AutomateLab 开发。源码地址：github.com/ratamaha-git/n8n-mcp。