n8n-multi-instance

通过 MCP 使用多个 n8n 实例

当 n8n_instances 工具可用时，用户已启用多实例模式：一个 MCP 连接可以访问多个 n8n 实例（例如 prod、staging，或为不同客户／团队分别设置的实例）。

有两种方式可以指定调用应发往哪个实例：

• 在调用中指定名称 — 每个 n8n 工具（n8n_get_workflow、n8n_list_workflows、 n8n_update_partial_workflow、n8n_manage_datatable、n8n_manage_credentials、 n8n_executions、n8n_test_workflow、n8n_health_check，等等）都接受可选参数 instance: "<name>"。它只会路由当前这次调用，不会改变其他设置。优先使用此方式。
• 使用 switch 设置默认实例 — n8n_instances({mode:"switch", name}) 会设置未指定实例名称的调用所使用的实例。

默认实例的影响范围比看起来更广。在 claude.ai（以及其他托管连接器）上，一个连接会被使用它的所有聊天和 Agent 共用，因此一个聊天中的 switch 会同时切换其他所有聊天——而它们下一次未指定实例的调用会悄无声息地发往你的实例。目标实例错误时通常不会有明显提示：读取会返回错误的数据，写入则会写到错误的位置。因此，请指定实例名称。

如果没有 n8n_instances 工具，则该账号仅有一个实例：忽略此技能，直接使用 n8n 工具。

可用性。 instance 参数需要托管版 n8n-mcp 后端 0.1.120+ / n8n-mcp 2.94.0+。当 n8n 工具的输入架构中列出 instance 属性（且 n8n_instances 的列表输出包含相关 hint）时，此参数可用。如果未列出，说明服务端版本较旧：请按 切换实例 一节所述，在单独的一轮中使用 switch。

基本规则

1. 先发现实例。 调用 n8n_instances({mode:"list"})，确认准确的实例名称以及哪个实例是 current。绝不要猜测名称。
2. 凡是有影响的调用都指定实例——只要你需要使用多个实例、使用 current 以外的实例，或与同一账号上的其他 Agent／聊天并行工作：n8n_list_workflows({instance:"prod"})。名称不区分大小写。在任务的每次调用中都以相同方式传入名称；无需先进行任何“设置”。
3. 你指定的 instance 绝不会被悄悄替换。 未知名称会触发 INSTANCE_NOT_FOUND 错误，并列出可用的 available 名称——从列表中选择一个并重试。绝不会回退到其他实例。
4. 仅在需要更改默认实例时使用 switch，且仅限你是该连接的唯一使用者。请在单独的一轮中切换——切勿与依赖此切换的调用放在同一并行批次中（批次顺序无法保证）。
5. 写入凭据时：指定实例。 n8n_manage_credentials({action:"create", …, instance:"prod"})。指定实例的写入目标明确，因此绝不会触发 INSTANCE_AMBIGUOUS。先通过 list 核对实例名称——如果指定了错误的实例，机密信息就会写入那里。
6. 意外的 NOT_FOUND 几乎总是实例路由错误，而不是对象已删除。 不要重新创建对象。请将 instance 设置为对象所在的实例后重试（参见“恢复”）。

核心工作流

1. n8n_instances({mode:"list"})                        # names, current, default
2. n8n_list_workflows({instance:"client-a"})            # read on client-a
3. n8n_get_workflow({id:"…", instance:"client-b"})      # read on client-b — no switch needed
4. n8n_update_partial_workflow({id:"…", operations:[…], instance:"client-b"})
5. Credential write:
   n8n_manage_credentials({action:"create", name:"…", type:"…", data:{…}, instance:"client-a"})

每次调用都会指定目标，因此无论其他聊天期间切换到了哪个实例，都不会产生影响；即使目标是不同实例，调用也可以安全地放在同一并行批次中运行。

instance 参数

• 值： n8n_instances list 中的实例名称（available[].name），匹配时不区分大小写。不是 ID，也不是 URL——同一个 URL 可以用多个名称注册。
• 作用范围：仅路由携带该参数的调用。它不会更改 current 或任何人的默认值。
• **省略（或为空）：**调用使用默认实例——此连接上最后一次 switch 的实例，或账户默认实例。
• 失败时关闭，并返回 INSTANCE_NOT_FOUND（调用不会到达 n8n，也不会扣除配额）的情况：
  • 名称与任何实例都不匹配——错误会列出 available；
  • 值不是字符串；
  • 多实例模式已关闭，且该名称不是此连接可访问的唯一实例。

{
  "error": "INSTANCE_NOT_FOUND",
  "message": "No n8n instance named \"clinet-a\". Pass one of the available names as `instance`, …",
  "available": ["client-a", "client-b"]
}

