Name: n8n工作流管理服务器
Author: get2knowio

使用说明

n8n mcp

用于管理n8n工作流的MCP（模型上下文协议）服务器。该服务器允许AI代理通过n8n API创建、检索、更新和管理n8n工作流。

特性

工作流管理

列出工作流：从n8n实例获取所有工作流
获取工作流：按ID检索特定工作流
创建工作流：使用节点和连接创建新工作流
更新工作流：修改现有工作流
删除工作流：删除工作流
激活/停用：控制工作流执行状态
凭据管理：列出凭据并解析凭据别名
凭证别名：在工作流中为凭据使用人性化名称
源代码管理：从源代码管理中提取更改以与远程同步
获取凭据架构：获取凭据类型的JSON模式以验证或驱动UI
传输工作流：跨项目或所有者移动工作流
转移凭证：跨项目或所有者移动凭据
执行列表：使用分页支持获取工作流执行
获取执行：按ID检索特定的执行详细信息
删除执行：删除执行记录

标签管理

标签CRUD：使用分页支持创建、读取、更新和删除标签
列表标记：获取所有具有可选分页的标签
创建标签：使用名称和可选颜色创建新标签
更新标签：更新现有标记名称和/或颜色
删除标记：按ID删除标签

变量管理

列出变量：获取所有支持分页的变量
创建变量：创建新的键值变量（强制使用唯一键）
更新变量：修改现有变量值
删除变量：删除变量
CLI和MCP支持：通过命令行和MCP工具完全访问

n8n端点兼容性和回退

此MCP服务器支持多种n8n API版本，并在端点之间自动后退以实现最大兼容性：

ID支持

UUID支持：所有工具都接受数字ID（例如。， 1, 2)以及字符串UUID（例如。， "tag-uuid-123", "workflow-abc-def")
适用于n8n Cloud（基于UUID）和自托管实例（基于数字或UUID）

标签操作回退策略

列表标签：

主要的，重要的 GET /api/v1/tags
退路： GET /rest/tags （当v1返回404/401时）

更新标签颜色：

尝试： PATCH /rest/tags/{id} 与 { color: "#ff0000" }
退路： PUT /api/v1/tags/{id} 与 { name, color }
如果两者都失败：返回有用的错误消息，说明可能需要通过UI设置颜色

设置工作流标记：

尝试： PATCH /rest/workflows/{id} 与 { tags: ["tag1", "tag2"] } （标签名称）
尝试： PATCH /rest/workflows/{id} 与 { tags: [{ id: "uuid1" }, { id: "uuid2" }] } （将ID标记为对象）
退路： PUT /api/v1/workflows/{id}/tags 与 { tagIds: ["uuid1", "uuid2"] }
如果全部失败：返回包含尝试端点和状态代码的详细错误

这种多端点方法可确保MCP服务器在以下方面工作：

n8n云（通常 /api/v1 端点）
自托管n8n v1.x+（通常 /api/v1 端点）
较旧的自托管版本（通常 /rest 端点）

错误消息

当操作因端点限制而失败时，错误响应包括：

尝试使用HTTP方法和状态代码的端点列表
有用的提示（例如，“可能需要通过n8n web UI设置标签颜色”）
关于替代方法的建议

安装

来自npm（推荐）

npm install @get2knowio/n8n-mcp

来源

git clone https://github.com/get2knowio/n8n-mcp.git
cd n8n-mcp
npm install
// See CONTRIBUTING.md for the full local dev workflow and build steps

开发容器（Docker Compose）

此仓库包括一个由Docker Compose支持的VS Code开发容器，它启动：

dev：您的开发容器（此仓库安装在 /workspaces/n8n-mcp)
n8n：同一Docker网络上的本地n8n实例，可通过以下方式访问 http://n8n:5678

在VS Code中打开文件夹，然后“在容器中重新打开”。dev容器设置了这些env变量，因此CLI和smoke测试默认与sidecar通信：

N8N_BASE_URL=http://n8n:5678
N8N_USERNAME=test, N8N_PASSWORD=test

您仍然可以用本地命令覆盖这些命令 .env 如果需要的话。

配置

