STARWARCLOUD STARWAR.AI
返回市场
mcp-n8n工作流构建器

mcp-n8n工作流构建器

作者：salacoste178 星标更新：2025-11-05
安装使用来源：spider==github.com

项目介绍

n8n 工作流构建器 MCP 服务器

该项目提供了一个 MCP（模型上下文协议）服务器，用于管理 n8n 工作流。它允许您通过 Claude AI 和 Cursor IDE 中可用的一系列工具来创建、更新、删除、激活和停用工作流。

图片

请注意，如果您不限制 MCP 动作的权限，可能会删除您的工作流

关键特性：

  • 通过 MCP 协议与 Claude AI 和 Cursor IDE 完全集成
  • 多实例支持 - 管理多个 n8n 环境（生产、预发布、开发）
  • 通过自然语言创建和管理工作流
  • 通过提示系统预定义的工作流模板
  • 实时反馈的交互式工作流构建
  • 向后兼容现有的单实例设置

图片

要求

  • Node.js（推荐 v14+）
  • npm
  • 具有 API 访问权限的 n8n 实例（已测试并兼容 n8n 版本 1.82.3）
  • Claude 应用或 Cursor IDE 以进行 AI 交互

安装指南

1. 从 npm 安装（推荐）

您可以直接从 npm 安装该包：

# 全局安装
npm install -g @kernel.salacoste/n8n-workflow-builder

# 或作为本地依赖项
npm install @kernel.salacoste/n8n-workflow-builder

安装后，您需要配置环境变量（见步骤 3）。

2. 克隆仓库

或者，您可以从 GitHub 克隆仓库：

git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git

然后导航到项目目录：

cd mcp-n8n-workflow-builder

3. 安装依赖项

使用 npm 安装必要的依赖项：

npm install

4. 配置环境变量

您有两个配置选项：

选项 A：多实例配置（推荐）

在项目根目录中创建一个 .config.json 文件以管理多个 n8n 环境：

{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com/api/v1/",
      "n8n_api_key": "n8n_api_key_for_production"
    },
    "staging": {
      "n8n_host": "https://staging-n8n.example.com/api/v1/", 
      "n8n_api_key": "n8n_api_key_for_staging"
    },
    "development": {
      "n8n_host": "http://localhost:5678/api/v1/",
      "n8n_api_key": "n8n_api_key_for_development"
    }
  },
  "defaultEnv": "development"
}

选项 B：单实例配置（遗留）

在项目根目录中创建一个 .env 文件，包含以下变量：

N8N_HOST=https://your-n8n-instance.com/api/v1/
N8N_API_KEY=your_api_key_here

注意： 如果未找到 .config.json，系统会自动回退到 .env 配置，确保向后兼容性。

5. 构建和运行

如果您是全局安装的，可以使用以下命令运行服务器：

n8n-workflow-builder

或者使用 JSON-RPC 模式：

n8n-workflow-builder --json-rpc

如果您克隆了仓库或作为本地依赖项安装，使用以下命令：

  • 构建项目：

    npm run build

  • 以独立模式启动 MCP 服务器：

    npm start

  • 以 JSON-RPC 模式启动进行测试：

    npm run start -- --json-rpc

服务器将启动并根据模式接受通过 stdio 或 JSON-RPC 的请求。

6. Claude 应用集成

要与 Claude 应用集成，您需要创建一个配置文件 cline_mcp_settings.json。您可以复制 cline_mcp_settings.example.json 并编辑它：

cp cline_mcp_settings.example.json cline_mcp_settings.json

然后编辑文件，提供正确的环境变量值：

{
  "n8n-workflow-builder": {
    "command": "node",
    "args": ["path/to/your/project/build/index.js"],
    "env": {
      "N8N_HOST": "https://your-n8n-instance.com/api/v1/",
      "N8N_API_KEY": "your_api_key_here",
      "MCP_PORT": "58921"
    },
    "disabled": false,
    "alwaysAllow": [
      "list_workflows",
      "get_workflow",
      "list_executions",
      "get_execution"
    ],
    "autoApprove": [
      "create_workflow",
      "update_workflow",
      "activate_workflow",
      "deactivate_workflow",
      "delete_workflow",
      "delete_execution"
    ]
  }
}

重要注意事项：

  • MCP_PORT 参数是可选的，但建议使用以避免端口冲突
  • 如果遇到冲突，请使用非标准高端口（如 58921）
  • 从版本 0.7.2 开始，服务器优雅地处理端口冲突
  • 不要在存储库中添加 cline_mcp_settings.json，因为它包含您的个人访问凭据

可用工具和功能

MCP 工具

以下工具可通过 MCP 协议获得：

