mcp-n8n

MCP n8n 服务

通过 Cursor 或 Claude 操作和构建 n8n——管理你的实例（用户、项目、执行记录、审计），并且提供完整的构建工作流：包含 560 个节点及其真实参数架构的目录（从官方 n8n 软件包中提取）、保存前验证、自动修复、支持回滚和差异对比的快照、按节点进行执行调试、运行状况报告，以及完整实例备份。

只需两个环境变量。可在你的机器上运行（stdio），也可作为远程 HTTP 服务运行。无需托管账户。

---

🎯 令牌优化

此服务经过优化，可最大限度地减少令牌消耗，解决 MCP 服务最突出的问题之一——API 令牌使用过多。

优化内容：

• 通过新的 n8n_list_workflows_summary 端点，列出工作流时的令牌消耗减少 90%
• 字段筛选——只请求你需要的数据
• 智能默认值——每次查询的结果数从 100 条减少到 10–20 条
• 智能警告——在操作将消耗大量令牌时发出提醒

详细使用指南请参阅 TOKEN_OPTIMIZATION.md。

---

✨ 功能

🔄 工作流管理

• 创建和部署：通过自然语言描述构建工作流
• CRUD 操作：全面管理工作流生命周期（创建、读取、更新、删除）
• 激活控制：按需启用或停用工作流
• 项目转移：在项目之间无缝移动工作流
• 标签管理：使用自定义标签整理工作流

📊 执行监控

• 实时跟踪：通过高级筛选条件监控工作流执行
• 详细分析：访问完整的执行数据和日志
• 错误恢复：自动重试失败的执行
• 清理工具：高效管理执行历史记录

🔐凭据管理

• 安全创建：为任何服务添加凭据
• 架构发现：自动发现凭据类型所需的字段
• 项目隔离：在项目之间安全地转移凭据
• 类型支持：兼容所有 n8n 凭据类型

🧱 工作流构建器

• 完整节点目录 — 560 个节点，包含真实架构：直接从 n8n-nodes-base 和 @n8n/n8n-nodes-langchain 提取（包含带类型的参数、允许的选项、显示条件、凭据、最新的 typeVersion），由 CI 每周重新生成。使用 n8n_search_nodes 搜索，使用 n8n_get_node 查看
• 真实验证：n8n_validate_workflow 根据真实架构进行检查——不存在的节点类型、缺少必需参数（包括有条件必需的参数）、无效的选项值、错误的 typeVersion、损坏的连接——在保存/激活前完成
• 表达式 lint：检测缺少 = 前缀的 {{ }} 表达式，以及对工作流中不存在的节点的引用
• 自动修复：n8n_autofix_workflow 修复缺少的 typeVersion/位置、重复名称、悬空连接和表达式前缀——先预览，再通过快照应用
• 精准编辑：n8n_update_workflow_partial 添加/移除节点和连接，无需重写整个工作流
• 公开模板：从 n8n.io 搜索并导入（n8n_search_public_templates、n8n_import_public_template），并附带 100 个模板作为备用
• 引导式提示词：MCP 提示词 build-workflow 和 fix-workflow 可引导任何 Agent 完成完整的构建/验证/测试/修复流程

🔬 深度调试与健康状况

• 单节点执行数据：n8n_get_node_execution_data 显示流经某个节点的具体数据（状态、条目数、输出样本、错误详情），无需下载整个执行记录
• 调试循环：n8n_debug_last_error 返回最近一次错误中的故障节点和错误消息
• 健康报告：n8n_workflow_health 根据近期执行记录计算每个工作流的成功率、失败次数、平均持续时间和最近一次失败，并按最差项优先排序

🛡️ 安全保障与真实测试

• 自动快照：每次更新、部分编辑、自动修复或删除之前，都会在本地保存先前状态（~/.mcp-n8n/snapshots，可通过 N8N_SNAPSHOT_DIR 配置）
• 回滚：n8n_rollback_workflow 可恢复任何快照，甚至可重新创建已删除的工作流（recreate=true）
• 差异对比：n8n_diff_workflow_snapshot 在决定是否回滚前，对比快照与当前状态（新增/移除/修改的节点、变更的参数、连接变化）
• 完整实例备份：n8n_export_all_workflows 将每个工作流保存为 JSON 文件；n8n_import_workflows 可还原它们
• 端到端测试：n8n_trigger_webhook 会在实例上调用 Webhook 触发的工作流并返回真实的 HTTP 响应，以便 Agent 验证流程确实有效

🎯 内置模板

• 100 个本地起点模板，支持关键词匹配；如果你不想访问 n8n.io，可使用这些模板

🏗️ 组织与管理

• 标签：对资源进行分类和整理
• 变量：集中管理环境变量
• 项目：支持多租户项目
• 用户与权限：完整的访问控制管理
• 审计日志：生成安全与合规报告

