n8n Workflow Builder MCP Server

---

🎯 这是什么？

n8n Workflow Builder MCP 服务通过对话式 AI 帮助你创建和管理 n8n 工作流，从而革新工作流自动化。不再需要手动编辑 JSON 或在复杂的 UI 中导航——只需用自然语言描述你的需求，让 AI 为你构建工作流。

它解决的问题

• ❌ 手动构建工作流既耗时又容易出错
• ❌ 编辑复杂的 JSON需要深厚的技术知识
• ❌ 在 IDE 和 n8n UI 之间切换会打断开发流程
• ❌ 管理多个 n8n 环境（开发、预发布、生产）十分繁琐

解决方案

• ✅ 使用 Claude AI 或 Cursor IDE 通过对话构建工作流
• ✅ 自然语言界面——用通俗易懂的英语描述工作流
• ✅ 支持多实例——在同一处管理开发、预发布和生产环境
• ✅ 17 个强大工具——全面管理工作流生命周期
• ✅ 留在 IDE 中——无需切换上下文

---

✨ 主要功能

🤖 AI 驱动的工作流创建 只需描述需求，即可创建复杂的 n8n 工作流。Claude AI 和 Cursor IDE 能理解你的意图，并生成可用于生产环境的工作流。 🌍 多实例管理 通过一个 MCP 服务即可无缝管理多个 n8n 环境（生产、预发布、开发），并智能路由到相应实例。 🛠️ 17 个全面的工具 覆盖完整的工作流生命周期： 8 个工作流工具 - 创建、更新、删除、激活、执行 4 个执行工具 - 监控、重试、分析运行记录 5 个标签工具 - 整理和分类工作流 6 个凭据工具（Epic 2）- 安全管理凭据

💬 自然语言界面 无需编辑 JSON。像这样构建工作流： “创建一个 webhook 工作流，用于验证客户邮箱、发送 Slack 通知，并将数据存储到 PostgreSQL 中” 🔒 安全至上 内置凭据保护 API 密钥加密 安全的多实例配置 日志中绝不暴露敏感数据 📚 完善的文档 38+ 个文档页面，包含指南和教程 交互式示例和工作流模式 故障排除指南和常见问题 API 参考，提供完整的工具文档

---

🚀 快速开始

前提条件

• Node.js v14+（推荐 v18+）
• npm v7+
• n8n 实例，并具备 API 访问权限（已使用 n8n v1.82.3+ 测试）
• Claude Desktop 或 Cursor IDE

安装

# Install globally via npm
npm install -g @kernel.salacoste/n8n-workflow-builder

# Verify installation
npx @kernel.salacoste/n8n-workflow-builder --version

配置

选项 1：多实例（推荐）

在项目根目录中创建 .config.json：

{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "your_production_api_key"
    },
    "staging": {
      "n8n_host": "https://staging.n8n.example.com",
      "n8n_api_key": "your_staging_api_key"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "your_dev_api_key"
    }
  },
  "defaultEnv": "development"
}

选项 2：单实例（向后兼容）

创建 .env 文件：

N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your_api_key

Claude Desktop 集成

添加到 Claude Desktop 配置文件（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

重启 Claude Desktop，即可开始使用！🎉

Cursor IDE 集成

添加到工作区中的 .cursor/mcp.json：

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

---

📖 完整文档

探索我们全面的文档网站：

🌐 完整文档

快速链接

部分	说明
🚀 快速入门教程	5 分钟内构建你的第一个工作流
📦 安装指南	详细的设置说明
🔧 配置	多实例和环境设置
🛠️ API 参考	完整的工具文档
🏗️ 多实例设置	管理多个 n8n 环境
💡 使用模式	最佳实践和对话模式
🐛 故障排除	常见问题和解决方案

---

🎨 示例

示例 1：创建 Webhook 工作流

你：

在暂存环境中创建一个 Webhook 工作流，要求：

• 在 /customer-signup 接收 POST 请求
• 验证电子邮件和姓名字段
• 通过 Gmail 发送欢迎邮件
• 将客户信息存储到 PostgreSQL

Claude： ✅ 创建包含验证、邮件和数据库节点的完整工作流

示例 2：多实例工作流管理

你：

列出生产环境中最近 7 天未运行的所有活跃工作流

Claude： 📊 分析生产环境并识别过时的工作流

示例 3：调试失败的执行

你：

调试生产环境中的工作流 456——它一直运行失败并报错

Claude： 🔍 检索执行历史、找出根本原因并提出修复建议

示例 4：凭据管理

你：

给我看看 OAuth2 凭据的架构，然后帮我为 Google Sheets API 创建凭据

Claude： 🔐 获取凭据架构并指导你安全地创建凭据

---

🛠️ MCP 工具参考

