n8n Manager for AI Agents

[!IMPORTANT] 此仓库不再积极开发。 n8n 实例管理工具已集成到更全面的 n8n-mcp 项目中，该提供完整的 n8n 自动化与 AI 代理解决方案。

请使用 n8n-mcp 获取最新特性和更新。

这是一个模型上下文协议（MCP）服务器，使 Claude Desktop 和其他 AI 代理能够通过 n8n API 管理 n8n 工作流自动化实例。

🎯 项目概述

此 MCP 服务器为 AI 代理提供了编程管理 n8n 工作流的工具。它实现了核心 n8n API 操作，并对 API 限制进行了智能处理。

✅ 已实现的功能

• 工作流管理：创建、读取、更新和删除工作流
• 执行监控：列出并查看执行详情，删除执行记录
• Webhook 触发器：通过 webhook 端点执行工作流
• 健康监控：检查 n8n 实例连接性和配置

🚧 当前限制

• 工作流激活：无法通过 API 激活/停用工作流（需要手动在 UI 中激活）
• 直接执行：不可用 - 必须使用 webhook 触发器
• 标签及凭证：只读字段，不能通过 API 设置

🚀 已实现特性

• 工作流操作：n8n 工作流的完整 CRUD 操作
• 执行管理：查看、列出并删除执行记录
• 基于 webhook 的执行：通过 webhook URL 触发工作流
• 智能错误处理：自动移除只读字段，方法回退
• AI 友好描述：增强工具描述，附带示例和明确限制
• 游标分页：高效处理大量结果集
• 健康监控：内置连接性和配置检查

⚠️ API 限制及解决办法

发现的限制

• 工作流激活：active 字段是只读的 - 工作流必须在 UI 中手动激活
• 标签字段：创建和更新时是只读的
• PATCH 方法：某些 n8n 实例不支持用于工作流更新的 PATCH
• 直接执行：必须使用 webhook 触发器（没有直接执行 API）
• 设置字段：必需但未文档化 - 我们提供合理的默认值

未实现（API 不可用）

• 用户管理：没有公开的 API 端点
• 凭证管理：有限的 API，未暴露模式
• 停止执行：无法通过 API 停止正在运行的执行
• 变量：仅可通过源控制 API 访问
• 导入/导出：计划但尚未实现

📦 可用的 MCP 工具

工作流管理

• n8n_create_workflow - 创建带有节点和连接的新工作流
• n8n_get_workflow - 根据 ID 获取工作流详情
• n8n_update_workflow - 更新现有工作流（需要完整的节点列表）
• n8n_delete_workflow - 永久删除工作流
• n8n_list_workflows - 列出工作流，支持过滤和分页

执行管理

• n8n_trigger_webhook_workflow - 通过 webhook URL 触发工作流
• n8n_get_execution - 获取详细的执行信息
• n8n_list_executions - 列出执行情况，支持状态过滤
• nn_delete_execution - 删除执行记录

系统工具

• n8n_health_check - 检查 API 连接性和配置

🛠️ 技术栈

• 运行时：Node.js 20+
• 语言：TypeScript 5.0
• MCP SDK：@modelcontextprotocol/sdk v1.13.1
• HTTP 客户端：Axios，带重试逻辑
• 验证：Zod 模式
• 日志：Winston（MCP 模式下基于文件）
• 构建：TypeScript，ES 模块

📋 先决条件

• Node.js 20 或更高版本
• 开启 API 访问的 n8n 实例
• n8n API 密钥
• Claude Desktop（用于 MCP 集成）

🚀 快速开始

1. 克隆仓库

   git clone https://github.com/czlonkowski/n8n-manager-for-ai-agents
   cd n8n-manager-for-ai-agents
   

2. 安装依赖

   npm install
   

3. 配置环境

   cp .env.example .env
   # 使用您的 n8n 实例详细信息编辑 .env 文件
   

4. 构建项目

   npm run build
   

5. 配置 Claude Desktop 添加到您的 Claude Desktop 配置（macOS 上位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

   {
     "mcpServers": {
       "n8n-manager": {
         "command": "node",
         "args": ["/绝对路径/to/n8n-manager-for-ai-agents/build/index.js"],
         "env": {
           "N8N_API_URL": "https://您的-n8n-实例.com",
           "N8N_API_KEY": "您的-api-key",
           "LOG_LEVEL": "info",
           "NODE_ENV": "production",
           "MCP_MODE": "stdio"
         }
       }
     }
   }
   

6. 重启 Claude Desktop 并验证 n8n-manager 是否出现在 MCP 工具列表中

📁 日志文件

日志写入 ~/.n8n-manager/logs/n8n-manager.log，以避免干扰 MCP 协议通信。

💡 使用示例

创建一个简单的工作流

"创建一个名为 'Test API' 的工作流，带有手动触发器"

列出工作流

"显示所有活动的工作流"
"列出带有 'production' 标签的工作流"

检查执行

"显示工作流 ID abc123 的最近执行"
"获取执行 xyz789 的详细信息"

webhook 执行

"触发位于 https://n8n.example.com/webhook/abc-def-ghi 的 webhook"

📖 文档

• CLAUDE.md - AI 指导、示例和错误解决方案
• 产品需求文档 - 原始项目规范
• 实施检查表 - 开发进度

🧪 开发

# 运行测试
npm test

# 在开发模式下运行
npm run dev

# 类型检查
npm run typecheck

# 代码检查
npm run lint

# 构建生产环境
npm run build

🤝 贡献

欢迎贡献！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

🔐 安全

• API 密钥存储在环境变量中
• 不记录敏感数据
• 所有通信均使用 HTTPS
• 实现了速率限制和请求验证

📄 许可证

本项目采用 MIT 许可证 - 详情见 LICENSE 文件。

版权所有 (c) 2024 Romuald Czlonkowski @ aiadvisors.pl

🙏 致谢

• n8n - 工作流自动化平台
• Anthropic - 提供 Claude 和 MCP 协议
• Model Context Protocol - 使此集成成为可能的协议

📞 联系方式

Romuald Czlonkowski
aiadvisors.pl

---

第一阶段完成：核心工作流和执行管理工具完全可用。请参阅 CLAUDE.md 获取详细的使用指导和常见错误解决方案。