n8n Workflow Builder MCP

n8n 工作流构建器 MCP

用于构建和操作 n8n 工作流的模型上下文协议（MCP）服务。只需通过 AI 提示词即可构建 n8n 工作流——兼容 Claude Code、VS Code、Cursor 和任何兼容 MCP 的客户端。

这个 MCP 服务适合你吗？

此服务会在本地写入 n8n 工作流 JSON 文件。它不需要正在运行的 n8n 实例，并会从内置目录中选择节点版本，该目录涵盖 n8n 1.86.0 – 2.6.2。

适合在以下情况下使用此服务：

• 想要离线生成工作流文件，然后自行导入（或提交到 git）
• 使用较旧的可自托管 n8n，并且需要工作流中的节点 typeVersion 是你的实例实际支持的版本。将 N8N_VERSION 设为与你的实例版本一致。

以下情况请考虑其他方案：

• 想让 AI 直接在你的 n8n 实例中构建、测试和运行工作流。请使用 n8n 内置的实例级 MCP 服务。
• 想要大型节点文档和模板库，并通过 n8n API 部署。请使用 czlonkowski/n8n-mcp。
• 需要 n8n 2.6.2 之后添加的节点。它们尚未包含在内置目录中。

演示视频：

Cursor 规则

• 规则文件位于 rules/n8n-mcp-server-rules.mdc

主要功能

• 工作流管理：以编程方式创建、更新和执行 n8n 工作流（尚未实现执行功能）
• 节点发现：探索可用的 n8n 节点及其功能
• 连接管理：在工作流节点之间创建连接
• AI 集成：用于在工作流中连接 AI 组件的专用工具
• AI 友好界面：专为与 AI Agent 交互而设计
• N8N 版本管理：自动检测版本并处理兼容性——支持 184+ 个 n8n 版本（1.86.0 – 2.6.2），具备动态节点筛选功能，并通过“最接近的较低版本”匹配确保向后兼容

前置条件

• Node.js（v18 或更高版本）
• npm（用于运行 npx 命令）
• 兼容 MCP 的客户端（Claude Code、VS Code、Cursor 等）

安装与设置

获取 n8n API 密钥

API 密钥是可选的。此服务仅使用 N8N_API_URL/N8N_API_KEY 检测你的 n8n 版本。若要完全离线运行，请跳过这两个变量，改为设置 N8N_VERSION（例如 N8N_VERSION=1.123.2）。

1. 在浏览器中打开你的 n8n 实例
2. 前往 设置 > API 密钥
3. 点击 创建 API 密钥
4. 复制生成的密钥并在配置中使用

Claude Code（推荐）

使用 Claude Code CLI 添加 MCP 服务：

claude mcp add n8n-workflow-builder -- npx -y n8n-workflow-builder-mcp

然后设置环境变量：

claude mcp add n8n-workflow-builder \
  -e N8N_API_URL=http://localhost:5678 \
  -e N8N_API_KEY=your-n8n-api-key-here \
  -- npx -y n8n-workflow-builder-mcp

N8N_VERSION 是可选的——服务会通过 API 自动检测版本。

VS Code / Cursor

添加到你的 MCP 配置文件（VS Code 使用 .vscode/mcp.json，Cursor 使用 .cursor/mcp.json）：

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["-y", "n8n-workflow-builder-mcp"],
      "env": {
        "N8N_API_URL": "http://localhost:5678",
        "N8N_API_KEY": "your-n8n-api-key-here"
      }
    }
  }
}

重启 IDE 使更改生效。

开发环境安装

如需开发或本地测试，请克隆并从源代码构建：

git clone https://github.com/ifmelate/n8n-workflow-builder-mcp.git
cd n8n-workflow-builder-mcp
npm install
npm run build

然后将 MCP 客户端指向构建好的入口文件：

# Claude Code
claude mcp add n8n-workflow-builder -- node /absolute/path/to/n8n-workflow-builder-mcp/dist/index.js

# VS Code / Cursor — use the same JSON config above with "command": "node" and "args": ["/absolute/path/to/dist/index.js"]

如需在开发时自动重新构建：

npm run dev

可用的 MCP 工具

此服务提供以下工具，用于处理 n8n 工作流：

核心工作流管理

工具名称	描述	关键参数
create_workflow	创建新的 n8n 工作流	workflow_name、workspace_dir
list_workflows	列出工作区中的工作流	limit（可选）、cursor（可选）
get_workflow_details	获取特定工作流的详细信息	workflow_name、workflow_path（可选）
validate_workflow	根据节点架构和连接关系验证工作流文件	workflow_name、workflow_path（可选）

节点管理

