n8n-extending-mcp

n8n 扩展 MCP

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

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

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

适用场景

情况 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 已原生公开的功能。

必须遵守

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

流程

• 先搜索现有封装。 使用 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/ 访问此接口。

1. 文件夹管理

MCP 可以将工作流放入现有文件夹，但无法创建、重命名、移动或删除文件夹。n8n 的 REST API 提供了文件夹端点，因此，只需封装一次，就能为经常整理文件夹的用户解决这个问题。

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

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、名称和类型。绝不返回机密。
跳过封装的 validate + verify + test 流程	“工具”本身已损坏，表现为令人困惑的找不到工具或空响应错误	遵循与任何工作流相同的生命周期：参见 n8n-workflow-lifecycle