内容
# n8n Pro MCP ⚙️
> 通过模型上下文协议（Model Context Protocol）实现对自托管n8n实例的全面管理，包括队列模式，涵盖工作流、执行、标签、凭证、变量、项目、用户、安全审计、源代码控制和健康监测等51种工具。
[](https://www.npmjs.com/package/n8n-pro-mcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/helbertparanhos/n8n-pro-mcp/stargazers)
[](https://github.com/helbertparanhos/n8n-pro-mcp/network/members)
[](https://github.com/helbertparanhos/n8n-pro-mcp/issues)
[](https://glama.ai/mcp/servers/helbertparanhos/n8n-pro-mcp)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://claude.ai/code)
[](https://cursor.sh)
[](https://claude.ai/download)
[](https://www.instagram.com/helbertparanhos)
[](https://www.youtube.com/@stratacademy)
[](https://www.linkedin.com/in/helbert-paranhos/)
[](https://buymeacoffee.com/helbertparanhos)
[](https://stratacademy.com.br)
`n8n-pro-mcp` 通过官方 [n8n 公共 API v1](https://docs.n8n.io/api/) 将 Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端连接到您的 n8n 实例，支持自动光标分页、指数级重试读取（写入和 webhook 调用永远不会重试，因此副作用不会重复），以及离线工作流验证，捕获经典的 n8n 错误（格式错误的 `{{ }}` 表达式、webhook 数据未访问 `.body`、代码节点缺少 `return [{json: {...}}]`）**在它们到达您的实例之前**。
## 为什么选择这个？
- **队列模式优先** - `list_running_executions`（实时队列视图）、`get_execution_stats`（成功率 + 每个工作流的平均持续时间）和 `check_health`（healthz、就绪状态、API 身份验证）适用于运行 `EXECUTIONS_MODE=queue` 的实例，带有工作程序和 webhook 处理器。`N8N_WEBHOOK_BASE_URL` 允许 webhook 调用针对专用 webhook 处理器。
- **完整的 API v1 覆盖** - 标签、变量、项目、用户、源代码控制和跨项目传输，超出通常的工作流/执行 CRUD。
- **内置离线验证** - `validate_workflow_json` 在不进行任何 API 调用情况下检查结构、连接完整性、孤立节点、表达式语法、webhook `.body` 访问、代码节点返回格式和硬编码秘密。`create_workflow`/`update_workflow` 自动运行它并拒绝无效有效负载。
- **安全的部分更新** - `update_workflow` 获取当前工作流，合并您传递的内容，仅剥离只读字段，这样您就不会通过发送不完整的 PUT 请求而丢失节点。
- **按名称添加标签** - `set_workflow_tags` 接受标签名称并创建缺失的标签；无需手动 ID 处理。
- **原始 API 没有的操作组合** - `summarize_execution_error`（仅失败节点 + 错误消息，而不是巨大的 JSON 转储）、`prune_executions`（批量清理，默认干运行）、`wait_for_execution`（轮询直到终端）、`clone_workflow` 和 `set_workflows_active_by_tag`（基于标签的开关）。
## 安装
```bash
npm install -g n8n-pro-mcp # 或使用 npx，无需安装
```
从源代码：
```bash
git clone https://github.com/helbertparanhos/n8n-pro-mcp.git && cd n8n-pro-mcp
npm install
npm run build
```
当从源代码运行时，您可以将 `.env.example` 复制到 `.env` **在项目根目录下** - 服务器从包根目录加载它，而不是工作目录。当通过 `npx` 安装时，请通过您的 MCP 客户端配置设置变量（不会从 npx 缓存读取 `.env` 文件）。
## 配置
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `N8N_API_URL` | ✅ | 您的实例的基本 URL（例如 `https://n8n.yourdomain.com`）- 无 `/api/v1` 后缀 |
| `N8N_API_KEY` | ✅ | n8n 的 API 密钥 → **设置 → n8n API → 创建 API 密钥** |
| `N8N_WEBHOOK_BASE_URL` | — | webhook 调用单独的基本 URL（队列模式，带有专用 webhook 处理器） |
| `N8N_API_TIMEOUT_MS` | — | 每个请求的超时时间（毫秒）（默认 `30000`） |
| `N8N_MAX_RETRIES` | — | 429/5xx/网络错误重试次数 - 仅适用于 GET 请求，绝不适用于写入或 webhook 调用（默认 `3`，`0` 禁用） |
### Claude 代码
```bash
claude mcp add n8n-pro --env N8N_API_URL=https://n8n.yourdomain.com --env N8N_API_KEY=your-key -- npx -y n8n-pro-mcp
```
或在 `.claude/settings.json` / `.mcp.json` 中：
```json
{
"mcpServers": {
"n8n-pro": {
"command": "npx",
"args": ["-y", "n8n-pro-mcp"],
"env": {
"N8N_API_URL": "https://n8n.yourdomain.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
### Claude 桌面版
`~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）：
```json
{
"mcpServers": {
"n8n-pro": {
"command": "npx",
"args": ["-y", "n8n-pro-mcp"],
"env": {
"N8N_API_URL": "https://n8n.yourdomain.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}
```
### Cursor
Cursor 的 MCP 设置（`.cursor/mcp.json`）中的相同 JSON 块。
## 工具（51）
### 工作流（12）
| 工具 | 描述 |
|------|-------------|
| `list_workflows` | 列表筛选（激活、标签、项目、名称）+ 自动分页 |
| `get_workflow` | 工作流的完整 JSON 或轻量级摘要 |
| `create_workflow` | 从 JSON 创建，自动离线验证 |
| `update_workflow` | 部分更新 - 获取、合并、验证、PUT |
| `delete_workflow` | 永久删除 |
| `activate_workflow` / `deactivate_workflow` | 切换触发器 |
| `transfer_workflow` | 在项目之间移动 |
| `search_workflows` | 跨名称、节点名称和节点类型的自由文本搜索 |
| `clone_workflow` | 复制为非活动副本 |
| `set_workflows_active_by_tag` | 按标签批量激活/停用，干运行 |
| `validate_workflow_json` | 离线验证，无 API 调用 |
### 执行（10）
| 工具 | 描述 |
|------|-------------|
| `list_executions` | 按状态/工作流/项目筛选，附带持续时间 |
| `get_execution` | 用于调试的汇总或完整节点级运行数据 |
| `delete_execution` | 删除执行记录 |
| `retry_execution` | 重试失败/停止的执行 |
| `list_running_executions` | **队列模式实时视图** 运行/排队执行的 |
| `run_webhook` | 通过生产或测试 webhook 触发工作流 |
| `wait_for_execution` | 轮询执行直到达到终端状态 |
| `summarize_execution_error` | 仅失败节点 + 错误消息 - 无巨大 JSON 转储 |
| `prune_executions` | 批量删除旧执行记录，默认干运行 |
| `get_execution_stats` | 成功率 + 按工作流筛选的平均持续时间 |
### 标签（6）
`list_tags`、`create_tag`、`update_tag`、`delete_tag`、`get_workflow_tags`、`set_workflow_tags`（按名称，自动创建缺失的标签）。
### 凭证（4）
`create_credential`、`delete_credential`、`get_credential_schema`、`transfer_credential`。秘密仅可写入 - n8n API 永远不会返回凭证数据。
### 变量（4）
`list_variables`、`create_variable`、`update_variable`、`delete_variable`（许可功能）。
### 项目（7）
`list_projects`、`create_project`、`update_project`、`delete_project`，以及成员管理：`add_user_to_project`、`remove_user_from_project`、`change_user_project_role`（许可功能）。
### 用户（5）
`list_users`、`get_user`、`create_user`（邀请）、`delete_user`、`change_user_role`。
### 系统（3）
| 工具 | 描述 |
|------|-------------|
| `check_health` | healthz + 就绪状态（DB）+ API 身份验证，附带纯语言摘要 |
| `generate_audit` | n8n 的内置安全审计（凭证、数据库、节点、文件系统、实例） |
| `pull_source_control` | 从连接的 git 仓库拉取 |
## 队列模式攻略
使用 `EXECUTIONS_MODE=queue`（主 + 工作线程 + Redis）：
1. `check_health` - 确认主进程和数据库已启动。
2. `list_running_executions` - 当前实际运行中的内容；不断增长的列表，旧的 `startedAt` 值意味着工作线程饥饿或卡住。
3. `get_execution_stats` - 哪些工作流失败或爬行；按成功率排序的最差优先。
4. 使用 `N8N_WEBHOOK_BASE_URL` 指向 webhook 处理器，运行 `run_webhook` 测试生产环境下的端到端数据摄入。
## 开发
```bash
npm test # 构建 + 单元测试（验证规则、客户端帮助程序、.env 解析器）
npm run watch # 增量编译
npm run inspector # 交互式测试，使用 @modelcontextprotocol/inspector
```
CI（GitHub Actions）在每次推送和 PR 上运行构建、测试和 `npm audit`。
## 要求
- Node.js ≥ 18
- 启用公共 API 的 n8n 实例（`N8N_PUBLIC_API_DISABLED` 未设置）和 API 密钥
- 变量、项目和源代码控制工具需要相应的许可 n8n 功能
## 👤 作者
由 **[Helbert Paranhos](https://github.com/helbertparanhos)** 在 **[Strat Academy](https://stratacademy.com.br)** 创建。
[](https://www.instagram.com/helbertparanhos)
[](https://www.youtube.com/@stratacademy)
[](https://www.linkedin.com/in/helbert-paranhos/)
[](https://buymeacoffee.com/helbertparanhos)
如果这个项目帮助了您，请考虑为仓库 ⭐ 加星，并关注 **[Strat Academy](https://stratacademy.com.br)** 以获取更多 AI 自动化工具。
## 📄 许可证
MIT © [Helbert Paranhos](https://github.com/helbertparanhos) / [Strat Academy](https://stratacademy.com.br) - 请参阅 [LICENSE](LICENSE)。
