n8n-extending-mcp-official

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

n8n Extending MCP

n8n 扩展MCP

Any n8n workflow with MCP access enabled becomes a tool the coding agent can call by name. Two common cases:

Wrap n8n capabilities the MCP doesn't expose. The MCP covers workflow CRUD, validation, execution, data tables, credential listing, execution search, folder/project listing, tag listing and attach/detach. Still missing: folder CRUD, tag rename/delete, instance metadata, credential creation. Build a workflow that hits the n8n API and exposes the result as an agent tool.
Expose a general-purpose workflow as a tool. A workflow that has nothing to do with n8n itself (calls a third-party API, runs internal business logic, looks something up in a private system) can be MCP-callable. Lets the agent invoke real operations during a coding session.

The MCP calls your workflow as if it were a native tool: input from the

Execute Workflow Trigger

, output from the workflow's last node.

任何启用MCP访问权限的n8n工作流，都可成为编码Agent可按名称调用的工具。常见场景分为两种：

封装MCP未支持的n8n功能。MCP已覆盖工作流CRUD、验证、执行、数据表、凭证列表、执行搜索、文件夹/项目列表、标签列表及附加/移除功能，但仍缺失以下功能：文件夹CRUD、标签重命名/删除、实例元数据、凭证创建。可构建一个调用n8n API的工作流，并将结果暴露为Agent工具。
将通用工作流暴露为工具。与n8n本身无关的工作流（调用第三方API、运行内部业务逻辑、查询私有系统数据等）也可被MCP调用，让Agent在编码会话中触发实际操作。

MCP会像调用原生工具一样调用你的工作流：输入来自

Execute Workflow Trigger

，输出来自工作流的最后一个节点。

When to reach for this

适用场景

Case 1 (wrap n8n capability):

Folder CRUD (create, rename, move, delete): REST API exists, no MCP tool yet.
Tag rename/delete: the MCP lists tags (
```
list_tags
```
) and attaches/detaches them (
```
update_workflow
```
```
addTags
```
/
```
removeTags
```
, auto-creating unknown names), but can't rename or delete tag entities. REST API exists for those.
Instance metadata (limits, plan info, configured integrations): no MCP tool.
Credential creation: REST API exists (
```
POST /credentials
```
), no MCP tool yet.
Any n8n API operation the MCP doesn't natively expose.

Case 2 (general agent tool):

A recurring agent task you'd rather codify than re-explain (lookup, format, send).
An action against a system the agent doesn't have direct access to (private API, internal service, third-party integration).
Anything you want a future session to invoke without re-deriving the implementation.

Don't reach for this for:

One-off questions, ask the user directly.
Things the MCP already exposes natively.

场景1（封装n8n功能）：

文件夹CRUD（创建、重命名、移动、删除）：REST API已存在，但暂无对应的MCP工具。
标签重命名/删除：MCP支持列出标签（
```
list_tags
```
）及附加/移除标签（
```
update_workflow
```
的
```
addTags
```
/
```
removeTags
```
，可自动创建未知名称的标签），但无法重命名或删除标签实体。这些功能可通过REST API实现。
实例元数据（限制、套餐信息、已配置集成）：暂无对应的MCP工具。
凭证创建：REST API已存在（
```
POST /credentials
```
），但暂无对应的MCP工具。
任何MCP未原生支持的n8n API操作。

场景2（通用Agent工具）：

重复出现的Agent任务，你更希望将其编码实现而非反复解释（查询、格式化、发送等）。
针对Agent无直接访问权限的系统执行操作（私有API、内部服务、第三方集成）。
希望未来会话可直接触发、无需重新推导实现逻辑的任何操作。

不适用场景：

一次性问题，直接询问用户即可。
MCP已原生支持的功能。

Non-negotiables

必须遵守的规则

Ask the user before building. This creates a workflow on their instance, with credentials. They need to OK it explicitly.
Credentials via credential, never text field. Same rule as everywhere else in n8n. See
```
n8n-credentials-and-security-official
```
.

构建前需征得用户同意。这会在用户的实例上创建带凭证的工作流，必须获得用户明确许可。
通过凭证组件而非文本字段存储凭证。与n8n其他场景的规则一致，详见
```
n8n-credentials-and-security-official
```
。

Protocol

流程规范

Search for existing wrappers first.
```
search_workflows({ tags: ['tool'] })
```
and a capability keyword search. If something matches, use it instead of duplicating.
For case 1, build as a stateless, queryable utility. Takes input, calls n8n's API, returns the result. No side effects. Case 2 may legitimately have side effects (sending, writing); name them in the tool description.
Offer to edit the agent's context file yourself (CLAUDE.md, AGENTS.md, GEMINI.md, whatever the user's agent reads on session start) to add an entry for the new tool. You have Edit/Write tools, so there's no reason to make the user paste a snippet manually. Ask first since it's their config file, then edit it directly when they say yes.

