czlonkowski--n8n-mcp/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

n8n-MCP

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

概述

n8n-MCP 充当 n8n 工作流自动化平台与 AI 模型之间的桥梁，使它们能够有效理解并使用 n8n 节点。它提供对以下内容的结构化访问：

• 2,150 个 n8n 节点 - 826 个核心节点 + 1,324 个社区节点（1,177 个已验证）
• 节点属性 - 99% 覆盖率，附带详细 schema
• 节点操作 - 可用操作的 63.6% 覆盖率
• 文档 - 来自官方 n8n 文档的 87% 覆盖率（含 AI 节点）
• AI 工具 - 检测到 265 个具备 AI 能力的工具变体，附完整文档
• 真实示例 - 从热门模板中提取的 156 个排名配置
• 模板库 - 2,352 个工作流模板，AI 元数据覆盖率 99.96%
• 社区节点 - 使用 source 过滤器搜索已验证的社区集成

支持本项目

n8n-mcp 最初是个人工具，如今帮助数以万计的开发者高效自动化工作流。维护与开发本项目与我的有偿工作形成竞争。您的赞助能帮助我投入专注时间开发新功能、快速响应 issue、保持文档更新，并确保与最新 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 及其他云服务商上部署
• 故障排查与安全最佳实践

Cloudflare Access 身份验证

若您的 n8n 实例位于 Cloudflare Access（Zero Trust）之后，请提供服务令牌以便 n8n-MCP 完成身份验证：

• N8N_CF_CLIENT_ID - Cloudflare Access Client ID
• N8N_CF_CLIENT_SECRET - Cloudflare Access Client Secret

设置后，这些值会作为 CF-Access-Client-Id / CF-Access-Client-Secret 请求头发送至 n8n API 请求、版本/健康探测及 webhook 执行。该令牌仅限于 N8N_API_URL 源站 — 对不同主机（例如拆分的 WEBHOOK_URL 源站）的 webhook 调用不会携带该令牌，以避免令牌泄露。

连接您的 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 Skills（可选）

借助专门技能加速构建 n8n 工作流，教会 AI 如何构建可用于生产的工作流！

了解更多：n8n-skills 仓库

Claude 项目配置

在 Claude Projects 中使用 n8n-MCP 以获得最佳效果，请使用以下增强版系统指令：

你是一名使用 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"})`
   - **必须注明出处**："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
// FAILS at runtime
{resource: "message", operation: "post", text: "Hello"}

// 可行 — 所有参数均显式指定
{resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
```

### Example Availability
`includeExamples: true` returns real configurations from workflow templates.
- Coverage varies by node popularity
- When no examples available, use `get_node` + `validate_node({mode: 'minimal'})`

## Validation Strategy

### Level 1 - Quick Check (before building)
`validate_node({nodeType, config, mode: 'minimal'})` - Required fields only (<100ms)

### Level 2 - Comprehensive (before building)
`validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes

### Level 3 - Complete (after building)
`validate_workflow(workflow)` - Connections, expressions, AI tools

### Level 4 - Post-Deployment
1. `n8n_validate_workflow({id})` - Validate deployed workflow
2. `n8n_autofix_workflow({id})` - Auto-fix common errors
3. `n8n_executions({action: 'list'})` - Monitor execution status

## Response Format

### Initial Creation
```
[并行静默执行工具]

已创建工作流：
- Webhook 触发器 → Slack 通知
- 已配置：POST /webhook → #general 频道

验证：所有检查均已通过
```

### Modifications
```
[静默执行工具]

已更新工作流：
- 为 HTTP 节点添加了错误处理
- 修复了必需的 Slack 参数

更改已成功验证。
```

## Batch Operations

Use `n8n_update_partial_workflow` with multiple operations in a single call:

GOOD - Batch multiple operations:
```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 Project 中，以便借助智能模板发现获得最佳的 n8n 工作流辅助。

可用的 MCP 工具

核心工具（7 个工具）

• tools_documentation - 获取任意 MCP 工具的文档（从这里开始！）
• search_nodes - 在所有节点中进行全文搜索。社区节点使用 source: 'community'|'verified'，配置使用 includeExamples: true
• get_node - 统一的节点信息工具，支持多种模式：
  • Info 模式（默认）：detail: 'minimal'|'standard'|'full'、includeExamples: true
  • Docs 模式：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 管理工具（16 个工具 - 需要 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_datatable - 管理 n8n 数据表及行（list、get、create、update、delete）

凭证管理

• n8n_manage_credentials - 管理 n8n 凭证（list、get、create、update、delete、getSchema）

安全与审计

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

系统工具

• n8n_health_check - 检查 n8n API 连通性与功能

只读部署

在治理敏感环境中，请同时使用这两个环境变量。完全禁用具有写入/破坏性操作或处理敏感数据的工具（n8n_manage_credentials 和 n8n_manage_datatable 也提供读取操作，但在此全部移除，因为即便读取也会暴露敏感信息）：

DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable

对于在同一工具名下同时包含读写的操作，仅阻止破坏性操作，同时保留 list 和 get：

DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete

搭配只读 n8n API 密钥（在 n8n 实例中：Settings → API）实现纵深防御（defence in depth）。完整设置指南见 Read-Only Deployment Recipe。

文档

• Self-Hosting Guide - npx、Docker、Railway 与本地安装
• Security & Hardening - 信任模型、加固选项、工作流限制
• n8n Deployment Guide - n8n 生产环境部署
• Database Configuration - SQLite 适配器与内存优化
• Privacy & Telemetry - 我们收集的数据及如何退出
• Workflow Diff Operations - 省 token 的工作流更新
• HTTP Deployment - 远程服务器设置
• Change Log - 完整版本历史

许可证

MIT License - 详见 LICENSE。

贡献

开发环境搭建、测试与贡献指南见 CONTRIBUTING.md。

致谢

贡献者与模板致谢见 Acknowledgments。

---

为 n8n 社区用心打造

---

💼 需要代建？

可与 AiAdvisors — 由 n8n-mcp 与 n8n-skills 背后的团队提供自动化审计、构建与运维服务。