工作流管理

  • list_workflows：显示一个精简的工作流列表，仅包含基本元数据（ID、名称、状态、日期、节点数、标签）。优化性能以防止大量数据传输。
  • create_workflow：在 n8n 中创建一个新的工作流。
  • get_workflow：通过其 ID 获取完整的工作流详情（包括节点和连接）。
  • update_workflow：更新现有工作流。
  • delete_workflow：通过其 ID 删除工作流。
  • activate_workflow：通过其 ID 激活工作流。
  • deactivate_workflow：通过其 ID 停用工作流。
  • execute_workflow：手动执行特定 ID 的工作流。

执行管理

  • list_executions：显示所有工作流执行的列表，并具有过滤功能。
  • get_execution：通过其 ID 获取特定执行的详细信息。
  • delete_execution：通过其 ID 删除执行记录。

标签管理

  • create_tag：创建新的标签。
  • get_tags：获取所有标签的列表。
  • get_tag：通过其 ID 获取标签详细信息。
  • update_tag：更新现有标签。
  • delete_tag：通过其 ID 删除标签。

多实例支持

新于 v0.8.0：所有 MCP 工具现在支持可选的 instance 参数以指定要针对哪个 n8n 环境：

{
  "name": "list_workflows",
  "arguments": {
    "instance": "production"
  }
}
  • 如果未提供 instance 参数，则使用默认环境
  • 可用实例在您的 .config.json 文件中定义
  • 对于单实例设置（使用 .env），忽略实例参数

所有工具都经过测试和优化，适用于 n8n 版本 1.82.3。使用的节点类型和 API 结构与此版本兼容。

关于工作流触发的重要注意事项

当使用 n8n 版本 1.82.3 时，请注意以下重要要求：

  • 触发节点是激活所必需的：n8n 至少需要一个有效的触发节点才能成功激活工作流。
  • 有效触发节点类型 包括：
    • scheduleTrigger（推荐用于自动化）
    • webhook（用于 HTTP 触发的工作流）
    • 服务特定的触发节点
  • 自动触发添加：activate_workflow 工具在检测不到触发节点时自动添加 scheduleTrigger 节点
  • 手动触发限制：manualTrigger 节点类型不被 n8n API v1.82 识别为有效触发

activate_workflow 工具实现了对触发节点的智能检测，并添加必要的属性以确保与 n8n API 兼容。

已知限制和 API 问题

在使用 n8n 版本 1.82.3 进行测试时，我们发现了一些用户应了解的 API 限制：

触发节点激活问题

n8n API 对工作流激活有严格的强制要求，这些要求并未明确记录：

状态：400
错误：工作流没有开始节点 - 至少需要一个触发器、轮询器或 webhook 节点

影响：

  • 没有被识别为有效触发节点的工作流无法通过 API 激活
  • 尽管可以在 UI 中使用，manualTrigger 节点不被视为有效触发
  • 即使添加了如 group: ['trigger'] 属性到 manualTrigger 也无法解决问题

我们的解决方案：

  • activate_workflow 函数自动检测缺失的触发节点
  • 在需要时添加一个配置良好的 scheduleTrigger
  • 保留您所有的现有节点和连接

标签管理冲突

当更新已存在的标签时，API 返回一个 409 冲突错误：

状态：409
错误：已存在同名标签

影响：

  • 如果已存在具有请求名称的标签，标签更新可能失败
  • 即使更新标签为相同名称也会发生这种情况

我们的解决方案：

  • 测试脚本现在实现标签名称的 UUID 生成
  • 在测试前清理现有标签
  • 实现适当的冲突错误处理

执行限制

执行 API 对某些触发类型有限制：

  • Webhook 触发：通过 API 执行时返回 404 错误（预期行为）
  • 手动触发：在版本 1.82.3 中无法通过 API 正确执行
  • 计划触发：可以激活但可能不会立即执行

建议： 对于需要通过 API 执行的工作流，请使用带有所需间隔设置的 scheduleTrigger。

MCP 资源

服务器提供了以下资源以更有效地访问上下文：

静态资源

  • /workflows：列出 n8n 实例中的所有可用工作流
  • /execution-stats：关于工作流执行的摘要统计信息

动态资源模板

  • /workflows/{id}：特定工作流的详细信息
  • /executions/{id}：特定执行的详细信息

MCP 提示

服务器通过提示系统提供预定义的工作流模板：

可用提示

  • 计划触发的工作流：创建一个按计划运行的工作流
  • HTTP Webhook 工作流：创建一个响应 HTTP webhook 请求的工作流
  • 数据转换工作流：创建一个处理和转换数据的工作流
  • 外部服务集成工作流：创建一个集成外部服务的工作流
  • API 数据轮询工作流：创建一个轮询 API 并处理数据的工作流，带过滤

每个提示都有可以在生成工作流时自定义的变量，例如工作流名称、计划表达式、webhook 路径等。

从单实例迁移到多实例