先搜索现有封装工具。调用
```
search_workflows({ tags: ['tool'] })
```
并结合功能关键词搜索。若存在匹配工具，直接使用而非重复构建。
场景1需构建为无状态、可查询的实用工具。接收输入，调用n8n API，返回结果，无副作用。场景2可合理存在副作用（发送、写入等），但需在工具描述中明确说明。
主动提出帮用户编辑Agent上下文文件（CLAUDE.md、AGENTS.md、GEMINI.md等用户Agent会话启动时读取的文件），添加新工具的条目。你拥有编辑/写入工具，无需让用户手动粘贴代码片段。先征得用户同意，再直接编辑文件。

The pattern, end to end

完整实现流程

1. User asks for a capability (missing MCP feature, or a workflow they want
   the agent to be able to invoke).
2. You: "I can build a workflow that exposes this as a tool the MCP can call.
   Want me to create it?"
3. User: yes.
4. You build the workflow:
   - Trigger: Execute Workflow Trigger with declared inputs.
   - Body: whatever logic the tool needs (HTTP Request to n8n's API, a
     third-party call, internal computation).
   - Output: structured response.
5. Validate, test, publish.
6. Ask the user if you can add an entry for this tool to their agent context
   file (CLAUDE.md / AGENTS.md / etc.) so future sessions know to search for
   it by name. Edit the file directly when they say yes.
7. The workflow is immediately callable: agent-created workflows have `availableInMCP: true` set by default.

1. 用户提出需求（缺失的MCP功能，或希望Agent能触发的工作流）。
2. 你："我可以构建一个工作流，将该功能暴露为MCP可调用的工具。需要我创建吗？"
3. 用户：同意。
4. 你构建工作流：
   - 触发器：使用声明了输入的Execute Workflow Trigger。
   - 主体：实现工具所需的逻辑（调用n8n API的HTTP请求、第三方调用、内部计算等）。
   - 输出：结构化响应。
5. 验证、测试、发布。
6. 询问用户是否可将该工具条目添加到其Agent上下文文件（CLAUDE.md / AGENTS.md / 其他文件），以便未来会话可按名称搜索到该工具。用户同意后直接编辑文件。
7. 工作流可立即被调用：Agent创建的工作流默认设置`availableInMCP: true`。

Common case-1 wrappers (missing MCP capabilities)

常见场景1封装工具（缺失的MCP功能）

Most common patterns, by usefulness. Case 2 (general agent tools) is whatever your project needs, no canonical examples.

n8n REST API reference: https://docs.n8n.io/api/api-reference/. Start here for any case-1 wrap. Find the endpoint, then wrap it with an HTTP Request node +
n8nApi
credential. Self-hosted instances expose this at
<instance-url>/api/v1/
.

按实用性排序的最常见模式。场景2（通用Agent工具）则根据项目需求而定，无标准示例。

n8n REST API参考文档： https://docs.n8n.io/api/api-reference/。构建场景1封装工具时请先查阅此处。找到对应端点后，使用HTTP Request节点 +
n8nApi
凭证进行封装。自托管实例的API地址为
<instance-url>/api/v1/
。

1. Folder management

1. 文件夹管理

The MCP can place workflows into existing folders but can't create, rename, move, or delete them. n8n's REST API has a Folders endpoint, so a one-time wrap solves this for users who organize folders frequently.

Tool: create folder
Input: { projectId: string, name: string, parentFolderId?: string }
Output: { id, name, projectId, parentFolderId? }

MCP可将工作流放入现有文件夹，但无法创建、重命名、移动或删除文件夹。n8n的REST API提供了文件夹端点，一次性封装即可满足频繁整理文件夹的用户需求。

工具：创建文件夹
输入：{ projectId: string, name: string, parentFolderId?: string }
输出：{ id, name, projectId, parentFolderId? }

2. Instance metadata

2. 实例元数据

Version, configured integrations, environment info. Useful for the SessionStart drift check or adapting workflows to instance capabilities.

Tool: get instance info
Input: {}
Output: { version, edition, integrations: [...], limits: {...} }

版本信息、已配置集成、环境信息。可用于会话启动时的差异检查，或根据实例能力调整工作流。

工具：获取实例信息
输入：{}
输出：{ version, edition, integrations: [...], limits: {...} }

How the agent invokes a tool workflow

Agent如何调用工具工作流

