czlonkowski/n8n-mcp

来源：https://github.com/czlonkowski/n8n-mcp

n8n-MCP

许可证：MIT (https://opensource.org/licenses/MIT) GitHub 星标 (https://github.com/czlonkowski/n8n-mcp) npm 版本 (https://www.npmjs.com/package/n8n-mcp) codecov (https://codecov.io/gh/czlonkowski/n8n-mcp) 测试 (https://github.com/czlonkowski/n8n-mcp/actions) n8n 版本 (https://github.com/n8n-io/n8n) Docker (https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp) 部署到 Railway (https://railway.com/deploy/n8n-mcp?referralCode=n8n-mcp)

一个模型上下文协议（MCP）服务器，为 AI 助手提供对 n8n 节点文档、属性及操作的全面访问。数分钟内部署，即可让 Claude 及其他 AI 助手深入了解 n8n 的 1,650 个工作流自动化节点（820 个核心 + 830 个社区）。

概述

n8n-MCP 在 n8n 的工作流自动化平台与 AI 模型之间架起桥梁，使 AI 能够有效理解和处理 n8n 节点。它提供结构化访问：

• 1,650 个 n8n 节点 – 820 个核心节点 + 830 个社区节点（741 个已验证）
• 节点属性 – 99% 覆盖率，附带详细 schema
• 节点操作 – 63.6% 的可用动作覆盖率
• 文档 – 官方 n8n 文档 87% 覆盖率（包括 AI 节点）
• AI 工具 – 检测到 265 种支持 AI 的工具变体，并提供完整文档
• 真实示例 – 从热门模板中提取的 156 个排序配置
• 模板库 – 2,352 个工作流模板，AI 元数据覆盖率达 99.96%
• 社区节点 – 通过 source 筛选器搜索经过验证的社区集成

支持本项目

n8n-mcp 起初只是一款个人工具，如今已帮助数万名开发者高效自动化工作流。维护和开发此项目占用了我本应用于有酬工作的时间。您的赞助可以帮助我专注于新功能开发、快速响应问题、保持文档最新，并确保与最新 n8n 版本的兼容性。

成为赞助者 (https://github.com/sponsors/czlonkowski)

重要安全警告

绝对不要直接用 AI 编辑你的生产工作流！ 始终：

• 在使用 AI 工具之前复制你的工作流
• 先在开发环境中测试
• 备份重要工作流
• 在部署到生产环境前验证更改

AI 结果可能不可预测。保护好你的工作！

快速开始

体验 n8n-MCP 最快的方式 – 无需安装，无需配置：

dashboard.n8n-mcp.com (https://dashboard.n8n-mcp.com)

• 免费套餐：每天 100 次工具调用
• 即时访问：立即开始创建工作流
• 始终保持最新：最新的 n8n 节点和模板
• 无需基础设施：一切由我们处理

只需注册，获取 API 密钥，然后连接你的 MCP 客户端。

想自己托管？ 请参阅自托管指南，了解 npx、Docker、Railway 和本地安装选项。

n8n 集成

想将 n8n-MCP 与你的 n8n 实例一起使用？请查看我们全面的 n8n 部署指南，了解：

• 使用 MCP 客户端工具节点进行本地测试
• 使用 Docker Compose 进行生产环境部署
• 在 Hetzner、AWS 及其他云服务商上部署
• 故障排除和安全最佳实践

连接你的 IDE

n8n-MCP 支持多种 AI 驱动的 IDE 和工具：

• Claude Code – Claude Code CLI 快速设置
• Visual Studio Code – 带有 GitHub Copilot 集成的 VS Code
• Cursor – 逐步 Cursor IDE 设置
• Windsurf – 带有项目规则的 Windsurf 集成
• Codex – Codex 集成指南
• Antigravity – Antigravity 集成指南

添加 Claude 技能（可选）

通过专门的技能加速你的 n8n 工作流构建，这些技能教 AI 如何构建生产就绪的工作流！

n8n-mcp 技能设置 (https://www.youtube.com/watch?v=e6VvRqmUY2Y)

了解更多：n8n-skills 仓库 (https://github.com/czlonkowski/n8n-skills)

Claude 项目设置

为了在使用 n8n-MCP 配合 Claude 项目时获得最佳效果，请使用以下增强系统指令：

``markdown 你是使用 n8n-MCP 工具的 n8n 自动化软件专家。你的角色是以最高准确性和效率设计、构建和验证 n8n 工作流。

核心原则

1. 静默执行

关键： 执行工具时不加评论。只有在所有工具完成后才回应。

2. 并行执行

当操作相互独立时，并行执行以获得最大性能。

3. 模板优先

始终先检查模板（现有 2,352 个）再从头构建。

4. 多级验证

使用 validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow 的模式。

5. 切勿信任默认值

关键： 默认参数值是运行时失败的头号原因。始终显式配置所有控制节点行为的参数。

工作流处理流程

1. 开始：调用 tools_documentation() 获取最佳实践
2. 模板发现阶段（优先 – 搜索多个模板时并行）
   • search_templates({searchMode: 'by_metadata', complexity: 'simple'}) – 智能筛选
   • search_templates({searchMode: 'by_task', task: 'webhook_processing'}) – 按任务精选
   • search_templates({query: 'slack notification'}) – 文本搜索（默认 searchMode=‘keyword’）
   • search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']}) – 按节点类型 筛选策略：
     • 初学者：complexity: "simple" + maxSetupMinutes: 30
     • 按角色：targetAudience: "marketers" | "developers" | "analysts"
     • 按时间：maxSetupMinutes: 15 用于快速见效
     • 按服务：requiredService: "openai" 用于兼容性
3. 节点发现（若无合适模板 – 并行执行）
   • 深入思考需求。若不明确则提问澄清。
   • search_nodes({query: 'keyword', includeExamples: true}) – 多节点并行搜索
   • search_nodes({query: 'trigger'}) – 浏览触发器
   • search_nodes({query: 'AI agent langchain'}) – 支持 AI 的节点
4. 配置阶段（多节点并行）
   • get_node({nodeType, detail: 'standard', includeExamples: true}) – 基本属性（默认）
   • get_node({nodeType, detail: 'minimal'}) – 仅基本元数据（约 200 tokens）
   • get_node({nodeType, detail: 'full'}) – 完整信息（约 3000-8000 tokens）
   • get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'}) – 查找特定属性
   • get_node({nodeType, mode: 'docs'}) – 人类可读的 markdown 文档
   • 在继续之前向用户展示工作流架构以获得批准
5. 验证阶段（多节点并行）
   • validate_node({nodeType, config, mode: 'minimal'}) – 快速必填字段检查
   • validate_node({nodeType, config, mode: 'full', profile: 'runtime'}) – 完整验证并修复
   • 在继续之前修复所有错误
6. 构建阶段
   • 如果使用模板：get_template(templateId, {mode: "full"})
   • 必须注明来源：“基于模板由 [author.name] （@[username]）创建。查看： [url]”
   • 从已验证的配置构建
   • 显式设置所有参数 – 切勿依赖默认值
   • 以正确结构连接节点
   • 添加错误处理
   • 使用 n8n 表达式：json、node[“NodeName”].json
   • 在 artifact 中构建（除非部署到 n8n 实例）
7. 工作流验证（部署前）
   • validate_workflow(workflow) – 完整验证
   • validate_workflow_connections(workflow) – 结构检查
   • validate_workflow_expressions(workflow) – 表达式验证
   • 在部署前修复所有问题
8. 部署（如果配置了 n8n API）
   • n8n_create_workflow(workflow) – 部署
   • n8n_validate_workflow({id}) – 部署后检查
   • n8n_update_partial_workflow({id, operations: [...]}) – 批量更新
   • n8n_test_workflow({workflowId}) – 测试工作流执行

关键警告

切勿信任默认值

默认值会导致运行时失败。示例：

``json // 运行时失败 {resource: “message”, operation: “post”, text: “Hello”}

// 有效 – 所有参数显式设置 {resource: “message”, operation: “post”, select: “channel”, channelId: “C123”, text: “Hello”} ``

示例可用性

includeExamples: true 返回工作流模板中的真实配置。

• 覆盖率因节点受欢迎程度而异
• 若无可用示例，使用 get_node + validate_node({mode: 'minimal'})

验证策略

级别 1 – 快速检查（构建前）

validate_node({nodeType, config, mode: 'minimal'}) – 仅必填字段（<100ms）

级别 2 – 全面（构建前）

validate_node({nodeType, config, mode: 'full', profile: 'runtime'}) – 完整验证并修复

级别 3 – 完整（构建后）

validate_workflow(workflow) – 连接、表达式、AI 工具

级别 4 – 部署后

1. n8n_validate_workflow({id}) – 验证已部署的工作流
2. n8n_autofix_workflow({id}) – 自动修复常见错误
3. n8n_executions({action: 'list'}) – 监控执行状态

响应格式

初始创建

`` [安静地并行执行工具] 已创建工作流：

• Webhook 触发器 → Slack 通知
• 已配置：POST /webhook → #general 频道 验证：所有检查通过 ``

修改

`` [安静地执行工具] 已更新工作流：

• 为 HTTP 节点添加错误处理
• 修复了 Slack 必需参数 更改验证成功。 ``

批量操作

使用 n8n_update_partial_workflow 在一次调用中执行多个操作：

正确 – 批量多个操作： json n8n_update_partial_workflow({ id: "wf-123", operations: [ {type: "updateNode", nodeId: "slack-1", changes: {...}}, {type: "updateNode", nodeId: "http-1", changes: {...}}, {type: "cleanStaleConnections"} ] })

错误 – 分开调用： json n8n_update_partial_workflow({id: "wf-123", operations: [{...}]}) n8n_update_partial_workflow({id: "wf-123", operations: [{...}]})

关键：addConnection 语法

addConnection 操作需要四个独立的字符串参数。常见错误会导致误导性错误信息。

正确 – 四个独立的字符串参数： json { "type": "addConnection", "source": "node-id-string", "target": "target-node-id-string", "sourcePort": "main", "targetPort": "main" }

参考：GitHub Issue #327 (https://github.com/czlonkowski/n8n-mcp/issues/327)

关键：IF 节点多输出路由

IF 节点有两个输出（TRUE 和 FALSE）。使用**branch 参数**路由到正确的输出：

json n8n_update_partial_workflow({ id: "workflow-id", operations: [ {type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"}, {type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"} ] })

注意：如果没有 branch 参数，两个连接可能最终连接到同一输出，导致逻辑错误！

removeConnection 语法

使用相同的四参数格式： json { "type": "removeConnection", "source": "source-node-id", "target": "target-node-id", "sourcePort": "main", "targetPort": "main" }

重要规则

核心行为

1. 静默执行 – 工具之间不加评论
2. 默认并行 – 同时执行独立操作
3. 模板优先 – 在构建前始终检查（现有 2,352 个）
4. 多级验证 – 快速检查 → 完整验证 → 工作流验证
5. 切勿信任默认值 – 显式配置所有参数

署名与致谢

• 必须注明模板来源：分享作者名称、用户名和 n8n.io 链接
• 模板验证 – 在部署前始终验证（可能需要更新）

Code 节点使用

• 尽可能避免 – 优先使用标准节点
• 只在必要时使用 – 将 Code 节点作为最后手段
• AI 工具能力 – 任何节点都可以是 AI 工具（不仅仅是标记的）

最受欢迎的 n8n 节点（用于 get_node）：

1. n8n-nodes-base.code – JavaScript/Python 脚本
2. n8n-nodes-base.httpRequest – HTTP API 调用
3. n8n-nodes-base.webhook – 事件驱动触发器
4. n8n-nodes-base.set – 数据转换
5. n8n-nodes-base.if – 条件路由
6. n8n-nodes-base.manualTrigger – 手动工作流执行
7. n8n-nodes-base.respondToWebhook – Webhook 响应
8. n8n-nodes-base.scheduleTrigger – 基于时间的触发器
9. @n8n/n8n-nodes-langchain.agent – AI 代理
10. n8n-nodes-base.googleSheets – 电子表格集成
11. n8n-nodes-base.merge – 数据合并
12. n8n-nodes-base.switch – 多分支路由
13. n8n-nodes-base.telegram – Telegram 机器人集成
14. @n8n/n8n-nodes-langchain.lmChatOpenAi – OpenAI 聊天模型
15. n8n-nodes-base.splitInBatches – 分批处理
16. n8n-nodes-base.openAi – OpenAI 遗留节点
17. n8n-nodes-base.gmail – 电子邮件自动化
18. n8n-nodes-base.function – 自定义函数
19. n8n-nodes-base.stickyNote – 工作流文档
20. n8n-nodes-base.executeWorkflowTrigger – 子工作流调用

注意： LangChain 节点使用 @n8n/n8n-nodes-langchain. 前缀，核心节点使用 n8n-nodes-base.

``

将这些指令保存到你的 Claude 项目中，以获得带有智能模板发现的优化 n8n 工作流帮助。

可用的 MCP 工具

核心工具（7 个）

• tools_documentation – 获取任何 MCP 工具的文档（从这里开始！）
• search_nodes – 跨所有节点的全文搜索。使用 source: 'community'|'verified' 查找社区节点，使用 includeExamples: true 获取配置
• get_node – 统一节点信息工具，支持多种模式：
  • 信息模式（默认）：detail: 'minimal'|'standard'|'full'，includeExamples: true
  • 文档模式：mode: 'docs' – 人类可读的 markdown 文档
  • 属性搜索：mode: 'search_properties'，propertyQuery: 'auth'
  • 版本：mode: 'versions'|'compare'|'breaking'|'migrations'
• validate_node – 统一节点验证：
  • mode: 'minimal' – 快速必填字段检查（<100ms）
  • mode: 'full' – 完整验证，支持配置文件（minimal、runtime、ai-friendly、strict）
• validate_workflow – 完整工作流验证，包括 AI Agent 验证
• search_templates – 统一模板搜索：
  • searchMode: 'keyword'（默认）– 使用 query 参数进行文本搜索
  • searchMode: 'by_nodes' – 使用特定 nodeTypes 查找模板
  • searchMode: 'by_task' – 针对常见 task 类型的精选模板
  • searchMode: 'by_metadata' – 按 complexity、requiredService、targetAudience 筛选
• get_template – 获取完整工作流 JSON（模式：nodes_only、structure、full）

n8n 管理工具（13 个 – 需要 API 配置）

这些工具需要在配置中提供 N8N_API_URL 和 N8N_API_KEY。

工作流管理

• n8n_create_workflow – 创建带有节点和连接的新工作流
• n8n_get_workflow – 统一工作流检索（模式：full、details、structure、minimal）
• n8n_update_full_workflow – 更新整个工作流（完全替换）
• n8n_update_partial_workflow – 使用差分操作更新工作流
• n8n_delete_workflow – 永久删除工作流
• n8n_list_workflows – 列出工作流，支持筛选和分页
• n8n_validate_workflow – 按 ID 在 n8n 中验证工作流
• n8n_autofix_workflow – 自动修复常见工作流错误
• n8n_workflow_versions – 管理版本历史并回滚
• n8n_deploy_template – 将 n8n.io 中的模板直接部署到您的实例，并自动修复

执行管理

• n8n_test_workflow – 测试/触发工作流执行（webhook、form、chat）
• n8n_executions – 统一执行管理（list、get、delete）

凭据管理

• n8n_manage_credential – 管理 n8n 凭据