Skip to content

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 带有 idname 的标签列表
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#

自 n8n v2.12.0 起可用

通过执行 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#

自 n8n v2.15.0 起可用

使用 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#

自 n8n v2.15.0 起可用

为工作流准备测试用 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#

自 n8n v2.12.0 起可用

发布(激活)工作流,使其可用于生产执行。这会根据当前草稿创建一个激活版本。

参数#

名称 类型 必填 描述
workflowId string 要发布的工作流 ID
versionId string 可选版本 ID。若未提供,则发布当前草稿版本。

输出#

字段 类型 描述
success boolean 发布是否成功
workflowId string 工作流 ID
activeVersionId string | null 发布后的激活版本 ID
error string 发布失败时的错误消息

unpublish_workflow#

自 n8n v2.12.0 起可用

取消发布(停用)工作流,使其不再可用于生产执行。

参数#

名称 类型 必填 描述
workflowId string 要取消发布的工作流 ID

输出#

字段 类型 描述
success boolean 取消发布是否成功
workflowId string 工作流 ID
error string 取消发布失败时的错误消息

search_projects#

自 n8n v2.14.0 起可用

搜索当前用户可访问的项目。

参数#

名称 类型 必填 描述
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#

自 n8n v2.14.0 起可用

搜索项目中的文件夹。

参数#

名称 类型 必填 描述
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 v2.12.0 起可用

获取 n8n Workflow SDK 参考文档,包括模式、表达式语法和函数。

参数#

名称 类型 必填 默认值 描述
section string "all" 要获取的文档章节。可选值:"patterns""expressions""functions""rules""import""guidelines""design""all"

输出#

字段 类型 描述
reference string 所请求章节的 SDK 参考文档内容

备注#

  • 在构建任何工作流之前,应首先调用此工具。
  • 各章节涵盖模式、表达式语法、内置函数、编码规则、导入语法、命名准则和设计建议。

search_nodes#

自 n8n v2.12.0 起可用

按服务名称、触发器类型或工具功能搜索 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 v2.12.0 起可用

获取 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#

自 n8n v2.12.0 起可用

获取按工作流技术类别整理的精选节点推荐。返回推荐节点、模式提示和配置指导。适用于分析完要构建的工作流类型之后。

参数#

名称 类型 必填 描述
categories string[] 是(最少 1 个) 工作流技术类别。可选值:chatbotnotificationschedulingdata_transformationdata_persistencedata_extractiondocument_processingform_inputcontent_generationtriagefind_research

输出#

字段 类型 描述
suggestions string 包含模式提示和配置指导的精选节点推荐

validate_workflow#

自 n8n v2.12.0 起可用

验证 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_codeupdate_workflow 之前,必须先调用此工具。
  • 即使代码有效,也可能存在警告。

create_workflow_from_code#

自 n8n v2.12.0 起可用

根据已验证的 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#

自 n8n v2.12.0 起可用

根据已验证的 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#

自 n8n v2.12.0 起可用

通过 ID 将 n8n 中的工作流归档。

参数#

名称 类型 必填 描述
workflowId string 要归档的工作流 ID

输出#

字段 类型 描述
archived boolean 工作流是否已归档
workflowId string 已归档工作流的 ID
name string 已归档工作流的名称

备注#

  • 该操作是幂等的,已经归档的工作流会被跳过。

数据表#

search_data_tables#

自 n8n v2.16.0 起可用

搜索当前用户可访问的数据表。可在修改或写入数据之前,先用它查找数据表 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 匹配数据表总数

备注#

  • 最大返回结果数为 100。

create_data_table#

自 n8n v2.16.0 起可用

使用指定列创建新的数据表。

参数#

名称 类型 必填 描述
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#

自 n8n v2.16.0 起可用

向现有数据表中添加新列。

参数#

名称 类型 必填 描述
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#

自 n8n v2.16.0 起可用

重命名数据表中的某一列。

参数#

名称 类型 必填 描述
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#

自 n8n v2.16.0 起可用

从数据表中删除一列。该操作会永久删除该列及其所有数据。

参数#

名称 类型 必填 描述
dataTableId string 包含该列的数据表 ID
projectId string 该数据表所属项目 ID
columnId string 要删除的列 ID

输出#

字段 类型 描述
success boolean 操作是否成功
message string 结果说明

备注#

  • 通过 MCP 删除列后无法撤销。

rename_data_table#

自 n8n v2.16.0 起可用

重命名现有数据表。

参数#

名称 类型 必填 描述
dataTableId string 要重命名的数据表 ID
projectId string 该数据表所属项目 ID
name string 数据表新名称(最少 1 个字符,最多 128 个字符)

输出#

字段 类型 描述
success boolean 操作是否成功
message string 结果说明

备注#

  • 名称在同一项目内必须唯一。

add_data_table_rows#

自 n8n v2.16.0 起可用

向现有数据表插入行。每一行都是一个将列名映射到值的对象。

参数#

名称 类型 必填 描述
dataTableId string 要插入行的数据表 ID
projectId string 该数据表所属项目 ID
rows array 是(最少 1 行,最多 1000 行) 行对象数组。每个对象都会将列名映射到值(stringnumberbooleannull)。

输出#

字段 类型 描述
success boolean 插入操作是否成功
insertedCount integer 成功插入的行数

备注#

  • 每次调用最多插入 1000 行。
  • 行值必须为 stringnumberbooleannull
  • 行对象中的列名必须与数据表中现有列名完全匹配。