设置以下环境变量：

选项1：API密钥验证

export N8N_BASE_URL=http://localhost:5678
export N8N_API_KEY=your_api_key_here

选项2：基本身份验证

export N8N_BASE_URL=http://localhost:5678
export N8N_USERNAME=your_username
export N8N_PASSWORD=your_password

用法

1）作为MCP服务器（推荐）

运行MCP服务器（推荐）--统一入口点：

# Global install
npm i -g @get2knowio/n8n-mcp

# Start server on stdio
n8n-mcp

# Or without global install
npx @get2knowio/n8n-mcp

这将启动stdio上的MCP服务器，以便与AI代理集成。通过环境变量配置访问权限（请参阅配置）。

可流式HTTP传输

代替stdio，同一台服务器可以作为长期服务器运行 超文本传输协议 服务（MCP 流式HTTP传输）——可用于在反向代理后托管或共享它跨客户：

# Start the HTTP server (flag or env)
n8n-mcp --http
# equivalently:
MCP_TRANSPORT=http n8n-mcp

它是 单租户：每个会话都使用相同的 N8N_BASE_URL / N8N_API_KEY （或基本身份验证），与stdio服务器完全一样。

HTTP特定配置（全部可选）：

变量	默认值	描述
`MCP_HTTP_PORT` （或 `PORT`)	`3000`	要绑定的端口
`MCP_HTTP_HOST`	`127.0.0.1`	要绑定的接口。默认情况下为环回 --设置为 `0.0.0.0` 揭露。
`MCP_HTTP_PATH`	`/mcp`	MCP端点路径。
`MCP_HTTP_TOKEN`	（未设置）	设置后，每个请求都必须发送 `Authorization: Bearer <token>`当未设置时，未强制执行身份验证 --仅在受信任的环回/网络上安全

端点：MCP端点为 POST/GET/DELETE <MCP_HTTP_PATH> （流式HTTP、JSON 响应， mcp-session-id 每个会话的标题）。A. GET /healthz 活性探针返回 {"ok":true} 并且故意未经认证。

⚠️ 默认绑定是环回，除非您设置，否则没有身份验证 MCP_HTTP_TOKEN. 在暴露端口之前(MCP_HTTP_HOST=0.0.0.0 或通过代理）设置令牌。

MCP客户端配置示例（HTTP）：

{
  "servers": {
    "n8n": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

2）作为CLI工具

CLI二进制文件是 n8n-mcp。全局安装后：

# Global install
npm i -g @get2knowio/n8n-mcp

# List workflows
n8n-mcp list

# With pagination
n8n-mcp list --limit 25 --cursor NEXT_CURSOR

# Get a workflow
n8n-mcp get 1

# Create from JSON
n8n-mcp create examples/example-workflow.json

# Activate / Deactivate
n8n-mcp activate 1
n8n-mcp deactivate 1

# Variables
n8n-mcp variables list
n8n-mcp variables create --key mykey --value myvalue
n8n-mcp variables update var-123 --value newvalue
n8n-mcp variables delete var-123

# Executions
n8n-mcp executions list
n8n-mcp executions get exec_123
n8n-mcp executions delete exec_123

# Tags
n8n-mcp tags list
n8n-mcp tags get 1
n8n-mcp tags create "My Tag" "#ff0000"
n8n-mcp tags update 1 "Updated Tag" "#00ff00"
n8n-mcp tags delete 1

# Webhook URLs
n8n-mcp webhook-urls 1 webhook-node-id

# Run once (optionally with input)
n8n-mcp run-once 1
n8n-mcp run-once 1 input-data.json

CLI输出格式

默认情况下，所有命令都会向stdout发送结构化JSON。
成功形状： { "ok": true, "data": <payload>, "meta"?: { ... } }
错误形状： { "ok": false, "error": { "message": string, "code"?: string, "details"?: any } } 非零退出。
旗帜：
- --compact 打印单行JSON（默认为漂亮）。
- --verbose 启用stderr的调试日志记录，而不影响stdout JSON。
ID：工作流ID可以是字符串或数字；CLI接受其中之一。

示例：

# List (pretty JSON)
n8n-mcp list --limit 1
# => { "ok": true, "data": { "data": [ ... ], "nextCursor": "..." } }

# Get (compact JSON)
n8n-mcp --compact get i47DndfezvDVfrVx
# => {"ok":true,"data":{"id":"i47DndfezvDVfrVx", ...}}

# Errors return ok:false and exit 1
n8n-mcp get
# => { "ok": false, "error": { "message": "Workflow ID required", "code": "BAD_INPUT" } }

如果您不想全局安装，请使用npx：

npx @get2knowio/n8n-mcp list

对于本地开发（npm脚本，从源代码运行），请参阅贡献.md.

MCP客户端配置示例

您可以将任何支持MCP的客户端指向 n8n-mcp 命令。中提供了两个现成的复制示例 examples/ 文件夹。

克劳德桌面（macOS/Windows/Linux）

将此内容放入您的Claude Desktop配置中（有关确切路径，请参阅Anthropic文档）：

{
  "mcpServers": {
    "n8n-mcp": {
  "command": "npx",
  "args": ["-y", "-p", "@get2knowio/n8n-mcp"],
      "env": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "your_api_key_here"
      }
    }
  }
}

示例文件： examples/mcp-client-claude-desktop.json

通用MCP客户端

{
  "servers": [
    {
      "name": "n8n-mcp",
  "command": "npx",
  "args": ["-y", "-p", "@get2knowio/n8n-mcp"],
      "env": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "your_api_key_here"
      }
    }
  ]
}

示例文件： examples/mcp-client-generic.json

VS代码MCP（故障排除）

某些环境需要显式的npx调用，因此该包在启动时可以在PATH上使用。如果您看到以下错误 sh: 1: n8n-mcp: not found，配置VS Code MCP以使用以下表单，该表单按需安装包并运行服务器：

{
  "servers": {
    "n8n-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "-p",
  "@get2knowio/n8n-mcp@<version>"
      ],
      "env": {
        "N8N_BASE_URL": "${input:n8n_base_url}",
        "N8N_API_KEY": "${input:n8n_api_key}"
      }
    }
  }
}