工具名称	描述	关键参数
add_node	向工作流添加新节点	workflow_name、node_type、position（可选）、parameters（可选）、node_name（可选）、typeVersion（可选）、webhookId（可选）、workflow_path（可选）、connect_from（可选）、connect_to（可选）
edit_node	编辑工作流中的现有节点	workflow_name、node_id、node_type（可选）、node_name（可选）、position（可选）、parameters（可选）、typeVersion（可选）、webhookId（可选）、workflow_path（可选）、connect_from（可选）、connect_to（可选）
delete_node	从工作流中删除节点	workflow_name、node_id、workflow_path（可选）
list_available_nodes	列出可用的节点类型，并支持筛选。支持标签式同义词以及多词元 OR/AND 逻辑	search_term（可选）、n8n_version（可选）、limit（可选）、cursor（可选）、tags（可选，默认值：true）、token_logic（可选：默认值为 'or'，或 'and'）

连接管理

工具名称	描述	关键参数
add_connection	在两个节点之间创建连接	workflow_name、source_node_id、source_node_output_name、target_node_id、target_node_input_name、target_node_input_index（可选）、workflow_path（可选）
add_ai_connections	将 AI 模型、工具和记忆连接到 Agent	workflow_name、agent_node_id、model_node_id（可选）、tool_node_ids（可选）、memory_node_id（可选）、embeddings_node_id（可选）、vector_store_node_id（可选）、vector_insert_node_id（可选）、vector_tool_node_id（可选）、workflow_path（可选）
connect_main_chain	构建一条贯穿 AI 工作流节点的最小主路径（触发器 → 模型 → 记忆 → 嵌入 → 文档加载器 → 向量存储 → 向量工具 → Agent）	workflow_name、workflow_path（可选）、dry_run（可选）、idempotency_key（可选）

工作流规划与组合

工具名称	描述	关键参数
plan_workflow	创建用于更新工作流的非破坏性计划（节点和连接）。不会写入文件	workflow_name、target（节点、连接）、workspace_dir（可选）
review_workflow_plan	在内存中应用计划，并返回验证错误、警告和建议的修复方案。不会写入文件	workflow_name、plan、workflow_path（可选）
apply_workflow_plan	将先前审核过的计划应用到磁盘上的工作流（原子写入）	workflow_name、plan、workflow_path（可选）
compose_ai_workflow	一次调用即可组合复杂的 AI 工作流（Agent + 模型 + 记忆 + 嵌入 + 向量 + 工具 + 触发器），包括连接配置和基本验证	workflow_name、plan、n8n_version（可选）

参数管理

工具名称	描述	关键参数
suggest_node_params	使用默认值和必填字段，为节点类型建议最少的有效参数	node_type、typeVersion（可选）、existing_parameters（可选）
list_missing_parameters	根据可见性规则，列出节点缺少的必填参数	node_type、typeVersion（可选）、parameters
fix_node_params	为缺少的必填字段应用默认值，并返回参数	node_type、typeVersion（可选）、parameters（可选）

模板与发现

工具名称	描述	关键参数
list_template_examples	列出从免费模板中提取的节点用法示例。可按 node_type 或 template_name 筛选	node_type（可选）、template_name（可选）、limit（可选）、cursor（可选）
get_n8n_version_info	获取当前 N8N 版本和功能	random_string

验证行为

validate_workflow 会将警告提升为错误；此外，如果任何已启用节点未连接到从推断出的 startNode 开始的主链（直接连接或通过 AI 端口连接），验证也会失败。使用 connect_from/connect_to 或 add_ai_connections 修复连接。

故障排除

常规

1. 检查 MCP 配置 — 确保 JSON 有效，且服务名称匹配。
2. 将 Node.js 更新到最新的 LTS 版本。
3. 如果 npx 失败，清除 npm 缓存：npm cache clean --force
4. 尝试全局安装作为备用方案：npm install -g n8n-workflow-builder-mcp

Claude Code

• 运行 claude mcp list，确认服务已注册。
• 使用 claude mcp logs n8n-workflow-builder 查看日志。

VS Code / Cursor

• 检查“输出”面板 — 从下拉菜单中选择“MCP”以查看服务日志。
• 确保已在“设置”>“功能”>“MCP 服务”中启用该服务。
• 更改配置后重启 IDE。

项目结构

• /src：主要源代码
• /src/tools：MCP 工具实现
• /src/models：数据模型
• /src/utils：实用函数
• /src/middleware：身份验证和中间件
• /config：配置文件
• /tests：测试文件
• /workflow_nodes：n8n 节点定义
• /docs：补充文档

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

MIT 许可证