n8n MCP 服务器工具参考
本页介绍实例级 MCP 服务器暴露的所有工具。
工作流管理
search_workflows
搜索工作流,并可附带筛选条件。返回每个工作流的预览信息。
参数
| 名称 |
类型 |
必填 |
描述 |
query |
string |
否 |
按名称或描述筛选 |
projectId |
string |
否 |
按项目 ID 筛选 |
limit |
integer |
否 |
限制返回结果数量(最大 200) |
输出
| 字段 |
类型 |
描述 |
data |
array |
工作流预览列表 |
data[].id |
string |
工作流的唯一标识符 |
data[].name |
string | null |
工作流名称 |
data[].description |
string | null |
工作流描述 |
data[].active |
boolean | null |
工作流是否处于激活状态 |
data[].createdAt |
string | null |
工作流创建时间的 ISO 时间戳 |
data[].updatedAt |
string | null |
工作流最近更新时间的 ISO 时间戳 |
data[].triggerCount |
number | null |
与工作流关联的触发器数量 |
data[].scopes |
string[] |
用户对此工作流拥有的权限 |
data[].canExecute |
boolean |
用户是否有权限执行该工作流 |
data[].availableInMCP |
boolean |
该工作流是否对 MCP 工具可见 |
count |
integer |
匹配筛选条件的工作流总数 |
备注
- 列类型在创建后无法通过 MCP 修改。
- 最大返回结果数为 200。
- 会包含用户对每个工作流的权限范围,方便 MCP 客户端了解可以对该工作流执行哪些操作。
- 重要:无论工作流的
Available in MCP 设置如何,此工具都可以列出当前用户有权访问的所有工作流。
get_workflow_details
获取指定工作流的详细信息,包括触发器详情。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
要获取的工作流 ID |
输出
| 字段 |
类型 |
描述 |
workflow |
object |
经过清理、适合 MCP 使用的工作流数据 |
workflow.id |
string |
工作流 ID |
workflow.name |
string | null |
工作流名称 |
workflow.active |
boolean |
工作流是否激活 |
workflow.isArchived |
boolean |
工作流是否已归档 |
workflow.versionId |
string |
当前工作流版本 ID |
workflow.activeVersionId |
string | null |
激活版本 ID(如果有) |
workflow.triggerCount |
number |
触发器数量 |
workflow.createdAt |
string | null |
创建时间的 ISO 时间戳 |
workflow.updatedAt |
string | null |
最近更新时间的 ISO 时间戳 |
workflow.settings |
object | null |
工作流设置 |
workflow.connections |
object |
工作流连接图 |
workflow.nodes |
array |
节点列表(已剥离凭据) |
workflow.activeVersion |
object | null |
激活版本的工作流图(节点 + 连接),如果可用 |
workflow.tags |
array |
带有 id 和 name 的标签列表 |
workflow.meta |
object | null |
工作流元数据 |
workflow.parentFolderId |
string | null |
父文件夹 ID |
workflow.description |
string |
工作流描述 |
workflow.scopes |
string[] |
用户对此工作流拥有的权限 |
workflow.canExecute |
boolean |
用户是否有权限执行该工作流 |
triggerInfo |
string |
描述如何触发该工作流的人类可读说明 |
备注
- 返回前会从节点中剥离敏感凭据数据。
- 如果工作流已发布,则会包含激活版本的详细信息。
execute_workflow
通过 ID 执行工作流,并将用户提示中的数据映射到触发器输入。返回执行 ID 和状态。此工具会执行“完整”的工作流运行,不会 mock 或跳过任何节点。
参数
| 名称 |
类型 |
必填 |
默认值 |
描述 |
workflowId |
string |
是 |
|
要执行的工作流 ID |
executionMode |
"manual" | "production" |
否 |
"production" |
"manual" 测试当前版本,"production" 执行已发布(激活)的版本 |
inputs |
object |
否 |
|
提供给工作流的输入(区分联合类型,见下文) |
inputs 变体(通过 type 区分):
| 类型 |
字段 |
描述 |
chat |
chatInput: string |
面向聊天型工作流的输入 |
form |
formData: Record<string, unknown> |
表单型工作流的输入数据 |
webhook |
webhookData: { method?, query?, body?, headers? } |
Webhook 型工作流的输入数据 |
输出
| 字段 |
类型 |
描述 |
executionId |
string | null |
执行 ID |
status |
string |
执行状态,可为:"success"、"error"、"running"、"waiting"、"canceled"、"crashed"、"new"、"unknown" |
error |
string |
执行失败时的错误消息 |
备注
- 仅支持特定触发器类型的工作流:Webhook、Chat Trigger、Form Trigger、Manual Trigger、Schedule Trigger。
- 当
executionMode 为 "production" 时,工作流必须有已发布(激活)的版本。
- 如果一个工作流中存在多个受支持的触发器,那么 MCP 客户端在使用工作流执行工具时可能只能通过其中一个(通常是第一个)来触发该工作流(AI Workflow Builder 工作流不受此限制)。
- 不支持执行包含多步骤表单或任何 human-in-the-loop 交互的工作流。
get_execution
通过执行 ID 和工作流 ID 获取执行详情。默认仅返回元数据。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
该执行所属的工作流 ID |
executionId |
string |
是 |
要获取的执行 ID |
includeData |
boolean |
否 |
是否包含完整执行结果数据。默认为 false(仅元数据)。 |
nodeNames |
string[] |
否 |
当 includeData 为 true 时,仅返回这些节点的数据。若省略,则包含所有节点的数据。 |
truncateData |
integer |
否 |
当 includeData 为 true 时,限制每个节点输出返回的数据项数量。 |
输出
| 字段 |
类型 |
描述 |
execution |
object | null |
执行元数据;如果发生错误则为 null |
execution.id |
string |
执行 ID |
execution.workflowId |
string |
工作流 ID |
execution.mode |
string |
执行模式 |
execution.status |
string |
执行状态 |
execution.startedAt |
string | null |
执行开始时间的 ISO 时间戳 |
execution.stoppedAt |
string | null |
执行结束时间的 ISO 时间戳 |
execution.retryOf |
string | null |
当前执行重试自哪个执行的 ID |
execution.retrySuccessId |
string | null |
重试成功的执行 ID |
execution.waitTill |
string | null |
执行等待至某时刻的 ISO 时间戳 |
data |
unknown |
执行结果数据(仅当 includeData 为 true 时出现) |
error |
string |
请求失败时的错误消息 |
备注
- 当不需要完整执行数据时,请使用轻量级元数据查询(默认行为)。
- 通过
nodeNames 过滤以及通过 truncateData 截断,有助于控制大型结果集的体积。
test_workflow
使用 pin data 测试工作流,以绕过外部服务。触发器节点、带凭据的节点以及 HTTP Request 节点会被 pin(使用模拟数据)。其他节点(Set、If、Code 等)会正常执行,包括无需凭据的 I/O 节点,如 Execute Command 或文件读写节点。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
要测试的工作流 ID |
pinData |
Record<string, array> |
是 |
工作流所有节点的 pin data。 |
triggerNodeName |
string |
否 |
可选。指定从哪个触发器节点开始执行。默认为第一个触发器节点。 |
输出
| 字段 |
类型 |
描述 |
executionId |
string | null |
测试执行 ID |
status |
string |
测试执行状态,可为:"success"、"error"、"running"、"waiting"、"canceled"、"crashed"、"new"、"unknown" |
error |
string |
执行失败时的错误消息 |
备注
- 可用于在不配置凭据或不调用外部服务的情况下测试工作流逻辑。
- 此工具会同步执行工作流(等待执行结束)。
- 存在强制的 MCP 执行超时限制(5 分钟)。
prepare_test_pin_data
为工作流准备测试用 pin data。触发器节点、带凭据的节点和 HTTP Request 节点需要 pin data。逻辑节点(Set、If、Code 等)以及无需凭据的 I/O 节点(Execute Command、文件读写)会在没有 pin data 的情况下正常执行。此工具会返回 JSON Schema,用于描述每个需要 pin data 的节点预期输出的结构。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
要为其生成测试 pin data 的工作流 ID |
输出
| 字段 |
类型 |
描述 |
nodeSchemasToGenerate |
Record<string, JsonSchema> |
需要 pin data 的节点。键为节点名,值为描述预期输出结构的 JSON Schema 对象。 |
nodesWithoutSchema |
string[] |
需要 pin data 但没有输出 Schema 的节点名。对这些节点使用空默认值 [{"json": {}}]。 |
nodesSkipped |
string[] |
不需要 pin data、会在测试中正常执行的节点。 |
coverage |
object |
覆盖率统计信息 |
coverage.withSchemaFromExecution |
number |
从最近一次成功执行输出中推断出 Schema 的节点数量 |
coverage.withSchemaFromDefinition |
number |
从节点类型定义中获得 Schema 的节点数量 |
coverage.withoutSchema |
number |
没有数据或没有 Schema 的节点数量 |
coverage.skipped |
number |
会正常执行(无需 pin data)的节点数量 |
coverage.total |
number |
启用节点总数 |
备注
- 生成
test_workflow 所需的真实示例数据时,应使用这些 Schema。
publish_workflow
发布(激活)工作流,使其可用于生产执行。这会根据当前草稿创建一个激活版本。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
要发布的工作流 ID |
versionId |
string |
否 |
可选版本 ID。若未提供,则发布当前草稿版本。 |
输出
| 字段 |
类型 |
描述 |
success |
boolean |
发布是否成功 |
workflowId |
string |
工作流 ID |
activeVersionId |
string | null |
发布后的激活版本 ID |
error |
string |
发布失败时的错误消息 |
unpublish_workflow
取消发布(停用)工作流,使其不再可用于生产执行。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
要取消发布的工作流 ID |
输出
| 字段 |
类型 |
描述 |
success |
boolean |
取消发布是否成功 |
workflowId |
string |
工作流 ID |
error |
string |
取消发布失败时的错误消息 |
search_projects
搜索当前用户可访问的项目。
参数
| 名称 |
类型 |
必填 |
描述 |
query |
string |
否 |
按项目名称筛选(大小写不敏感的部分匹配) |
type |
"personal" | "team" |
否 |
按项目类型筛选 |
limit |
integer |
否 |
限制返回结果数量(最大 100) |
输出
| 字段 |
类型 |
描述 |
data |
array |
匹配项目列表 |
data[].id |
string |
项目的唯一标识符 |
data[].name |
string |
项目名称 |
data[].type |
"personal" | "team" |
项目类型 |
count |
integer |
匹配项目总数 |
备注
- 最大返回结果数为 100。
- 该工具使 MCP 客户端能够在特定项目中创建工作流和数据表。
search_folders
搜索项目中的文件夹。
参数
| 名称 |
类型 |
必填 |
描述 |
projectId |
string |
是 |
要搜索文件夹的项目 ID |
query |
string |
否 |
按文件夹名称筛选(大小写不敏感的部分匹配) |
limit |
integer |
否 |
限制返回结果数量(最大 100) |
输出
| 字段 |
类型 |
描述 |
data |
array |
匹配文件夹列表 |
data[].id |
string |
文件夹的唯一标识符 |
data[].name |
string |
文件夹名称 |
data[].parentFolderId |
string | null |
父文件夹 ID;如果位于项目根目录则为 null |
count |
integer |
匹配文件夹总数 |
备注
- 最大返回结果数为 100。
- 该工具使 MCP 客户端能够在特定文件夹中创建工作流。
工作流构建
get_sdk_reference
获取 n8n Workflow SDK 参考文档,包括模式、表达式语法和函数。
参数
| 名称 |
类型 |
必填 |
默认值 |
描述 |
section |
string |
否 |
"all" |
要获取的文档章节。可选值:"patterns"、"expressions"、"functions"、"rules"、"import"、"guidelines"、"design"、"all" |
输出
| 字段 |
类型 |
描述 |
reference |
string |
所请求章节的 SDK 参考文档内容 |
备注
- 在构建任何工作流之前,应首先调用此工具。
- 各章节涵盖模式、表达式语法、内置函数、编码规则、导入语法、命名准则和设计建议。
search_nodes
按服务名称、触发器类型或工具功能搜索 n8n 节点。返回节点 ID、判别项(resource/operation/mode)以及 get_node_types 工具所需的相关节点。
参数
| 名称 |
类型 |
必填 |
描述 |
queries |
string[] |
是(最少 1 个) |
搜索词,例如服务名(如 "gmail"、"slack")、触发器类型(如 "schedule trigger"、"webhook")或工具节点(如 "set"、"if"、"merge"、"code") |
输出
| 字段 |
类型 |
描述 |
results |
string |
包含匹配节点 ID、判别项和相关节点的搜索结果 |
get_node_types
获取 n8n 节点的 TypeScript 类型定义。返回精确的参数名和结构。
参数
| 名称 |
类型 |
必填 |
描述 |
nodeIds |
array |
是(最少 1 个) |
节点 ID 数组。每个元素可以是普通字符串(例如 "n8n-nodes-base.gmail"),也可以是带判别项的对象(见下文)。 |
Node ID 对象格式:
| 字段 |
类型 |
必填 |
描述 |
nodeId |
string |
是 |
节点类型 ID(例如 "n8n-nodes-base.gmail") |
version |
string |
否 |
特定版本(例如 "2.1") |
resource |
string |
否 |
resource 判别项(例如 "message") |
operation |
string |
否 |
operation 判别项(例如 "send") |
mode |
string |
否 |
mode 判别项 |
输出
| 字段 |
类型 |
描述 |
definitions |
string |
所请求节点的 TypeScript 类型定义 |
备注
- 这是正确配置节点的关键工具,MCP 客户端在编写工作流代码前应始终先调用它。
- 同时支持简单字符串节点 ID 和带判别项的对象形式,用于多变体节点。
get_suggested_nodes
获取按工作流技术类别整理的精选节点推荐。返回推荐节点、模式提示和配置指导。适用于分析完要构建的工作流类型之后。
参数
| 名称 |
类型 |
必填 |
描述 |
categories |
string[] |
是(最少 1 个) |
工作流技术类别。可选值:chatbot、notification、scheduling、data_transformation、data_persistence、data_extraction、document_processing、form_input、content_generation、triage、find_research |
输出
| 字段 |
类型 |
描述 |
suggestions |
string |
包含模式提示和配置指导的精选节点推荐 |
validate_workflow
验证 n8n Workflow SDK 代码。该工具会将代码解析为工作流并检查错误。若有效,则返回工作流 JSON;若无效,则返回用于修复的详细错误消息。在创建工作流之前,务必先执行验证。
参数
| 名称 |
类型 |
必填 |
描述 |
code |
string |
是 |
使用 n8n Workflow SDK 编写的完整 TypeScript/JavaScript 工作流代码。必须包含工作流导出。 |
输出
| 字段 |
类型 |
描述 |
valid |
boolean |
工作流代码是否有效 |
nodeCount |
number |
工作流中的节点数量(若有效) |
warnings |
array |
验证警告(如果有) |
warnings[].code |
string |
标识警告类型的代码 |
warnings[].message |
string |
警告消息 |
warnings[].nodeName |
string |
触发警告的节点 |
warnings[].parameterPath |
string |
触发警告的参数路径 |
errors |
string[] |
验证错误(若无效) |
备注
- 在调用
create_workflow_from_code 或 update_workflow 之前,必须先调用此工具。
- 即使代码有效,也可能存在警告。
create_workflow_from_code
根据已验证的 SDK 代码在 n8n 中创建工作流。该工具会将代码解析为工作流并保存。
参数
| 名称 |
类型 |
必填 |
描述 |
code |
string |
是 |
使用 n8n Workflow SDK 编写的完整 TypeScript/JavaScript 工作流代码。必须先通过 validate_workflow 验证。 |
name |
string |
否 |
可选工作流名称(最多 128 个字符)。若未提供,则使用代码中的名称。 |
description |
string |
否 |
简短工作流描述(最多 255 个字符,1 到 2 句话)。 |
projectId |
string |
否 |
创建工作流的项目 ID。默认为用户的个人项目。 |
folderId |
string |
否 |
创建工作流的文件夹 ID。要求同时设置 projectId。 |
输出
| 字段 |
类型 |
描述 |
workflowId |
string |
已创建工作流的 ID |
name |
string |
已创建工作流的名称 |
nodeCount |
number |
工作流中的节点数量 |
url |
string |
可在 n8n 中打开该工作流的 URL |
autoAssignedCredentials |
array |
自动分配给节点的凭据列表 |
autoAssignedCredentials[].nodeName |
string |
自动分配凭据的节点名称 |
autoAssignedCredentials[].credentialName |
string |
自动分配的凭据名称 |
note |
string |
关于工作流创建的附加说明(例如在自动分配凭据时跳过了哪些节点) |
备注
- 会自动为节点分配可用凭据。
- HTTP Request 节点会跳过自动分配凭据,必须手动配置。
- 会将已创建工作流的
availableInMCP 标志设置为 true。
- 会为工作流标记
aiBuilderAssisted 元数据。
- 会自动解析 webhook 节点 ID。
folderId 要求同时提供 projectId。
- MCP 客户端应为所有新建工作流生成简短描述。
update_workflow
根据已验证的 SDK 代码更新 n8n 中的现有工作流。该工具会将代码解析为工作流并保存更改。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
要更新的工作流 ID |
code |
string |
是 |
使用 n8n Workflow SDK 编写的完整 TypeScript/JavaScript 工作流代码。必须先通过 validate_workflow 验证。 |
name |
string |
否 |
可选工作流名称(最多 128 个字符)。若未提供,则使用代码中的名称。 |
description |
string |
否 |
简短工作流描述(最多 255 个字符,1 到 2 句话)。 |
输出
| 字段 |
类型 |
描述 |
workflowId |
string |
已更新工作流的 ID |
name |
string |
已更新工作流的名称 |
nodeCount |
number |
工作流中的节点数量 |
url |
string |
可在 n8n 中打开该工作流的 URL |
autoAssignedCredentials |
array |
自动分配给节点的凭据列表 |
autoAssignedCredentials[].nodeName |
string |
自动分配凭据的节点名称 |
autoAssignedCredentials[].credentialName |
string |
自动分配的凭据名称 |
note |
string |
关于工作流更新的附加说明(例如在自动分配凭据时跳过了哪些节点) |
备注
- 会通过匹配节点名称和类型来保留现有工作流中用户已配置的凭据。
- 会为工作流标记
aiBuilderAssisted 元数据。
- MCP 客户端应为所有被修改的工作流(重新)生成简短描述。
archive_workflow
通过 ID 将 n8n 中的工作流归档。
参数
| 名称 |
类型 |
必填 |
描述 |
workflowId |
string |
是 |
要归档的工作流 ID |
输出
| 字段 |
类型 |
描述 |
archived |
boolean |
工作流是否已归档 |
workflowId |
string |
已归档工作流的 ID |
name |
string |
已归档工作流的名称 |
备注
数据表
search_data_tables
搜索当前用户可访问的数据表。可在修改或写入数据之前,先用它查找数据表 ID。
参数
| 名称 |
类型 |
必填 |
描述 |
query |
string |
否 |
按数据表名称筛选(大小写不敏感的部分匹配) |
projectId |
string |
否 |
按项目 ID 筛选 |
limit |
integer |
否 |
限制返回结果数量(最大 100) |
输出
| 字段 |
类型 |
描述 |
data |
array |
匹配查询的数据表列表 |
data[].id |
string |
数据表唯一标识符 |
data[].name |
string |
数据表名称 |
data[].projectId |
string |
该数据表所属项目 |
data[].createdAt |
string |
数据表创建时间的 ISO 时间戳 |
data[].updatedAt |
string |
数据表最近更新时间的 ISO 时间戳 |
data[].columns |
array |
此数据表中定义的列 |
data[].columns[].id |
string |
列唯一标识符 |
data[].columns[].name |
string |
列名称 |
data[].columns[].type |
string |
列数据类型。可为:"string"、"number"、"boolean"、"date" |
data[].columns[].index |
integer |
列在表中的位置 |
count |
integer |
匹配数据表总数 |
备注
create_data_table
使用指定列创建新的数据表。
参数
| 名称 |
类型 |
必填 |
描述 |
projectId |
string |
是 |
创建数据表的项目 ID |
name |
string |
是 |
数据表名称(最少 1 个字符,最多 128 个字符,且在项目内必须唯一) |
columns |
array |
是(最少 1 个) |
要在数据表中创建的列 |
columns[].name |
string |
是 |
列名。必须以字母开头,只能包含字母、数字和下划线(最多 63 个字符)。 |
columns[].type |
string |
是 |
列的数据类型。可为:"string"、"number"、"boolean"、"date" |
输出
| 字段 |
类型 |
描述 |
id |
string |
已创建数据表的唯一标识符 |
name |
string |
已创建数据表的名称 |
projectId |
string |
已创建数据表所属项目的 ID |
备注
- 至少需要一列。
- 表名在同一项目内必须唯一。
- 列名必须匹配模式:
^[a-zA-Z][a-zA-Z0-9_]*$(最多 63 个字符)。
add_data_table_column
向现有数据表中添加新列。
参数
| 名称 |
类型 |
必填 |
描述 |
dataTableId |
string |
是 |
要添加列的数据表 ID |
projectId |
string |
是 |
该数据表所属项目 ID |
name |
string |
是 |
列名。必须以字母开头,只能包含字母、数字和下划线(最多 63 个字符)。 |
type |
string |
是 |
新列的数据类型。可为:"string"、"number"、"boolean"、"date" |
输出
| 字段 |
类型 |
描述 |
success |
boolean |
操作是否成功 |
message |
string |
结果说明 |
column |
object |
已创建的列 |
column.id |
string |
列唯一标识符 |
column.name |
string |
列名称 |
column.type |
string |
列数据类型 |
备注
- 列名必须匹配模式:
^[a-zA-Z][a-zA-Z0-9_]*$(最多 63 个字符)。
- 列类型在创建后无法通过 MCP 修改。
rename_data_table_column
重命名数据表中的某一列。
参数
| 名称 |
类型 |
必填 |
描述 |
dataTableId |
string |
是 |
包含该列的数据表 ID |
projectId |
string |
是 |
该数据表所属项目 ID |
columnId |
string |
是 |
要重命名的列 ID |
name |
string |
是 |
新列名。必须符合列命名规则。 |
输出
| 字段 |
类型 |
描述 |
success |
boolean |
操作是否成功 |
message |
string |
结果说明 |
column |
object |
重命名后的列 |
column.id |
string |
列唯一标识符 |
column.name |
string |
新列名 |
column.type |
string |
列数据类型 |
备注
- 新名称必须符合列命名规则:
^[a-zA-Z][a-zA-Z0-9_]*$(最多 63 个字符)。
delete_data_table_column
从数据表中删除一列。该操作会永久删除该列及其所有数据。
参数
| 名称 |
类型 |
必填 |
描述 |
dataTableId |
string |
是 |
包含该列的数据表 ID |
projectId |
string |
是 |
该数据表所属项目 ID |
columnId |
string |
是 |
要删除的列 ID |
输出
| 字段 |
类型 |
描述 |
success |
boolean |
操作是否成功 |
message |
string |
结果说明 |
备注
rename_data_table
重命名现有数据表。
参数
| 名称 |
类型 |
必填 |
描述 |
dataTableId |
string |
是 |
要重命名的数据表 ID |
projectId |
string |
是 |
该数据表所属项目 ID |
name |
string |
是 |
数据表新名称(最少 1 个字符,最多 128 个字符) |
输出
| 字段 |
类型 |
描述 |
success |
boolean |
操作是否成功 |
message |
string |
结果说明 |
备注
add_data_table_rows
向现有数据表插入行。每一行都是一个将列名映射到值的对象。
参数
| 名称 |
类型 |
必填 |
描述 |
dataTableId |
string |
是 |
要插入行的数据表 ID |
projectId |
string |
是 |
该数据表所属项目 ID |
rows |
array |
是(最少 1 行,最多 1000 行) |
行对象数组。每个对象都会将列名映射到值(string、number、boolean 或 null)。 |
输出
| 字段 |
类型 |
描述 |
success |
boolean |
插入操作是否成功 |
insertedCount |
integer |
成功插入的行数 |
备注
- 每次调用最多插入 1000 行。
- 行值必须为
string、number、boolean 或 null。
- 行对象中的列名必须与数据表中现有列名完全匹配。