或者，全局安装并直接引用二进制文件：

npm i -g @get2knowio/n8n-mcp@<version>

然后设置 command 到 npx 带args ["-y", "-p", "@get2knowio/n8n-mcp@<version>"] 或者，在全局安装后，使用 n8n-mcp.

可用工具

工作流工具

list_workflows -列出所有工作流
get_workflow -按ID获取工作流
创建工作流 -创建新工作流
update_workflow -更新现有工作流（支持可选的乐观并发）
删除工作流 -删除工作流
激活工作流 -激活工作流
停用工作流 -停用工作流
停用工作流 -停用工作流
list_credentials -列出所有凭据
resolve_credential_alias -将凭据别名解析为其ID
源控制pull -从源代码管理中提取更改
get_credential_schema -获取凭据类型的JSON模式
list_workflow_tags -列出特定工作流的标签
set_workflow_tags -为特定工作流设置标签
转移工作流 -将工作流转移到其他项目或所有者
转账凭证 -将凭据转移到其他项目或所有者
列表执行 -列出带有分页的工作流执行情况
getexecution -按ID执行
删除执行 -删除执行
webhook_urls -获取webhook节点的webhook URL
run_once -手动执行一次工作流

变量工具

list_变量 -列出所有支持分页的变量
create_variable -创建新变量（需要唯一密钥）
update_variable -更新现有变量值
delete_variable -删除变量

标记工具

list_tags -列出所有带有可选分页的标签
get_tag -按ID获取标签
create_tag -创建新标签
update_tag -更新现有标签
delete_tag -删除标签

工作流验证工具

validate_workflow -在创建或更新完整的工作流程JSON之前验证它：结构（空图、重复节点名称、缺少触发器、孤立节点）、连接（悬挂节点引用、数组嵌套）、表达式（缺少 = 前缀、不平衡的大括号、未知的节点引用），以及节点目录覆盖该类型的每个节点配置。退货 { valid, issues: [{ severity, code, message, node?, path? }] }.
validate_connections -仅验证工作流的连接图。
validate_expressions -仅验证工作流节点参数中嵌入的表达式。