n8n_instances 本身不接受 instance——它有自己的 name 参数供 switch 使用。

n8n_instances 工具

两种模式（必须提供 mode，并会验证其枚举值）：

• {mode:"list"} → { current, default, available, hint }，无副作用。
  • current 和 default 均为单个实例 { id, name, url, isDefault }（或 null）。
  • available 包含所有实例，每个实例额外带有一个 isCurrent 布尔值。按名称匹配；切勿对 id 进行硬编码。
• {mode:"switch", name:"<name>"} → { previous, current }，并设置未指定实例名称的调用所使用的默认实例。name 不区分大小写。

错误封装（来自 n8n_instances 工具）

每个错误都会返回 { error: "<CODE>", message, … }。你实际会遇到的错误如下：

Code	When	What to do
UNKNOWN_INSTANCE	switch 的 name 与任何实例都不匹配	从错误负载中的 available 列表选择一个名称，然后重试。
NAME_REQUIRED	调用 switch 时未提供 name	重新调用并提供 name（错误会在 available 中列出有效名称）。
MULTI_INSTANCE_DISABLED	多实例模式已关闭	无需切换；直接使用 n8n 工具。用户可以在 n8n-mcp 仪表板中启用此模式。
NO_SESSION	请求既没有 MCP 会话 ID，也没有凭据 ID	没有可应用选择的会话。重新连接／初始化会话，然后切换；或者在每次调用时直接指定 instance。
UNKNOWN_MODE	mode 不是 list 或 switch	使用 list 或 switch。
INVALID_CONTEXT	缺少服务端元数据	这是服务端错误，不是你的输入有误——请报告此问题。

实例名称不能是 default、current、list 或 switch（这些名称为保留名称），因此你不会看到名称恰好与模式或字段同名的实例。

INSTANCE_AMBIGUOUS（来自凭据写入路径，而非工具）

调用 n8n_manage_credentials（或执行 n8n_manage_agents 写入操作）时未提供 instance，且该调用继承的默认实例存在歧义时，会返回此错误：此会话从未自行切换实例，却继承了其他位置进行的切换，指向一个非默认实例。为避免将密钥写入错误的实例，服务端会阻止写入（调用不会到达 n8n，也不会扣除配额），并返回：

{
  "error": "INSTANCE_AMBIGUOUS",
  "message": "… the session issuing this request never switched there itself … Re-run n8n_instances({mode:\"switch\", name:\"…\"}) on this session to confirm the target …",
  "lastSelected": { "id": "…", "name": "…" },
  "default":      { "id": "…", "name": "…" }
}

解决方法：确定你实际需要使用哪个实例（lastSelected 是继承的切换实例，default 是账户默认实例），然后使用 instance:"<that name>" 重试写入。（如果服务端不支持 instance 参数，请先在此会话中运行 n8n_instances({mode:"switch", name:"…"})，然后重试。）

目标定位方式（心智模型）

• 指定名称的调用会直接发送到指定实例，不会有其他影响。它是无状态的：既不读取也不更改默认实例。
• 未指定名称的调用会发送到默认实例：此连接上最近一次 switch 指定的实例，否则发送到账号默认实例。
• 默认实例由哪些调用共享取决于客户端。托管连接器（claude.ai，以及任何会将一个聊天分散到多个 MCP 会话的连接器）会为每个连接保留一个默认实例，由该连接上的所有聊天和 Agent 共享。使用稳定 MCP 会话的直连客户端（Claude Code、Cursor）会为每个终端保留一个默认实例，但重新连接后可能会回退到连接上最近一次 switch 指定的实例。无论哪种情况，其他操作都可能更改你的默认实例——这就是规则 2 要求指定实例名称的原因。
• switch 会在重新连接、空闲以及后端部署后继续生效（约 24 小时，即 MCP 会话的生命周期）。
• 不带 instance 的读取和非凭证写入会静默路由到默认实例——路由错误会导致数据错误或返回 NOT_FOUND，而不是报错。
• 如果默认实例被删除（用户在会话中途将其移除），未指定名称的调用会静默回退到账号默认实例——不会报错。对已删除实例的指定名称调用会失败并返回 INSTANCE_NOT_FOUND。

切换（仅在需要更改默认实例时）

当用户要求更改“默认”实例，或使用不支持 instance 参数的旧版服务时，使用 switch。

1. n8n_instances({mode:"switch", name:"prod"})   # its own turn
   → returns { previous, current }; confirm current.name == "prod"
2. (then, in a later turn) the unnamed calls
3. Before a credential write: n8n_instances({mode:"list"}) → re-confirm current, then write

