内容
n8n MCP 服务器
适用于 [n8n](https://n8n.io) 工作流自动化的 MCP 服务器。专为 AI 代理（如 Claude Code、Claude Desktop）设计，可通过编程方式管理 n8n 工作流。
智能验证、自动修复常见问题、嵌入式知识库、执行轮询、凭证管理和节点发现 — 均在一个服务器中。
## 为什么存在
n8n 的 AI 工作流功能仅限企业使用。我希望 AI 代理能够构建和管理我的工作流，因此我构建了这个 MCP 服务器。它赋予 Claude（或任何兼容 MCP）对 n8n 的完全编程控制权 — 并了 7 个常见的，这些问题会阻碍代理的正常运行。
## 快速```bash
git clone https://github.com/r-ms/n8n-mcp.git
cd n8n-mcp
npm install
npm run build## 配置
所有配置 MCP 客户端配置变量进行。
| 是否必需 | 描述 --- | --- | --- |
| `N8N_API_URL` | 是 | n8n 实例 URL（例如 `http://localhost:5678`） |
| `N8N_API_KEY` | 是 | n8n 公共 API 密钥（设置 → API → 创建 API 密钥） |
| `N8N_WEBHOOK_URL` | 否 | 如果在代理后面，则为 Webhook 的单独基准 URL。默认为 `N8N_API_URL` |
| `N8N_MCP_API_KEY` | 否 | 用于节点发现工具的 n8n MCP 服务器 API 密钥（设置 → MCP 服务器）。需要 n8n 2.14+ |
### Claude Code
添加到项目的 `.mcp.json` 中：
```json
{
"mcpServers": {
"n8n": {
"type": "stdio",
"command": "node",
"args": ["/path/to/n8n-mcp/dist/index.js"],
"env": {
"N8N_API_URL": "http://localhost:5678",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"n8n": {
"command": "node",
"args": ["/path/to/n8n-mcp/dist/index.js"],
"env": {
"N8N_API_URL": "http://localhost:5678",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
## 工具（20）
### 工作流管理（8）
| 工具 | 描述 |
| --- | --- |
| `n8n_list_workflows` | 列出所有工作流，按活动状态或名称过滤 |
| `n8n_get_workflow` | 获取具有飞行前验证警告的完整工作流定义 |
| `n8n_create_workflow` | 创建工作流，自动修复常见问题 |
| `n8n_update_workflow` | 部分更新 — 自动从当前版本填充缺失字段 |
| `n8n_update_workflow_json` | 从 JSON 字符串部署完整工作流。可选激活 |
| `n8n_delete_workflow` | 删除工作流（自动停用，首先需要确认） |
| `n8n_activate_workflow` | 激活工作流（启用触发器） |
| `n8n_deactivate_workflow` | 停用工作流（停止触发器） |
### 执行与监控（4）
| 工具 | 描述 |
| --- | --- |
| `n8n_list_executions` | 列出最近的执行，带有状态过滤和成功率 |
| `n8n_get_execution` | 详细的执行跟踪 — 节点时间、项目、错误、知识提示。`verbose` 模式用于完整输出 |
| `n8n_run_workflow` | 通过 Webhook 触发。默认等待结果（120 秒超时），返回完整跟踪 |
| `n8n_diagnose_workflow` | 在不执行的情况下对工作流运行所有飞行前检查 |
### 即席执行（1）
| 工具 | 描述 |
| --- | --- |
| `n8n_run_adhoc` | 运行一次性节点链 — 创建临时工作流，通过 Webhook 执行，返回跟踪，自动清理 |
### 凭证（3）
| 工具 | 描述 |
| --- | --- |
| `n8n_list_credentials` | 列出所有凭证（ID、名称、类型） |
| `n8n_get_credential_schema` | 获取凭证类型的 JSON 模式 — 显示创建前所需的字段 |
| `n8n_create_credential` | 创建凭证。出错时，自动获取模式作为提示 |
### 节点发现（3）— 需要 `N8N_MCP_API_KEY`
| 工具 | 描述 |
| --- | --- |
| `n8n_search_nodes` | 按关键词搜索可用的节点类型。返回 ID 和鉴别器 |
| `n8n_get_node_params` | 获取节点参数的 TypeScript 类型定义。防止猜测 |
| `n8n_get_suggested_nodes` | 按类别（聊天机器人、调度、抓取等）提供精选的 |
### 诊断（1）
| 工具 | 描述 |
| --- | --- |
| `n8n_search_knowhow` | 在嵌入式知识库中搜索 n8n 问题解决方案 |
## 飞行前验证
在每次 `create` 和 `update` 时自动应用。在 API 之前捕获并修复常见的 n8n 问题：
| 问题 | 自动修复 |
| --- | --- |
| 代码节点 v2 没有 `language` 参数 | 降级到 v1 |
| 触发器节点名称中的空格（破坏 Webhook） | 删除空格，重写连接 |
| 缺失的 `settings字段 | 添加 `{executionOrder: "v1"}` |
| `ExecuteWorkflow` 工作流 ID 作为纯字符串 | 包装在 `{value: "ID"}` 中 |
| MongoDB `find` 没有 `alwaysOutputData` | 设置为 `true` |
| SplitInBatches v3 连接到错误输出 | 从输出 0（完成）移动连接至输出 1（循环） |
| 触发器节点上缺少 `webhookId` | 自动生成 |
## 知识库
11 个模式匹配条目。当发生错误时，服务器会将其与已知的 n8n 问题进行匹配，并显示解决方案：
| 模式 | 解决方案 |
| --- | --- |
| `require()` 在沙箱中被阻止 | 使用 n8n 原生节点代替 Code 节点导入 |
| 代码节点中的 ECONNREFUSED | 任务运行器是网络隔离的 — 使用 HTTP 请求节点 |
| MongoDB 类型错误限制 | 必须是整数，而不是表达式字符串 |
| 子工作流未发布 | 在父工作流之前激活子工作流 |
| Webhook 404 | 检查：激活？名称中的空格？webhookId 设置？ |
## 弹性
- **重试，指数退避** — 网络错误和 502/503 时重试 3 次
- **执行轮询** — `n8n_run_workflow` 每 2 秒轮询一次，直到完成或超时
- **Webhook 404 恢复** — 模糊匹配活动 Webhook 路径并建议更正
## 要求
- Node.js 18+
- 启用公共 API 的 n8n（任何版本）
- 节点发现工具需要 n8n 2.14+（可选）
## 许可证
MIT