模板工具

由公众支持，未经身份验证 n8n模板库 (api.n8n.io，可通过 N8N_TEMPLATES_HOST)--不需要n8n许可证或身份验证。

搜索模板 -按以下方式搜索示例工作流 query, nodeTypes, category，以及 limit.
get_template -按ID为模板获取可导入的工作流JSON。

执行调试工具

list_error_executions -列出最近失败的执行，可选范围为 workflowId.
重试执行 -重试失败的执行。
停止执行 -停止正在运行的执行。

现有 getexecution 工具接受可选 includeData 用于获取每个节点运行数据的标志，修剪为故障节点及其直接上游邻居（从工作流的连接图解析），并截断以避免序列化巨大的有效载荷。通过 onlyFailedNode: false 而是包括每个节点的运行数据。

能力发现工具

发现能力 -报告此n8n实例/许可证支持哪些资源组（变量、项目、文件夹、源代码管理），这样调用者就不必猜测社区与企业门控。
健康检查 -针对配置的n8n实例进行廉价的连接和身份验证预飞行。

更新的乐观并发性

这 update_workflow 该工具通过以下方式支持可选的乐观并发控制 ifMatch 参数：

{
  "id": 1,
  "name": "Updated Workflow Name",
  "ifMatch": "W/\"1234567890\""
}

当 ifMatch 提供：

该请求包括 If-Match 带有提供值的标头
如果工作流已被其他用户修改（412前提条件失败），您将收到一条明确的错误消息
这有助于防止多用户环境中的更新冲突

工作流创建示例

带有凭证ID的基本工作流

{
  "name": "Example Workflow",
  "nodes": [
    {
      "id": "webhook",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [250, 300],
      "parameters": {
        "httpMethod": "GET",
        "path": "example"
      }
    }
  ],
  "connections": {},
  "active": false,
  "tags": ["example"]
}

带有凭据别名的工作流

现在，您可以使用人性化的凭据名称而不是ID：

{
  "name": "HTTP Request Workflow",
  "nodes": [
    {
      "id": "http-request",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 1,
      "position": [250, 300],
      "parameters": {
        "url": "https://api.example.com/data",
        "method": "GET"
      },
      "credentials": {
        "httpBasicAuth": "my-api-credentials"
      }
    }
  ],
  "connections": {},
  "active": false,
  "tags": ["example", "api"]
}

系统将自动解析 "my-api-credentials" 在创建或更新工作流之前，将其转换为适当的凭据ID。

凭据管理

列出凭据

使用 list_credentials 工具查看n8n实例中的所有可用凭据：

# Through MCP tools
{
  "tool": "list_credentials",
  "arguments": {}
}

解决凭据别名

使用 resolve_credential_alias 将凭据名称解析为其ID的工具：

# Through MCP tools
{
  "tool": "resolve_credential_alias", 
  "arguments": {
    "alias": "my-api-credentials"
  }
}

别名解析规则

独特匹配：如果只有一个凭据与别名匹配，则返回凭据ID
没有匹配：如果没有与别名匹配的凭据，则抛出错误
多场比赛：如果多个凭据具有相同的名称，则抛出错误
数值：所有数字的凭证值都被视为ID，保持不变

转移操作（企业）

传输工具允许在企业n8n设置中跨项目和所有者移动工作流和凭据：

传输工作流

// Transfer to a different project
{
  "id": 1,
  "projectId": "project-123"
}

// Transfer to a different owner
{
  "id": 1,
  "newOwnerId": "user-456"
}

// Transfer to both different project and owner
{
  "id": 1,
  "projectId": "project-123",
  "newOwnerId": "user-456"
}

转账凭证

// Same structure as workflow transfer
{
  "id": 2,
  "projectId": "project-789",
  "newOwnerId": "user-123"
}

备注：转移操作需要：

启用项目/所有权功能的企业n8n安装
执行传输的用户的适当权限
有效的目标项目ID和用户ID

如果不允许该操作，则将返回权限错误并显示明确的错误消息。

标签管理

标签用于在n8n中组织和分组工作流。MCP服务器提供全面的标签管理功能：