工作流管理（8 个工具）

工具	说明	示例用例
list_workflows	按筛选条件列出所有工作流	“显示生产环境中的活跃工作流”
get_workflow	获取完整的工作流详情	“获取暂存环境中的工作流 123”
create_workflow	从头构建新工作流	“创建一个每日报告工作流”
update_workflow	修改现有工作流	“为工作流 456 添加错误处理”
delete_workflow	移除工作流	“删除工作流 789”
activate_workflow	启用工作流执行	“激活工作流 123”
deactivate_workflow	禁用工作流执行	“停用工作流 456”
execute_workflow	手动触发工作流运行	“使用测试数据执行工作流 789”

执行管理（4 个工具）

工具	说明	示例用例
list_executions	使用筛选条件查看执行历史	“显示今天失败的执行记录”
get_execution	获取详细的执行信息	“获取执行记录 9876 的详情”
delete_execution	移除执行记录	“删除旧的测试执行记录”
retry_execution	重试失败的工作流运行	“重试执行记录 9876”

标签管理（5 个工具）

工具	描述	使用示例
list_tags / get_tags	获取所有工作流标签	“显示所有工作流标签”
get_tag	获取特定标签的信息	“获取 ‘email-automation’ 的标签详情”
create_tag	创建工作流分类标签	“创建标签 ‘customer-workflows’”
update_tag	修改标签信息	“将标签重命名为 ‘legacy-workflows’”
delete_tag	删除工作流标签	“删除标签 ‘deprecated’”

凭据管理（6 个工具 - Epic 2）

工具	描述	使用示例
get_credential_schema	获取凭据类型的 JSON 架构	“显示 httpBasicAuth 的架构”
list_credentials	安全指南（受 n8n API 限制）	“列出凭据指南”
get_credential	安全指南（受 n8n API 限制）	“获取凭据指南”
create_credential	创建并验证架构的凭据	“创建 Gmail OAuth2 凭据”
update_credential	不可变性指南（DELETE + CREATE）	“获取凭据更新指南”
delete_credential	永久删除凭据	“删除凭据 123”

---

🏗️ 多实例架构

通过智能路由管理多个 n8n 环境：

┌─────────────────────────────────────┐
│   MCP Server (Single Instance)     │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐  ┌──────────┐       │
│  │ ConfigLoader│ EnvironmentMgr   │
│  └──────────┘  └──────────┘       │
│         │            │             │
│         ▼            ▼             │
│  ┌─────────────────────────┐      │
│  │   Instance Routing      │      │
│  └─────────────────────────┘      │
│         │                          │
└─────────┼──────────────────────────┘
          │
    ┌─────┴─────┬─────────────┬──────────────┐
    │           │             │              │
    ▼           ▼             ▼              ▼
┌────────┐  ┌────────┐   ┌────────┐    ┌────────┐
│  Dev   │  │Staging │   │  Prod  │    │Custom  │
│ n8n    │  │  n8n   │   │  n8n   │    │  n8n   │
└────────┘  └────────┘   └────────┘    └────────┘

优势：

• ✅ 单个 MCP 服务即可管理所有环境
• ✅ 根据上下文自动路由到对应实例
• ✅ 每个环境使用单独的 API 密钥
• ✅ 在对话中轻松切换环境

---

🎯 使用场景

🚀 开发工作流

1. 在开发环境中构建： 在本地创建并测试工作流
2. 部署到预发布环境： 在 QA 环境中验证
3. 发布到生产环境： 满怀信心地部署

📊 运维与监控

• 监控各环境中的执行状态
• 通过详细分析调试失败的工作流
• 跟踪工作流性能和可靠性

🔄 工作流迁移

• 从一个实例导出工作流
• 导入到另一个实例并自动适配
• 跨环境执行批量操作

📝 文档与学习

• 自动生成工作流文档
• 通过 AI 指导学习 n8n 模式
• 浏览工作流示例和模板

---

🔒 安全与最佳实践

凭据保护

• ✅ 通过 .gitignore 自动将 .config.json 排除在 git 之外
• ✅ 不记录 API 密钥（仅显示前 20 个字符）
• ✅ 凭据由 n8n API 加密
• ✅ npm 包中不包含敏感数据

多实例安全

• ✅ 每个环境使用单独的 API 密钥
• ✅ 生产环境密钥与开发环境隔离
• ✅ API 调用前验证实例

安全操作

⚠️ IMPORTANT: Be careful with destructive operations!

- Always test in development first
- Use get_workflow to backup before modifications
- Review workflow details before deletion
- Enable debug mode for troubleshooting

---

🐛 故障排除

常见问题

MCP 服务连接失败

症状： Claude/Cursor 无法找到 n8n 工具

解决方案：