如果您当前使用的是单实例设置（使用 .env），并且想要迁移到多实例：

  1. 创建 .config.json，包含您现有的配置：

    {
  "environments": {
    "default": {
      "n8n_host": "https://your-existing-n8n.com/api/v1/",
      "n8n_api_key": "your_existing_api_key"
    }
  },
  "defaultEnv": "default"
}

  2. 根据需要添加其他环境：

    {
  "environments": {
    "default": {
      "n8n_host": "https://your-existing-n8n.com/api/v1/",
      "n8n_api_key": "your_existing_api_key"
    },
    "staging": {
      "n8n_host": "https://staging-n8n.com/api/v1/",
      "n8n_api_key": "staging_api_key"
    }
  },
  "defaultEnv": "default"
}

  3. 保留您的 .env 文件以确保向后兼容性（可选）

  4. 在需要时使用实例参数调用 MCP

使用示例

基本多实例使用

// 列出默认环境中的工作流
await listWorkflows();

// 列出特定环境中的工作流
await listWorkflows("production");

// 在预发布环境中创建工作流
await createWorkflow(workflowData, "staging");

Claude AI 示例

您现在可以在与 Claude 的对话中指定要针对哪个 n8n 实例：

  • "列出生产环境中的所有工作流"
  • "在预发布实例中创建一个新工作流"
  • "显示开发 n8n 的执行情况"

在 examples 目录中，您会找到设置和使用 n8n 工作流构建器与 Claude 应用的示例和说明：

  1. setup_with_claude.md - 逐步说明如何设置与 Claude 应用的集成
  2. workflow_examples.md - 使用 n8n 工作流的简单查询示例
  3. complex_workflow.md - 创建和更新复杂工作流的示例
  4. using_prompts.md - 使用提示功能快速创建工作流的指南

测试服务器

您可以使用提供的测试脚本来验证功能：

使用 test-mcp-tools.js

test-mcp-tools.js 脚本提供了对所有 MCP 工具的全面测试，以验证您的 n8n 实例。这是验证您的设置并确保所有功能正常工作的推荐方法。

# 运行所有测试
node test-mcp-tools.js

该脚本执行以下测试：

  1. 健康检查和工具可用性
  2. 工作流管理（创建、读取、更新、激活）
  3. 标签管理（创建、读取、更新、删除）
  4. 执行管理（执行、列出、获取、删除）

测试脚本创建临时测试工作流和标签，这些会在测试结束后自动清理。您可以通过修改脚本顶部的测试配置变量来自定义测试行为。

// test-mcp-tools.js 中的配置选项
const config = {
  mcpServerUrl: 'http://localhost:3456/mcp',
  healthCheckUrl: 'http://localhost:3456/health',
  testWorkflowName: 'Test Workflow MCP',
  // ... 其他选项
};

// 测试标志以启用/禁用特定测试套件
const testFlags = {
  runWorkflowTests: true,
  runTagTests: true, 
  runExecutionTests: true,
  runCleanup: true
};

其他测试脚本

# 测试与 Claude 的基本功能
node test-claude.js

# 测试提示功能
node test-prompts.js

# 测试工作流的创建和管理
node test-workflow.js

故障排除

  • 确保您正在使用 npm。
  • 如果遇到问题，请尝试清理构建目录并重新构建项目： 
    npm run clean && npm run build
  • 检查 .env 和 cline_mcp_settings.json 文件中的环境变量是否正确设置。
  • 如果与 Claude 集成出现问题，请检查 cline_mcp_settings.json 文件的位置。
  • 为了调试，使用 --json-rpc 标志运行，并使用 curl 发送测试请求到端口 3000。

常见错误及其解决方案

端口已被使用（EADDRINUSE）

如果在日志中看到以下错误：

Error: listen EADDRINUSE: 地址已在使用中 :::3456

这意味着端口 3456（MCP 服务器的默认端口）已被另一个进程占用。要解决此问题：

选项 1：使用环境变量指定自定义端口

从版本 0.7.2 开始，您可以使用 MCP_PORT 环境变量指定自定义端口：

# 在您的代码中
MCP_PORT=58921 npm start

# 或直接运行
MCP_PORT=58921 node build/index.js

如果使用 Claude Desktop，请更新您的 cline_mcp_settings.json 文件以包含新端口：

{
  "n8n-workflow-builder": {
    "command": "node",
    "args": ["path/to/your/project/build/index.js"],
    "env": {
      "N8N_HOST": "https://your-n8n-instance.com/api/v1/",
      "N8N_API_KEY": "your_api_key_here",
      "MCP_PORT": "58921"
    },
    // ...
  }
}

选项 2：查找并终止使用该端口的进程

# 在 macOS/Linux 上
lsof -i :3456
kill -9 <PID>

# 在 Windows 上
netstat -ano | findstr :3456
taskkill /PID <PID> /F

关于版本 0.7.2+ 的注意事项：从版本 0.7.2 开始，服务器包含了改进的端口冲突处理，自动检测端口已被占用的情况，并优雅地继续操作而不抛出错误。这对于 Claude Desktop 尝