标签操作

列表标记：获取所有具有可选分页的标签
获取标签：按ID检索特定标签
创建标签：创建一个带有名称和可选颜色的新标签
更新标签：修改标记名称和/或颜色
删除标记：删除标签

标签示例

{
  "id": 1,
  "name": "Production",
  "color": "#ff0000",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "updatedAt": "2023-01-01T00:00:00.000Z"
}

标记API支持：

分页：使用 limit 和 cursor 列出标签时的参数
颜色支持：用于视觉组织的可选十六进制颜色代码
错误处理：对于重复的名称，正确的答案为409个，对于缺失的标签，正确的回答为404个

变量管理示例

n8n中的变量是简单的键值对，可用于配置和状态管理：

{
  "id": "var-123",
  "key": "api_endpoint",
  "value": "https://api.example.com/v1"
}

CLI使用示例

# Create a variable
n8n-mcp variables create --key environment --value production

# List all variables
n8n-mcp variables list

# Update a variable value
n8n-mcp variables update var-123 --value "https://api.newdomain.com/v2"

# Delete a variable
n8n-mcp variables delete var-123

MCP工具使用

变量可以通过MCP工具进行管理，以便与AI代理集成：

list_variables() -返回所有变量的分页列表
create_variable({ key: "config_mode", value: "advanced" }) -创建新变量
update_variable({ id: "var-123", value: "new_value" }) -更新现有变量
delete_variable({ id: "var-123" }) -删除变量

执行管理

服务器提供全面的执行管理功能：

列出执行情况

# List recent executions
n8n-mcp executions list

# List with pagination
n8n-mcp executions list --limit 20 --cursor next_page_cursor

# Filter by workflow
n8n-mcp executions list --workflow-id 1

这 list_executions 工具支持：

限制：要返回的最大执行次数（分页）
光标：用于获取下一页/上一页的分页光标
工作流ID：按特定工作流ID筛选执行

获取执行详细信息

n8n-mcp executions get exec_12345

返回完整的执行数据，包括：

执行状态和时间
输入输出数据
错误详细信息（如果失败）
节点执行结果

删除处决

n8n-mcp executions delete exec_12345

永久删除执行记录以帮助管理存储。

分页注释

列出执行情况时：

使用 limit 控制页面大小的参数
使用 nextCursor 从响应到获取下一页
游标是不透明的字符串-按原样存储和使用它们
空 nextCursor 表示没有更多可用页面

Webhook URL

这 webhook_urls 该工具可帮助您获取工作流中webhook节点的正确webhook URL。这有助于：

获取URL以配置需要调用webhooks的外部系统
在开发过程中测试webhook端点
文档和集成指南

Webhook节点的先决条件

对于 webhook_urls 要使工具正常工作，您的webhook节点必须：

类型 n8n-nodes-base.webhook
有一个...，有... path 参数已配置
成为现有工作流的一部分

URL格式

该工具以n8n的标准格式返回URL：

测试URL: ${baseUrl}/webhook-test/${path} -用于工作流开发期间的测试
生产URL: ${baseUrl}/webhook/${path} -当工作流处于活动状态时使用

示例用法

// Get webhook URLs for a node
const urls = await client.getWebhookUrls(1, 'webhook-node-id');
console.log(urls);
// Output:
// {
//   "testUrl": "http://localhost:5678/webhook-test/my-webhook",
//   "productionUrl": "http://localhost:5678/webhook/my-webhook"
// }

手动工作流执行

这 run_once 该工具允许您手动执行工作流，这对以下方面很有用：

开发过程中的测试工作流程
以编程方式触发工作流
使用特定输入数据运行工作流
调试工作流问题

工作流类型

该工具优雅地处理不同的工作流类型：

手动工作流程：以手动触发器开始的工作流（例如“开始”节点）
触发器工作流：具有自动触发的工作流（例如Webhook、Cron等）

输入数据

在执行工作流时，您可以选择提供输入数据：

// Execute without input
const execution = await client.runOnce(1);

// Execute with input data
const execution = await client.runOnce(1, { 
  name: "John Doe", 
  email: "john@example.com" 
});

