n8n Pro MCP

n8n Pro MCP ⚙️

通过 Model Context Protocol 对可自托管的 n8n 实例进行全面管理，包括队列模式。提供 51 个工具，涵盖工作流、执行记录、标签、凭据、变量、项目、用户、安全审计、源代码控制和健康监控。

n8n-pro-mcp 通过官方 n8n public API v1，将 Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端连接到你的 n8n 实例。它支持自动游标分页、读取操作失败时采用指数退避重试（写入和 webhook 调用绝不会重试，因此不会重复产生副作用），并可离线验证工作流，在工作流到达你的实例之前捕获常见的 n8n 错误（格式错误的 {{ }} 表达式、访问 webhook 数据时未使用 .body、Code 节点缺少 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 访问、Code 节点返回格式和硬编码密钥。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（基于标签的紧急停用开关）。

安装

npm install -g n8n-pro-mcp     # or use npx, no install needed

从源码安装：

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 → Settings → n8n API → Create API key 中获取的 API 密钥
N8N_WEBHOOK_BASE_URL	—	Webhook 调用使用的单独基础 URL（队列模式下配备专用 Webhook 处理器时使用）
N8N_API_TIMEOUT_MS	—	每次请求的超时时间，单位为毫秒（默认值为 30000）
N8N_MAX_RETRIES	—	遇到 429／5xx／网络错误时的重试次数——仅应用于 GET 请求，不适用于写入或 Webhook 调用（默认值为 3，0 表示禁用）

Claude Code

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 中配置：

{
  "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 Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "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（主进程 + worker + Redis）时：

1. check_health — 确认主进程和 DB 正常运行。
2. list_running_executions — 查看当前实际正在执行的任务；列表不断增长且包含较早的 startedAt 值，表示 worker 资源不足或已卡住。
3. get_execution_stats — 查看哪些工作流失败或运行缓慢；按成功率从低到高排序。
4. 使用 N8N_WEBHOOK_BASE_URL 指向你的 Webhook 处理器，调用 run_webhook，端到端测试生产环境的数据接收路径。

开发

npm test             # build + unit tests (validation rules, client helpers, .env parser)
npm run watch        # incremental compile
npm run inspector    # interactive testing with @modelcontextprotocol/inspector

CI（GitHub Actions）会在每次推送和 PR 时运行构建、测试和 npm audit。

要求

• Node.js ≥ 18
• 启用了公共 API（未设置 N8N_PUBLIC_API_DISABLED）且具有 API 密钥的 n8n 实例
• 变量、项目和源代码控制工具需要相应的 n8n 授权功能

👤 作者

由 Helbert Paranhos 在 Strat Academy 创建。

如果这个项目对你有帮助，欢迎为仓库点亮 ⭐ 并关注 Strat Academy，获取更多 AI 自动化工具。

📄 许可证

MIT © Helbert Paranhos / Strat Academy — 详见 LICENSE。