n8n

用途

本技能用于支持创建和管理 n8n 工作流以完成自动化任务，并帮助进行 API 集成。

前置条件

需要运行中的 n8n 实例并具备 API 访问权限，环境变量示例：

• N8N_HOST=localhost
• N8N_PORT=5678
• N8N_API_KEY=your-api-key

核心概念

工作流结构

每个 n8n 工作流是 JSON，结构包含 name、nodes、connections，以及 settings（其中 executionOrder 为 v1）。

节点结构

每个节点包含 id、name、type、typeVersion、position、parameters、credentials。

连接结构

连接定义节点间的数据流，按源节点名称组织 main 数组，指向目标节点名称、类型与索引。

常见工作流模式

1. Webhook 触发工作流：创建 HTTP 端点触发执行。资料给出 Webhook 节点示例（typeVersion 2，参数含 path、httpMethod、responseMode 为 responseNode）与 Respond 节点（typeVersion 1.1），并通过连接将 Webhook 指向 Respond。访问地址为 http://localhost:5678/webhook/my-endpoint。

2. HTTP 请求模式：用于调用外部 API。示例中 HTTP Request 节点 typeVersion 为 4.2，参数含 method、url、authentication 为 predefinedCredentialType、nodeCredentialType、sendBody、specifyBody 为 json、jsonBody 为表达式，credentials 通过 ID 引用。

3. 条件分支（IF 节点）：按条件路由数据。示例 IF 节点 typeVersion 2，conditions 包含 options（caseSensitive、leftValue、typeValidation 为 strict）、conditions 数组（leftValue、rightValue、operator 类型与操作）、combinator 为 and。

4. 批量循环（SplitInBatches）：按批次处理条目。示例中 Split In Batches 节点 typeVersion 3，参数含 batchSize 为 10、options。

n8n REST API

资料列出以下 API 调用方式（均使用 X-N8N-API-KEY 请求头）：

• 列出工作流：GET http://localhost:5678/api/v1/workflows
• 获取工作流：GET http://localhost:5678/api/v1/workflows/{id}
• 创建工作流：POST http://localhost:5678/api/v1/workflows，请求体包含 name、nodes、connections
• 更新工作流：PUT http://localhost:5678/api/v1/workflows/{id}
• 激活：POST http://localhost:5678/api/v1/workflows/{id}/activate
• 停用：POST http://localhost:5678/api/v1/workflows/{id}/deactivate
• 获取执行记录：GET http://localhost:5678/api/v1/executions?workflowId={id}&limit=10&includeData=true

表达式语法

n8n 使用表达式处理动态值，资料列出：

• ={{ $json.field }}：访问当前条目字段
• ={{ $json.body.param }}：访问嵌套字段
• ={{ $('Node Name').item.json.field }}：访问特定节点的输出
• ={{ $input.first().json }}：第一个输入条目
• ={{ $input.all() }}：全部输入条目
• ={{ JSON.stringify($json) }}：转换为 JSON 字符串

常用节点类型

• Webhook（n8n-nodes-base.webhook）：HTTP 触发
• HTTP Request（n8n-nodes-base.httpRequest）：API 调用
• Respond to Webhook（n8n-nodes-base.respondToWebhook）：返回 HTTP 响应
• IF（n8n-nodes-base.if）：条件分支
• Switch（n8n-nodes-base.switch）：多路分支
• Set（n8n-nodes-base.set）：数据转换
• Code（n8n-nodes-base.code）：自定义 JavaScript
• Split In Batches（n8n-nodes-base.splitInBatches）：循环处理
• Merge（n8n-nodes-base.merge）：合并分支

MCP 集成

n8n 可通过内置 MCP 服务器将工作流暴露为 MCP 工具：在工作流设置中启用 "availableInMCP": true；MCP 端点地址为 http://localhost:5678/mcp-server/http；可使用 supergateway 进行 Claude Code 集成。

提示

• Webhook 响应：使用 responseMode 为 responseNode 配合 Respond 节点进行控制
• 凭据：将 API 密钥存储在 n8n 凭据中，通过 ID 引用
• 错误处理：添加 Error Trigger 节点用于失败通知
• 测试：开发期间使用 /webhook-test/ 路径
• ADF 格式：Jira/Confluence 富文本需要 Atlassian Document Format

限制

资料未说明具体收费、价格、平台适用范围或效果数据，暂未提供。