1. 重启 Claude Desktop / Cursor IDE
2. 检查 claude_desktop_config.json / .cursor/mcp.json 语法
3. 确认 n8n 实例可以访问
4. 启用调试模式：在环境中设置 DEBUG=true

完整调试指南

调用 n8n API 时出现 404 错误

症状：“Request failed with status code 404”

解决方案：

1. 确认 n8n_host 使用的是基础 URL（例如，https://n8n.example.com）
2. 不要包含 /api/v1 后缀（服务会自动添加）
3. 检查 n8n API 密钥是否具有正确的权限
4. 测试连接：curl https://your-n8n-instance.com/api/v1/workflows

配置指南

工作流激活失败

症状：“Workflow cannot be activated without valid trigger”

解决方案：

1. 确保工作流至少包含一个触发器节点（webhook、计划任务等）
2. n8n API v1.82.3 无法识别 manualTrigger
3. 如果缺少有效触发器，服务会自动添加

错误参考

获取帮助

• 📚 完整故障排除指南
• 🐛 报告问题
• 💬 GitHub 讨论区

---

📊 最新动态

Version 0.9.3（最新）- 安全与文档

• 🔒 **安全修复：**阻止将日志文件发布到 npm
• 📦 **软件包优化：**大小从 699KB 减少至 653KB
• 📚 **文档增强：**添加徽章并改进 npm 元数据
• ✅ **API 密钥轮换：**更新安全实践

Version 0.9.0 - MCP 协议合规性

• ✅ 全面支持 MCP 通知处理程序
• ✅ 修复“Method 'notifications/initialized' not found”错误
• 📦 **软件包大小优化：**从 1.3MB 降至 278KB
• 🏗️ 多实例架构，支持智能路由
• 🔐 增强凭据管理，支持架构验证

Epic 2 已完成（13/13 个故事）- 高级 API 实现

• ✅ 已实现 17 个 MCP 工具（8 个工作流 + 4 个执行 + 5 个标签 + 6 个凭据）
• ✅ 所有实现的测试成功率均为 100%
• ✅ 12,000 多行文档，包含全面的示例
• ✅ 达到可用于生产的质量，零错误

查看完整更新日志

---

🗺️ 路线图

✅ 已完成

• 核心工作流 CRUD 操作
• 执行管理与监控
• 基于标签的工作流组织
• 多实例架构
• 凭据生命周期管理
• 完整的文档网站（38 多个页面）
• 通过 CI/CD 部署 GitHub Pages

🚧 正在进行

• 工作流模板库
• 增强错误恢复模式
• 针对大型工作流的性能优化
• 高级筛选与搜索功能

🔮 计划中

• 集成可视化工作流编辑器
• 工作流版本控制与回滚
• 协作式工作流开发
• 高级分析与洞察
• 工作流市场与共享

建议功能

---

🤝 参与贡献

欢迎贡献！以下是你可以提供帮助的方式：

贡献方式

• 🐛 报告错误：创建问题
• 💡 提出功能建议：发起讨论
• 📖 **改进文档：**提交文档改进
• 🔧 **提交拉取请求：**修复错误或添加功能

开发环境设置

# Clone repository
git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git
cd mcp-n8n-workflow-builder

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm run dev

代码规范

• ✅ 使用 TypeScript 确保类型安全
• ✅ 使用 ESLint 保证代码质量
• ✅ 使用 Prettier 格式化代码
• ✅ 使用 Jest 进行测试
• ✅ 遵循 Conventional Commits 规范

贡献指南

---

📄 许可证

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

这意味着

• ✅ 允许商业使用
• ✅ 允许修改
• ✅ 允许分发
• ✅ 允许私人使用
• ⚠️ 不提供担保
• ⚠️ 不承担责任

许可证详情

---

🙏 致谢

使用以下项目构建：

• 🤖 Claude AI - AI 驱动的开发辅助
• 🔧 n8n - 工作流自动化平台
• 🔌 Model Context Protocol - AI 集成标准
• 📝 TypeScript - 类型安全的开发
• 📚 MkDocs Material - 文档框架

特别感谢：

• n8n 团队打造了出色的自动化平台
• Anthropic 团队打造了 Claude AI 和 MCP
• 所有提供反馈的贡献者和用户

---

📞 联系方式

• 🌐 文档： https://salacoste.github.io/mcp-n8n-workflow-builder/
• 📦 npm 包： https://www.npmjs.com/package/@kernel.salacoste/n8n-workflow-builder
• 💻 GitHub： https://github.com/salacoste/mcp-n8n-workflow-builder
• 🐛 问题： https://github.com/salacoste/mcp-n8n-workflow-builder/issues
• 💬 讨论： https://github.com/salacoste/mcp-n8n-workflow-builder/discussions

---