> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/czlonkowski/n8n-mcp) · [上游 README](https://github.com/czlonkowski/n8n-mcp/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# n8n-MCP
[](https://opensource.org/licenses/MIT)
[](https://github.com/czlonkowski/n8n-mcp)
[](https://www.npmjs.com/package/n8n-mcp)
[](https://codecov.io/gh/czlonkowski/n8n-mcp)
[](https://github.com/czlonkowski/n8n-mcp/actions)
[](https://github.com/n8n-io/n8n)
[](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
[](https://railway.com/deploy/n8n-mcp?referralCode=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 版本兼容。**[成为赞助者](https://github.com/sponsors/czlonkowski)**
## 重要安全警告
**切勿直接用 AI 编辑生产工作流！** 请务必：
- 使用 AI 工具前先复制工作流
- 先在开发环境中测试
- 导出重要工作流的备份
- 部署到生产环境前验证变更
AI 结果可能不可预测。请保护好您的工作！
## 快速开始
**试用 n8n-MCP 的最快方式** — 无需安装、无需配置：
**[dashboard.n8n-mcp.com](https://dashboard.n8n-mcp.com)**
- 免费套餐：每天 100 次工具调用
- 即时访问：立即开始构建工作流
- 始终保持最新：最新的 n8n 节点与模板
- 无需基础设施：由我们处理一切
注册即可获取 API 密钥，并连接您的 MCP 客户端。
**想自托管？** 请参阅[自托管指南](./docs/SELF_HOSTING.md)，了解 npx、Docker、Railway 及本地安装选项。
## n8n 集成
想在您的 n8n 实例中使用 n8n-MCP？请查看我们的完整 [n8n 部署指南](./docs/N8N_DEPLOYMENT.md)，内容包括：
- 使用 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](./docs/CLAUDE_CODE_SETUP.md) - Claude Code CLI 快速配置
- [Visual Studio Code](./docs/VS_CODE_PROJECT_SETUP.md) - 集成 GitHub Copilot 的 VS Code
- [Cursor](./docs/CURSOR_SETUP.md) - Cursor IDE 分步配置
- [Windsurf](./docs/WINDSURF_SETUP.md) - 带项目规则的 Windsurf 集成
- [Codex](./docs/CODEX_SETUP.md) - Codex 集成指南
- [Antigravity](./docs/ANTIGRAVITY_SETUP.md) - Antigravity 集成指南
## 添加 Claude Skills（可选）
借助专门技能加速构建 n8n 工作流，教会 AI 如何构建可用于生产的工作流！
[](https://www.youtube.com/watch?v=e6VvRqmUY2Y)
了解更多：[n8n-skills 仓库](https://github.com/czlonkowski/n8n-skills)
## Claude 项目配置
在 Claude Projects 中使用 n8n-MCP 以获得最佳效果，请使用以下增强版系统指令：
````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"})`
- **必须注明出处**："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` 也提供读取操作，但在此全部移除，因为即便读取也会暴露敏感信息）：
```bash
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`：
```bash
DISABLED_TOOL_OPERATIONS=n8n_workflow_versions:delete,rollback,prune;n8n_executions:delete
```
搭配只读 n8n API 密钥（在 n8n 实例中：Settings → API）实现纵深防御（defence in depth）。完整设置指南见 [Read-Only Deployment Recipe](./docs/HTTP_DEPLOYMENT.md#read-only-deployment-recipe)。
## 文档
- [Self-Hosting Guide](./docs/SELF_HOSTING.md) - npx、Docker、Railway 与本地安装
- [Security & Hardening](./docs/SECURITY_HARDENING.md) - 信任模型、加固选项、工作流限制
- [n8n Deployment Guide](./docs/N8N_DEPLOYMENT.md) - n8n 生产环境部署
- [Database Configuration](./docs/DATABASE_CONFIGURATION.md) - SQLite 适配器与内存优化
- [Privacy & Telemetry](./PRIVACY.md) - 我们收集的数据及如何退出
- [Workflow Diff Operations](./docs/workflow-diff-examples.md) - 省 token 的工作流更新
- [HTTP Deployment](./docs/HTTP_DEPLOYMENT.md) - 远程服务器设置
- [Change Log](./CHANGELOG.md) - 完整版本历史
## 许可证
MIT License - 详见 [LICENSE](LICENSE)。
## 贡献
开发环境搭建、测试与贡献指南见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 致谢
贡献者与模板致谢见 [Acknowledgments](./docs/ACKNOWLEDGMENTS.md)。
---
为 n8n 社区用心打造
---
> 💼 **需要代建？**
>
> 可与 [AiAdvisors](https://www.aiadvisors.pl/en) — 由 n8n-mcp 与 n8n-skills 背后的团队提供自动化审计、构建与运维服务。
