mcp-n8n-builder

mcp-n8n-builder

用于以编程方式创建和管理 n8n 工作流的模型上下文协议（MCP）服务。此服务提供用于与 n8n REST API 交互的工具和资源，让 AI 助手无需用户直接介入即可构建、修改和管理工作流。

功能

• 🔄 工作流管理：创建、读取、更新、删除、激活和停用工作流
• 📊 执行管理：列出并获取工作流执行详情
• ✅ 架构验证：使用 Zod 全面验证输入和输出数据
• 🔍 节点验证：在创建工作流之前，根据 n8n 提供的节点验证节点类型，防止出错
• 🤔 智能建议：检测到无效节点时，提供相似节点类型的建议
• 🛠️ 错误处理：提供详细的错误消息，便于排查问题
• 📝 文档：为所有工具和资源提供详尽的文档
• 🔍 搜索和筛选：按名称、标签或激活状态筛选工作流

⚠️ Token 消耗警告

由于 n8n 工作流的特性，此工具非常消耗 token：

• N8N 工作流是复杂的 JSON 结构，包含嵌套节点、连接、参数和设置
• 单个工作流在查看或编辑时很容易消耗数千个 token
• 无法在不丢失重要工作流信息的前提下有效精简 JSON 结构
• 大模型的上下文窗口有限——复杂工作流可能超出可用上下文

缓解策略

此工具实现了多项优化，以减少 token 用量：

• 详细程度控制：使用 OUTPUT_VERBOSITY=concise（默认值）获取摘要，而非完整 JSON
• 对象简化：工作流列表仅显示必要字段（id、名称、状态、节点数量）
• 按需包含指南：错误消息仅包含组合指南中的相关部分
• 逐工具控制详细程度：通过 verbosity 参数覆盖单个工具调用的详细程度

推荐用法

• 先列出工作流，确定所需内容（token 成本较低）
• 尽可能处理简单工作流
• 除非确实需要完整 JSON，否则使用 concise 详细程度
• 将复杂工作流拆分成更小的部分，以便于管理
• 在获取或编辑大型工作流之前，考虑 token 成本

配置

此服务需要通过 MCP 客户端进行配置。以下是适用于不同环境的示例：

Cline 配置

将以下内容添加到 Cline MCP 设置中：

{
	"mcpServers": {
		"n8n-workflow-builder": {
			"command": "npx",
			"args": ["-y", "mcp-n8n-builder"],
			"env": {
				"N8N_HOST": "http://localhost:5678/api/v1",
				"N8N_API_KEY": "your-n8n-api-key",
				"OUTPUT_VERBOSITY": "concise" // Options: 'concise' or 'full'
			}
		}
	}
}

使用 WSL 的 Claude Desktop 配置

在 WSL 环境中，将以下内容添加到 Claude Desktop 配置中：

{
	"mcpServers": {
		"n8n-workflow-builder": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"N8N_HOST=http://localhost:5678/api/v1 N8N_API_KEY=your-n8n-api-key OUTPUT_VERBOSITY=concise npx -y mcp-n8n-builder"
			]
		}
	}
}

环境变量

可使用环境变量配置此服务：

变量	描述	默认值
N8N_HOST	n8n API 的 URL	http://localhost:5678/api/v1
N8N_API_KEY	用于 n8n 身份验证的 API 密钥	""
SERVER_NAME	MCP 服务的名称	"n8n-workflow-builder"
SERVER_VERSION	MCP 服务的版本	Package version
LOG_LEVEL	日志级别	"info"
CACHE_ENABLED	启用缓存	false
CACHE_TTL	缓存 TTL（秒）	300
OUTPUT_VERBOSITY	输出详细程度（concise 或 full）	"concise"

MCP 工具

节点管理

• list_available_nodes：列出 n8n 实例中所有可用节点。重要：创建或更新工作流之前，请先使用此工具，确保只使用有效的节点类型。这有助于避免因使用当前 n8n 实例中不存在的节点类型而导致错误。

工作流管理

• list_workflows：列出 n8n 中的所有工作流及其基本信息，包括 ID、名称、状态、创建日期和标签。结果可以按激活状态、标签或名称筛选。
• create_workflow：使用指定的节点和连接在 n8n 中创建新工作流。返回已创建的工作流及其分配的 ID。会验证所有节点类型是否存在于 n8n 实例中。
• get_workflow：按 ID 获取特定工作流的完整详情，包括所有节点、连接、设置和元数据。
• update_workflow：使用新配置更新现有工作流。必须提供完整的工作流结构，而不只是要更改的部分。会验证所有节点类型是否存在于 n8n 实例中。
• delete_workflow：按 ID 永久删除工作流。此操作无法撤销。
• activate_workflow：按 ID 激活工作流，使其能够根据触发器自动运行。
• deactivate_workflow：停用工作流，防止其自动运行。

执行管理

• list_executions：列出工作流执行历史记录，包含成功／失败状态、耗时和时间戳等详情。结果可以按工作流 ID、状态筛选，也可以限制为指定数量。
• get_execution：获取特定工作流执行的详细信息，包括执行时间、状态，以及可选的每个步骤处理的完整数据。

MCP 资源

• n8n://workflows：n8n 中所有工作流的列表
• n8n://workflows/{id}：特定 n8n 工作流的详情
• n8n://executions/{id}：特定 n8n 工作流执行的详情

开发

设置

1. 克隆仓库
2. 安装依赖项：

npm install

3. 构建项目：

npm run build

4. 在开发模式下运行：

npm run dev

发布

项目使用 changesets 管理版本。发布步骤如下：

1. 创建 changeset：

npm changeset

2. 为软件包设置版本：

npm changeset version

3. 发布到 npm：

npm release

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

MIT 许可证 — 详情请参阅 LICENSE 文件。

致谢

• 基于 Model Context Protocol 构建
• 由 n8n 提供支持