n8n-extending-mcp-official

扩展 n8n 的 MCP 能力

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

1. 封装 MCP 未提供的 n8n 功能。 MCP 支持工作流的 CRUD、验证、执行、数据表、凭据列表、执行搜索、文件夹的创建／重命名／移动和文件夹／项目列表、标签列表以及标签的附加／移除。但以下功能仍未提供：删除文件夹、创建／重命名项目、重命名／删除标签、实例元数据、创建凭据。可以构建一个调用 n8n API 并将结果作为 Agent 工具公开的工作流。
2. 将通用工作流公开为工具。 与 n8n 本身无关的工作流（调用第三方 API、运行内部业务逻辑、在私有系统中查找信息）也可以通过 MCP 调用。这样，Agent 就能在编码会话期间执行实际操作。

MCP 会像调用原生工具一样调用你的工作流：输入来自 Execute Workflow Trigger，输出来自工作流的最后一个节点。

适用场景

情况 1（封装 n8n 功能）：

• 删除文件夹，以及创建／重命名项目：没有 MCP 工具。现在，已注册的实例可以使用 MCP 工具创建／重命名／移动文件夹，以及在文件夹之间移动工作流（create_folder、update_folder、move_workflows_to_folder）；删除文件夹仍需使用 REST API。
• 重命名／删除标签：MCP 可以列出标签（list_workflow_tags），并附加／移除标签（update_workflow 的 addTags／removeTags，会自动创建未知名称），但无法重命名或删除标签实体。REST API 支持这些操作。
• 实例元数据（限制、套餐信息、已配置的集成）：没有 MCP 工具。
• 创建凭据：REST API 支持（POST /credentials），但目前没有 MCP 工具。
• 任何 MCP 未原生提供的 n8n API 操作。

情况 2（通用 Agent 工具）：

• 你希望编写成代码，而不是反复解释的重复性 Agent 任务（查找、格式化、发送）。
• 针对 Agent 无法直接访问的系统执行操作（私有 API、内部服务、第三方集成）。
• 希望未来的会话能够调用，而无需重新推导实现方式的任何功能。

以下情况不适用：

• 一次性问题，直接询问用户。
• MCP 已原生提供的功能。

必须遵守的事项

1. 构建前先询问用户。 这会在用户的实例上创建一个带有凭据的工作流。必须获得用户明确同意。
2. 凭据必须通过凭据配置，不得放在文本字段中。 这是 n8n 中一贯的规则。请参阅 n8n-credentials-and-security-official。

流程

• 先搜索是否已有封装。 使用 search_workflows({ tags: ['tool'] }) 并按功能关键词搜索。如果找到匹配项，就使用它，不要重复创建。
• 对于情况 1，构建无状态且可查询的工具。 接收输入、调用 n8n API 并返回结果。不产生副作用。情况 2 可以有合理的副作用（发送、写入）；请在工具描述中说明。
• 主动提出亲自编辑 Agent 的上下文文件（CLAUDE.md、AGENTS.md、GEMINI.md 或用户的 Agent 在会话开始时读取的其他文件），为新工具添加条目。你有 Edit/Write 工具，因此没有理由让用户手动粘贴代码片段。先询问，因为这是用户的配置文件；用户同意后再直接编辑。

完整流程示例

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 缺少的功能）

以下是最常见的模式，按实用性排序。情况 2（通用 Agent 工具）取决于项目需求，没有统一的示例。

n8n REST API 参考： https://docs.n8n.io/api/api-reference/。封装任何情况 1 功能时，都从这里开始。找到端点后，使用 HTTP Request 节点和 n8nApi 凭据进行封装。可自托管实例可通过 <instance-url>/api/v1/ 访问此 API。

1. 文件夹删除和项目管理

MCP 现在原生支持创建、重命名和移动文件夹（create_folder、update_folder、move_workflows_to_folder），因此这些操作不再需要封装。不过仍缺少删除文件夹，以及创建和重命名项目的功能。n8n 的 REST API 同时支持这两种操作（Folders endpoint），因此只需封装一次即可补足这一缺口。

Tool: delete folder
Input: { projectId: string, folderId: string }
Output: { success: boolean }

2. 实例元数据

版本、已配置的集成、环境信息。这些信息可用于 SessionStart 漂移检查，或根据实例功能调整工作流。

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

Agent 如何调用工具工作流

MCP 不会将每个标记为工具的工作流注册为名称独立的 MCP 工具。 发现和调用分为两个步骤：

1. 发现：通过 search_workflows({ query: '<keyword>' }) 搜索。启用了 MCP 访问权限的工作流会返回 availableInMCP: true。筛选出这类工作流。
2. 调用：通过 execute_workflow({ workflowId, inputs }) 执行。先用 get_workflow_details 查看输入架构。Execute Workflow Trigger 定义了类型化字段。

输出内容取决于工作流最后一个节点的返回值。

MCP 访问权限默认设置： Agent 创建的工作流默认将 availableInMCP: true。UI 创建的工作流可能默认关闭 MCP 访问权限，此时用户必须先在工作流设置中开启 MCP 访问权限，工作流才会出现在搜索结果中。无论哪种情况，用户之后都可以将其关闭以限制访问。

因此，Agent 上下文文件中的代码片段（CLAUDE.md / AGENTS.md / 等）很重要。 后续会话不会自动枚举工具工作流。代码片段会告知它们工具的名称，让它们直接搜索，而不是重新推导实现方式。

反模式

反模式	问题所在	修正方法
未征求用户同意就构建 MCP 扩展工作流	意外在用户的实例上创建带有凭据的工作流	始终先征求许可
未在 Agent 的上下文文件中记录新工具	后续会话不会自动枚举工具工作流。没有提示时，它们会重新推导实现方式。	先征求用户同意，然后直接编辑 CLAUDE.md / AGENTS.md / Agent 读取的相应文件。不要让用户粘贴代码片段。
在 HTTP Request 节点中硬编码 n8n API 令牌	导出或复制工作流时会泄露令牌	使用 n8nApi 类型的凭据或适当的标头身份验证
工具会产生副作用，但名称或描述中未提及	Agent 以为是读取操作而调用，结果却发送了真实消息或写入了真实数据	明确命名并描述副作用（例如，Tool: send Slack message）。对于第 1 类封装，默认采用只读方式更安全。
封装工具执行批量或破坏性操作（归档、删除），却没有试运行模式	一个错误就会影响多个工作流	每次调用都必须明确选择启用，并提供试运行模式，以便列出目标但不执行操作
封装工具返回凭据值	通过工具输出泄露令牌	仅返回 ID、名称和类型。绝不返回密钥。
跳过封装工具的验证、检查和测试流程	工具本身存在问题，表现为令人困惑的“找不到工具”或空响应错误	遵循与任何工作流相同的生命周期：参见 n8n-workflow-lifecycle-official