切勿将切换操作与依赖该切换的工作批量执行，并记住，更改会影响所有共享该连接的聊天。

故障恢复手册

症状	通常意味着什么	处理方法
INSTANCE_NOT_FOUND	instance 名称错误（拼写错误、猜测的名称，或实例已被移除）	从错误中的 available 列表选择一个名称并重试。切勿为了“让它运行”而省略 instance——这样会静默地在默认实例上运行。
创建／更新／删除凭证时出现 INSTANCE_AMBIGUOUS	在从未选择目标的会话中进行未指定名称的密钥写入	使用 instance:"<target>" 重试写入（错误中会列出 lastSelected 和 default——选择你需要的实例）。切勿盲目重试。
某个你确定存在的工作流／数据表／凭证返回 NOT_FOUND	当前指向了错误的实例——并不意味着对象已被删除	将 instance 设为对象所在的实例后重试（使用 list 检查名称）。不要重新创建对象。
读取返回空数据或陌生数据	未指定名称的调用发送到了被其他操作更改过的默认实例，或在你的实例被删除后发生了回退	在得出结论之前，使用 instance:"<name>" 重新执行读取。
switch 返回 UNKNOWN_INSTANCE	name 错误	查看错误中的 available 名称，并切换到其中一个名称。
n8n_health_check 报告了你意料之外的 instanceName	未指定名称的调用被发送到了其他位置	在调用中指定实例名称（如果你拥有该连接，也可以使用 switch）。n8n_health_check({instance:"…"}) 可确认名称能否解析。

要确认未指定名称的调用会发送到哪里，请从 n8n_instances({mode:"list"}) 中读取 current（首选方法）。 n8n_health_check 也会在 details.instanceName 下返回已解析的实例，但某些路径（旧版／聊天）中可能不会提供该值，因此请将其作为辅助确认。

凭据操作（风险最高）

凭据中保存着有效机密，而将凭据写入错误位置会导致机密泄露到错误的实例。因此：

• 每次创建、更新或删除凭据时都指定实例： n8n_manage_credentials({action:"create", …, instance:"client-a"})。从 list 获取实例名称——即使指定了名称，写入错误的实例也仍会写入。
• 如果不指定 instance，写入会进入默认实例，而其他聊天可能已更改该默认实例。服务端只会拦截存在歧义的情况（INSTANCE_AMBIGUOUS）；如果有人显式切换实例后，你执行了未命名的写入，写入就会进入对方的实例。
• 凭据读取（action:"list"/"get"/"getSchema"）不会写入机密，但从错误的实例读取会返回错误的架构或列表——读取时也要指定实例。
• 关于 n8n_manage_credentials 工具本身（CRUD 参数结构、通过 getSchema 发现架构，以及绝不将机密直接写入文本字段），请参阅 n8n-mcp-tools-expert。

常见的多实例任务：在实例之间复制内容

若要在实例 B 上重新创建实例 A 中的凭据或工作流：

1. read the source on A:  n8n_get_workflow({id:"…", instance:"A"})
                          (credentials: n8n_manage_credentials({action:"get", id:"…", instance:"A"}))
2. create it on B:        n8n_create_workflow({…, instance:"B"})
                          (credentials: n8n_manage_credentials({action:"create", …, instance:"B"}))
3. verify on B:           n8n_get_workflow({id:"<new id>", instance:"B"})

无需切换实例，因此在读取和写入之间不会有任何操作改变目标实例。n8n 不会返回凭据机密值，所以创建实例 B 上的凭据时，用户需要重新提供这些值。

快速参考

• 查看实例：n8n_instances({mode:"list"}) → { current, default, available, hint }
• 指定单次调用的目标：在任何 n8n 工具调用中添加 instance:"<name>"——优先使用此方式
• 更改未命名调用的默认实例：在单独的一轮中调用 n8n_instances({mode:"switch", name:"<name>"})；此设置由托管连接上的所有聊天共享
• INSTANCE_NOT_FOUND → 使用错误中 available 列表里的名称
• INSTANCE_AMBIGUOUS（未指定实例的凭据写入）→ 使用 instance:"<target>" 重试
• 出现意外的 NOT_FOUND → 使用正确的 instance 重试；不要重新创建
• 工具架构中没有 instance 属性 → 服务端版本较旧：在单独的一轮中执行 switch，并在写入凭据前确认 current

与其他技能的集成

• n8n-mcp-tools-expert — 负责 n8n_manage_credentials（CRUD + getSchema），并规定机密必须通过凭据系统处理，绝不能写入文本字段。本技能在此基础上增加“目标实例是哪一个？”这一层。
• using-n8n-mcp-skills — 路由器；如需了解某个构建步骤由哪个技能负责，请查阅它。