---

🚀 快速开始

通过 npm 安装（推荐）

这是最简单的入门方式：

npm install -g mcp-n8n

配置

1. 获取 n8n API 凭据：

   • 前往你的 n8n 实例 → Settings → n8n API
   • 生成新的 API 密钥

2. 配置 Claude Desktop：

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac/Linux）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

选项 A - 使用全局安装（如果你运行了 npm install -g mcp-n8n）：

{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}

N8N_TOOLSETS 是可选的（默认值为 all）。如果你希望使用操作和创建功能，但不需要用户/项目管理工具，请使用 core,builder。仅在管理实例时使用 admin。

远程 HTTP 模式（可选）

默认情况下，服务器通过 stdio（本地）通信。要将其作为共享的远程服务运行（例如在 Docker 或 VPS 中），请设置端口：

N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n

这会在端口 3000 上通过可流式 HTTP 暴露 MCP 协议，并提供 GET /health 端点。强烈建议设置 N8N_MCP_HTTP_TOKEN：设置后，每个请求都必须包含 Authorization: Bearer <token>。将支持可流式 HTTP 的 MCP 客户端指向 http://your-host:3000，并添加该请求头。

选项 B - 使用 npx（无需安装，始终使用最新版本）：

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 配置 Cursor：

在 Cursor MCP 设置中添加（Settings → Extensions → MCP）：

推荐 - 使用 npx（始终使用最新版本）：

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

注意：Cursor 要求使用 npx 运行 MCP 服务。-y 标志会自动安装/更新软件包，无需提示。

选项 C - Docker：

docker build -t mcp-n8n .

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

/data 卷会在不同运行之间保留工作流快照。

4. 重启 Claude Desktop 或 Cursor

---

💬 使用示例

配置完成后，使用自然语言与 n8n 交互：

创建工作流

"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"

"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"

使用模板

"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template

"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template

管理工作流

"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage

"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed

"Deactivate the 'Daily Backup' workflow"

"What went wrong with execution abc123?"

监控与调试

"Show me the last 10 failed executions"

"Retry all failed executions from workflow xyz456"

"Delete all successful executions older than 30 days"

---

🛠️ 可用工具

工作流

• n8n_create_workflow - 创建新工作流（先验证）
• n8n_list_workflows_summary - 节省令牌的列表
• n8n_list_workflows - 完整详情，可选择筛选字段
• n8n_get_workflow - 完整工作流 JSON
• n8n_update_workflow - 替换字段（未提供的字段保留当前值）
• n8n_update_workflow_partial - 精细编辑：添加/移除节点和连接
• n8n_delete_workflow - 永久移除工作流
• n8n_activate_workflow / n8n_deactivate_workflow
• n8n_transfer_workflow / 标签工具

安全与测试

• n8n_list_workflow_snapshots - 此服务执行的每次更改的本地历史记录
• n8n_rollback_workflow - 恢复到之前的版本，或重新创建已删除的工作流
• n8n_diff_workflow_snapshot - 回滚前比较快照与当前状态
• n8n_trigger_webhook - 调用 Webhook 工作流并获取实际响应
• n8n_export_all_workflows / n8n_import_workflows - 完整实例备份与恢复

构建器

• n8n_search_nodes / n8n_get_node - 完整目录：560 个节点，包含真实参数架构
• n8n_validate_workflow - 保存/激活前，根据真实架构检查 JSON
• n8n_autofix_workflow - 机械修复：typeVersion、位置、重复项、悬空连接、表达式前缀
• n8n_search_public_templates / n8n_import_public_template - 官方 n8n.io 库
• n8n_list_workflow_templates / n8n_get_workflow_template / n8n_create_workflow_from_template - 内置模板

包含 13 个类别的 100 个模板：

• 电子商务：Shopify 自动化、WooCommerce 支持 Agent
• 社交媒体：Instagram、TikTok、LinkedIn、Twitter 自动化
• AI/聊天：聊天机器人、AI Agent、语音助手
• 通信：WhatsApp、Telegram、电子邮件自动化
• 内容：博客自动化、视频生成、SEO 优化
• 人力资源/招聘：简历筛选、候选人搜寻
• 销售/CRM：潜在客户开发、冷呼叫工作流
• 金融：股票分析、发票提取
• 数据抓取：Google Maps、LinkedIn、Amazon、TikTok
• 监控：网站正常运行时间、竞争对手跟踪
• 生产力：日历、Notion、日程安排自动化

执行（4 个工具）