响应格式

该工具返回执行详细信息：

{
  "executionId": "uuid-execution-id",
  "status": "running" // or "completed", "failed", etc.
}

发布

此项目使用自动发布。当GitHub上发布新版本时：

发布工作流会自动触发
该软件包已构建并经过测试
如果所有测试都通过，则将包发布到公共npm注册表
发布后冒烟测试从npm安装包，并验证模块导入和CLI连接
然后可以使用以下方法安装该软件包： npm install @get2knowio/n8n-mcp

必需的GitHub密码

NPM_TOKEN：一个具有发布权限的npm Automation令牌 @get2knowio 范围

剪切一个释放

您可以从GitHub UI或CLI剪切版本。CLI示例：

# Bump the version in package.json (patch bump shown)
git add package.json README.md .github/workflows/
git commit -m "chore(release): v0.1.1"
git tag v0.1.1
git push origin main --tags

# Create the GitHub release (requires gh CLI auth)
gh release create v0.1.1 -t "v0.1.1" -n "Automated release to npm"

这会触发Release工作流，该工作流构建、测试、发布到npm，然后对发布的工件运行冒烟测试。

覆盖范围报告

使用Jest收集覆盖率，并根据中的阈值强制执行 jest.config.js （CI运行 npm run test:coverage).看贡献.md 用于本地覆盖命令。

要创建新版本，请执行以下操作：

更新中的版本 package.json
在GitHub上创建一个与版本匹配的标签的新版本
自动化工作流程将处理其余部分

烟雾测试（真实n8n）

您可以使用以下命令针对实时n8n实例验证CLI接线：

npm run build
npm run smoke

烟雾探测器负载 .env （N8N_BASE_URL+凭据），并为可读堆栈启用源映射。

许可证

麻省理工学院

调试和可追溯错误

在开发或故障排除过程中，使用相关ID和源映射堆栈获取结构化、可追溯的错误：

通过设置MCP_debug=debug启用调试日志
通过设置MCP_Enable_source_maps=1启用源映射（节点18+也支持 --enable-source-maps 旗帜）

示例：

# Start MCP server with debug logging and write logs to a file (stderr)
MCP_DEBUG=debug MCP_ENABLE_SOURCE_MAPS=1 npm start 2>server.log

# Use CLI with verbose output
N8N_BASE_URL=http://localhost:5678 N8N_API_KEY=xxx \
  node dist/cli.js --verbose list

笔记：

所有日志都以JSON格式写入stderr，以避免干扰MCP stdout。
每个工具调用都包含一个correlationId，您可以跨日志进行grep。
Axios请求/响应跟踪包含在调试模式中，敏感字段已被编辑。

使用说明

n8n mcp

特性

工作流管理

标签管理

变量管理

n8n端点兼容性和回退

ID支持

标签操作回退策略

错误消息

安装

来自npm（推荐）

来源

开发容器（Docker Compose）

配置

选项1：API密钥验证

选项2：基本身份验证

用法

1） 作为MCP服务器（推荐）

可流式HTTP传输

2） 作为CLI工具

CLI输出格式

MCP客户端配置示例

克劳德桌面（macOS/Windows/Linux）

通用MCP客户端

VS代码MCP（故障排除）

可用工具

工作流工具

变量工具

标记工具

工作流验证工具

模板工具

执行调试工具

能力发现工具

更新的乐观并发性

工作流创建示例

带有凭证ID的基本工作流

带有凭据别名的工作流

凭据管理

列出凭据

解决凭据别名

别名解析规则

转移操作（企业）

传输工作流

转账凭证

标签管理

标签操作

标签示例

变量管理示例

CLI使用示例

MCP工具使用

执行管理

列出执行情况

获取执行详细信息

删除处决

分页注释

Webhook URL

Webhook节点的先决条件

URL格式

示例用法

手动工作流执行

工作流类型

输入数据

响应格式

发布

必需的GitHub密码

剪切一个释放

覆盖范围报告

烟雾测试（真实n8n）

许可证

调试和可追溯错误

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

科学研究的开源MCP服务器

1）作为MCP服务器（推荐）

2）作为CLI工具