n8n-mcp

MCP 服务器，为 Claude、Cursor 等 AI 助手提供 n8n 节点文档和操作能力，让 AI 能直接帮你构建 n8n 自动化工作流。覆盖 1650 多个节点、2352 个模板，支持模板优先、多级验证等最佳实践，大幅降低 n8n 使用门槛。内含详细 Claude 项目指令模板，快速上手。注意：README 强调 AI 结果不可预测，生产流程需提前备份验证。

README

n8n-MCP

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

概述

n8n-MCP 充当 n8n 工作流自动化平台与 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 版本的兼容性。成为赞助者

重要安全警告

切勿直接用 AI 编辑你的生产工作流！ 务必：

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

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

快速开始

尝试 n8n-MCP 的最快方式 — 无需安装，无需配置：

dashboard.n8n-mcp.com

免费版：每天 100 次工具调用
即时访问：立即开始构建工作流
始终最新：最新的 n8n 节点和模板
无需基础设施：我们处理所有事务

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

想自托管？ 查看自托管指南，了解 npx、Docker、Railway 和本地安装选项。

n8n 集成

想在你的 n8n 实例中使用 n8n-MCP？查看我们全面的 n8n 部署指南，了解：

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

连接你的 IDE

n8n-MCP 与多种支持 AI 的 IDE 和工具配合使用：

Claude Code — 快速设置 Claude Code CLI
Visual Studio Code — VS Code 与 GitHub Copilot 集成
Cursor — 逐步 Cursor IDE 配置
Windsurf — Windsurf 集成与项目规则
Codex — Codex 集成指南
Antigravity — Antigravity 集成指南

添加 Claude 技能（可选）

使用专业技能增强你的 n8n 工作流构建能力，教 AI 如何构建生产级工作流！

了解更多：n8n-skills 仓库

Claude 项目设置

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

你是一位使用 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 个 token）
   - `get_node({nodeType, detail: 'full'})` — 完整信息（约 3000-8000 个 token）
   - `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"})`
   - **强制注明出处**："Based on template by **[author.name]** (@[username]). View at: [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 — 使用 diff 操作更新工作流
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_credentials — 管理 n8n 凭证（list、get、create、update、delete、getSchema）

安全与审计

n8n_audit_instance — 安全审计，结合 n8n 内置审计 API 与深度工作流扫描

系统工具

n8n_health_check — 检查 n8n API 连接和功能

文档

自托管指南 — npx、Docker、Railway 和本地安装
安全与加固 — 信任模型、加固选项、工作流限制
n8n 部署指南 — 与 n8n 的生产部署
数据库配置 — SQLite 适配器和内存优化
隐私与遥测 — 我们收集什么以及如何选择退出
工作流 Diff 操作 — token 高效的工作流更新
HTTP 部署 — 远程服务器设置
变更日志 — 完整版本历史

许可证

MIT 许可证 — 详见 LICENSE。

贡献

请参阅 CONTRIBUTING.md 了解开发设置、测试和贡献指南。

致谢

请参阅致谢了解鸣谢和模板归属。

为 n8n 社区精心打造

开源项目czlonkowski2026-05-04原文

打开互动版