• n8n_list_executions - 按状态、工作流、项目筛选
• n8n_get_execution - 详细的执行数据
• n8n_delete_execution - 移除执行记录
• n8n_retry_execution - 重试失败的执行
• n8n_debug_last_error - 上次错误中的失败节点及消息
• n8n_get_node_execution_data - 流经某个特定节点的数据
• n8n_workflow_health - 每个工作流的成功率、失败次数和耗时

凭证（4 个工具）

• n8n_create_credential - 添加新凭证
• n8n_delete_credential - 移除凭证（仅限所有者）
• n8n_get_credential_schema - 查看必填字段
• n8n_transfer_credential - 在项目之间迁移

组织（19 个工具）

标签：创建、列出、获取、更新、删除 变量：创建、列出、更新、删除 用户：列出、创建、获取、删除、更改角色 项目：创建、列出、更新、删除、管理用户

高级（2 个工具）

• n8n_generate_audit - 安全审计报告
• n8n_pull_source_control - 版本控制集成

默认提供 61 个工具（N8N_TOOLSETS=all）。core,builder 提供 28 个工具。另有 2 个 MCP 提示词（build-workflow、fix-workflow）。

---

📚 文档

• 快速入门指南 - 5 分钟内快速上手
• 示例与用例 - 真实场景中的自动化示例
• 节点参考 - 详细的工具文档
• 更新日志 - 版本历史与更新

---

🏗️ 项目结构

mcp-n8n/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── n8n-client.ts     # n8n API client
│   └── types.ts          # TypeScript definitions
├── examples/
│   ├── templates-metadata.json
│   └── *.json            # Pre-built workflow templates
├── dist/                 # Compiled output
├── QUICKSTART.md         # Quick start guide
├── EXAMPLES.md           # Usage examples
├── NODE_REFERENCE.md     # API documentation
└── package.json

---

🔧 开发

本地安装（用于开发）

如果你想贡献代码或测试本地更改：

1. 设置

# Clone repository
git clone https://github.com/leonardosepulvedat/mcp-n8n.git
cd mcp-n8n

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

2. 使用本地构建进行配置

对于 Claude Desktop，添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

对于 Cursor，添加到 MCP 设置：

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

重要：将 /absolute/path/to/mcp-n8n/ 替换为克隆仓库的实际绝对路径（例如，/Users/yourname/projects/mcp-n8n/）。

3. 测试

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
node dist/index.js

---

如何运行

运行主脚本，请执行：

python main.py

如何测试

运行测试，请执行：

pytest test_main.py

---

📋 要求

• Node.js：20 或更高版本
• n8n 实例：可自托管或使用 n8n Cloud（付费计划）
• n8n API 密钥：身份验证所必需
• AI IDE：支持 MCP 的 Claude Desktop 或 Cursor

n8n 要求

• 可自托管：拥有完整的 API 访问权限 ✅
• n8n Cloud：访问 API 需要付费计划
• 版本：兼容 n8n v1.0.0 及更高版本

---

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 发起 Pull Request

---

📝 许可证

本项目采用 MIT License 许可，详情请参阅 LICENSE 文件。

---

🙏 致谢

• n8n - 工作流自动化平台
• Anthropic - Claude 和 Model Context Protocol
• Cursor - AI 驱动的代码编辑器

---

🔗 资源

• n8n API 文档
• Model Context Protocol
• n8n 社区
• MCP 服务注册表

---

⚠️ 重要说明

API 访问

• n8n Cloud 需要付费计划才能访问 API
• 可自托管的 n8n 在所有计划中均提供完整的 API 访问权限
• 某些操作需要所有者／管理员权限

安全

• 切勿提交包含凭据的 .env 文件
• 使用环境变量存储敏感数据
• API 密钥可授予对 n8n 实例的完整访问权限
• 定期轮换 API 密钥以确保安全

速率限制

• 遵守 n8n API 速率限制
• 对大型结果集使用分页
• 针对速率限制响应实现错误处理

---

🐛 故障排除

连接问题

问题：“Cannot connect to n8n API”

• 验证 N8N_BASE_URL 是否正确且可访问
• 检查 API 密钥是否有效
• 确保 n8n 实例正在运行

权限错误

问题：“Insufficient permissions”

• 某些操作需要所有者／管理员角色
• 确认你的用户拥有相应权限
• 检查项目级访问权限

模板问题

问题：“Template not found”

• 确保 examples/ 目录存在
• 确认 templates-metadata.json 存在
• 检查模板文件引用是否正确

---

💡 提示与最佳实践

1. 从模板开始：使用预构建模板作为起点
2. 使用标签：通过标签整理工作流，便于管理
3. 监控执行情况：定期检查失败的执行
4. 清理数据：删除旧的执行数据以节省空间
5. 版本控制：使用 n8n 内置的版本控制功能
6. 先进行测试：在生产环境中启用工作流之前先进行测试

---

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• n8n Community: community.n8n.io

---