The MCP doesn't register each tool-flagged workflow as a separately-named MCP tool. Discovery and invocation are two steps:

Discover via
```
search_workflows({ query: '<keyword>' })
```
. Workflows with MCP access on return
```
availableInMCP: true
```
. Filter for that.

Invoke via

execute_workflow({ workflowId, inputs })

. Read the input schema first with

get_workflow_details

. The

Execute Workflow Trigger

defines typed fields.

Output is whatever the workflow's last node returns.

MCP access defaults: Agent-created workflows default to

availableInMCP: true

. UI-created workflows may default off, in which case the user has to toggle MCP access on in the workflow's settings before it appears in search results. Either way, the user can flip it off later to restrict access.

This is why the agent-context-file snippet (CLAUDE.md / AGENTS.md / etc.) matters. Future sessions don't auto-enumerate tool workflows. The snippet tells them the tool exists by name, so they search for it instead of re-deriving the implementation.

MCP 不会将每个标记为工具的工作流注册为单独命名的MCP工具。发现与调用分为两步：

发现：调用
```
search_workflows({ query: '<keyword>' })
```
。启用MCP访问的工作流会返回
```
availableInMCP: true
```
，可据此过滤。

调用：调用

execute_workflow({ workflowId, inputs })

。需先通过

get_workflow_details

读取输入 schema，

Execute Workflow Trigger

定义了类型化字段。

输出为工作流最后一个节点返回的内容。

MCP访问权限默认设置： Agent创建的工作流默认

availableInMCP: true

。UI创建的工作流默认关闭该权限，用户需在工作流设置中手动开启MCP访问权限，才能在搜索结果中显示。无论哪种情况，用户后续都可关闭该权限以限制访问。

这就是Agent上下文文件片段（CLAUDE.md / AGENTS.md / 其他文件）重要的原因。未来会话不会自动枚举工具工作流，片段会告知Agent该工具的名称，使其可直接搜索而非重新推导实现逻辑。

Anti-patterns

反模式

Anti-pattern	What goes wrong	Fix
Building an MCP-extension workflow without asking the user	Surprise creation of workflows on their instance with credentials	Always ask permission first
Not documenting the new tool in the agent's context file	Future sessions don't auto-enumerate tool workflows. Without a hint they'll re-derive the implementation.	Ask the user, then edit CLAUDE.md / AGENTS.md / whichever file their agent reads, directly. Don't make them paste a snippet.
Hardcoding the n8n API token in the HTTP Request node	Token leak when the workflow is exported or copied	Use a credential of type `n8nApi` or appropriate header auth
Side-effecting tool with no mention of side effects in its name/description	Agent invokes thinking it's a read, ends up sending real messages or writing real data	Name and describe the side effect explicitly (e.g., `Tool: send Slack message` ). Read-only is the safer default for case-1 wrappers.
Wrapper that does bulk or destructive ops (archive, delete) with no dry-run	One bug touches many workflows	Strong explicit opt-in per call, plus a dry-run mode that lists targets without acting
Wrapper returns credential values	Token leak via tool output	Return IDs, names, types only. Never the secret.
Skipping the validate + verify + test cycle on the wrapper	The "tool" itself is broken, manifests as confusing tool-not-found or empty-response errors	Same lifecycle as any workflow: see `n8n-workflow-lifecycle-official`

反模式	问题	修复方案
未征得用户同意就构建MCP扩展工作流	在用户实例上意外创建带凭证的工作流	始终先征得用户许可
未在Agent上下文文件中记录新工具	未来会话不会自动枚举工具工作流，若无提示会重新推导实现逻辑	询问用户后，直接编辑CLAUDE.md / AGENTS.md / 其他Agent读取的文件，无需让用户粘贴代码片段
在HTTP Request节点中硬编码n8n API令牌	导出或复制工作流时会泄露令牌	使用 `n8nApi` 类型的凭证或合适的头部认证
有副作用的工具未在名称/描述中提及副作用	Agent以为是只读操作，实际却发送真实消息或写入真实数据	在名称和描述中明确说明副作用（例如： `工具：发送Slack消息` ）。场景1封装工具默认使用只读模式更安全
封装批量或破坏性操作（归档、删除）的工具无试运行模式	一个bug可能影响多个工作流	每次调用需明确确认，且添加试运行模式，仅列出目标对象而不执行操作
封装工具返回凭证值	通过工具输出泄露令牌	仅返回ID、名称、类型，绝不返回密钥
跳过封装工具的验证+确认+测试流程	“工具”本身存在问题，表现为令人困惑的工具未找到或空响应错误	遵循与其他工作流相同的生命周期：详见 `n8n-workflow-lifecycle-official`