n8n-multi-instance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Working with multiple n8n instances over MCP

通过MCP管理多个n8n实例

When the

n8n_instances

tool is available, the user has multi-instance mode on: one MCP connection can reach several n8n instances (e.g.

prod

staging

, or one per client/team). Every other n8n tool (

n8n_get_workflow

n8n_list_workflows

n8n_update_partial_workflow

n8n_manage_datatable

n8n_manage_credentials

n8n_executions

n8n_test_workflow

, …) runs against whichever instance this session is currently targeting. There is no per-call instance argument: you change the target only by switching. Target the wrong instance and a read returns the wrong data and a write lands in the wrong place — usually with no error (the one exception is an ambiguous credential write, which fails closed; see below). So target deliberately.

If the

n8n_instances

tool is not present, the account is single-instance: ignore this skill and use the n8n tools directly.

当

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_instances

工具不可用，则该账户为单实例模式：忽略本技能，直接使用n8n工具即可。

Golden rules

黄金准则

Six rules. Each prevents a class of silent misroute.

Discover first. Call
```
n8n_instances({mode:"list"})
```
before acting so you know the instance names and which one is
```
current
```
.
Switch by name to your target before doing work on a non-default instance:
```
n8n_instances({mode:"switch", name:"<instance name>"})
```
. The match is case-insensitive.
Switch in its own turn. Never put a
```
switch
```
and a dependent operation in the same parallel tool-call batch. Calls in one batch have no guaranteed order, so the dependent call can be resolved against the previous instance before the switch's session state is visible. Switch, let it return, then operate.
Verify before high-stakes ops. Immediately before creating/updating/deleting credentials (and before destructive workflow edits), confirm
```
current
```
is the instance you intend — primary check is
```
n8n_instances({mode:"list"})
```
. The system fail-closes only the ambiguous credential case (rule 6); an explicit switch to the wrong instance still writes there silently, so this check is on you.
An unexpected
NOT_FOUND
is almost always a wrong-instance misroute, not a deletion. Don't recreate the object. Re-check the current instance and retry (see Recovery).
On
INSTANCE_AMBIGUOUS
, switch on this session, then retry. The system is refusing to write a secret because this session never picked a target itself. Comply — run
```
switch
```
here to confirm the instance, then retry the write. Don't work around it or retry blindly.

六条准则，每条都能避免一类静默路由错误。

先发现。在执行操作前调用
```
n8n_instances({mode:"list"})
```
，了解实例名称以及当前
```
current
```
指向的实例。
切换到目标实例：在非默认实例上执行操作前，调用
```
n8n_instances({mode:"switch", name:"<instance name>"})
```
切换到目标实例。名称匹配不区分大小写。
单独执行切换。不要将
```
switch
```
操作和依赖操作放在同一个并行工具调用批次中。同一批次中的调用没有固定顺序，因此依赖操作可能在切换的会话状态生效前，就基于之前的实例执行了。先切换，等待返回结果，再执行操作。
高风险操作前验证。在创建/更新/删除凭据（以及执行破坏性工作流编辑）前，立即确认
```
current
```
是你想要的实例——主要通过
```
n8n_instances({mode:"list"})
```
检查。系统仅会在模糊凭据场景（准则6）下触发失败关闭；如果明确切换到错误实例，写入操作仍会静默执行，因此需要你自行检查。
意外的NOT_FOUND几乎总是路由到错误实例导致的，而非对象被删除。不要重新创建对象。重新检查当前实例并重试（参见恢复指南）。
遇到
INSTANCE_AMBIGUOUS
错误时，在当前会话切换实例，然后重试。系统拒绝写入机密信息，因为当前会话从未自行选择目标实例。请执行切换——调用
```
switch
```
确认实例，然后重试写入操作。不要试图绕过或盲目重试。

Core workflow

核心工作流

1. n8n_instances({mode:"list"})                      # see available[] + current + default
2. n8n_instances({mode:"switch", name:"prod"})       # bind THIS session to "prod"
   → returns { previous, current }; confirm current.name == "prod"
3. (do your work) n8n_list_workflows / n8n_get_workflow / n8n_manage_datatable / ...
4. Before a credential write or a delete:
   n8n_instances({mode:"list"})  → re-confirm current, THEN n8n_manage_credentials({action:"create", ...})

To move to another instance, just

switch

again. The whole session follows the switch.

1. n8n_instances({mode:"list"})                      # 查看available[] + current + default
2. n8n_instances({mode:"switch", name:"prod"})       # 将当前会话绑定到"prod"
   → 返回{ previous, current }; 确认current.name == "prod"
3. (执行你的操作) n8n_list_workflows / n8n_get_workflow / n8n_manage_datatable / ...
4. 在执行凭据写入或删除操作前：
   n8n_instances({mode:"list"})  → 重新确认current，然后执行n8n_manage_credentials({action:"create", ...})

要切换到另一个实例，只需再次调用

switch

。整个会话会跟随切换后的实例。

The

n8n_instances

tool

n8n_instances

工具

Two modes (

mode

is required and enum-validated):

```
{mode:"list"}
```
→
```
{ current, default, available }
```
, no side effects.
- ```
current
```
  and
```
default
```
  are each one instance
```
{ id, name, url, isDefault }
```
  (or
```
null
```
  ).
- ```
available
```
  is every instance, each with an extra
```
isCurrent
```
  boolean. Match by name
  ; never hard-code
```
id
```
  .
```
{mode:"switch", name:"<name>"}
```
→
```
{ previous, current }
```
, and binds this session to the named instance.
```
name
```
is case-insensitive.

两种模式（

mode

为必填项，且为枚举值）：

```
{mode:"list"}
```
→ 返回
```
{ current, default, available }
```
，无副作用。
- ```
current
```
  和
```
default
```
  分别为单个实例对象
```
{ id, name, url, isDefault }
```
  （或
```
null
```
  ）。
- ```
available
```
  包含所有实例，每个实例额外带有
```
isCurrent
```
  布尔值。请通过**
```
name
```
  **匹配实例；切勿硬编码
```
id
```
  。
```
{mode:"switch", name:"<name>"}
```
→ 返回
```
{ previous, current }
```
，并将当前会话绑定到指定名称的实例。
```
name
```
不区分大小写。

Error envelope (from the

n8n_instances

tool)

错误信息（来自

n8n_instances

工具）

Every error returns

{ error: "<CODE>", message, … }

. The ones you'll actually hit:

Code	When	What to do
`UNKNOWN_INSTANCE`	`name` matches no instance	Pick a name from the `available` list in the error payload and retry.
`NAME_REQUIRED`	`switch` with no `name`	Re-call with a `name` (the error lists the valid ones in `available` ).
`MULTI_INSTANCE_DISABLED`	multi-instance mode is off	There's nothing to switch; use the n8n tools directly. The user can enable it at the n8n-mcp dashboard.
`NO_SESSION`	the request has neither an MCP session id nor a credential id	A selection has nowhere to land. Reconnect / initialize a session, then switch.
`UNKNOWN_MODE`	`mode` wasn't `list` / `switch`	Use `list` or `switch` .
`INVALID_CONTEXT`	server-side metadata missing	A server bug, not your input — report it.

Instance names can never be
default
,
current
,
list
, or
switch
(reserved), so you'll never see an instance literally named after a mode or field.

所有错误都会返回

{ error: "<CODE>", message, … }

。你实际会遇到的错误如下：

代码	触发场景	解决方法
`UNKNOWN_INSTANCE`	`name` 未匹配到任何实例	从错误返回的 `available` 列表中选择一个名称并重试。
`NAME_REQUIRED`	调用 `switch` 时未提供 `name`	重新调用并传入 `name` （错误信息中会列出有效的名称）。
`MULTI_INSTANCE_DISABLED`	多实例模式已关闭	无需切换；直接使用n8n工具即可。用户可在n8n-mcp控制台启用多实例模式。
`NO_SESSION`	请求既无MCP会话ID也无凭据ID	无法完成选择。重新连接/初始化会话，然后执行切换。
`UNKNOWN_MODE`	`mode` 不是 `list` / `switch`	使用 `list` 或 `switch` 模式。
`INVALID_CONTEXT`	服务器端元数据缺失	属于服务器Bug，与你的输入无关——请上报。

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

INSTANCE_AMBIGUOUS

(from the credential-write path, not the tool)

INSTANCE_AMBIGUOUS

（来自凭据写入流程，而非工具本身）

A separate, higher-stakes error. It is not returned by

n8n_instances

— it's returned by the server when you call

n8n_manage_credentials

to create/update/delete a credential and the target instance is ambiguous: this session never switched on its own but inherited a switch made elsewhere (a fan-out / reconnect), pointing at a non-default instance. Rather than risk writing a secret to the wrong instance, the server blocks the write (it never reaches n8n, no quota is charged) and returns:

json

{
  "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": "…" }
}

Fix: decide which instance you actually want (

lastSelected

is the inherited switch,

default

is the account default), run

n8n_instances({mode:"switch", name:"…"})

on this session, then retry the write. See rule 6.

这是一种独立的高风险错误。它不是由

n8n_instances

返回的——而是当你调用

n8n_manage_credentials

来创建/更新/删除凭据，且目标实例不明确时，由服务器返回：当前会话从未自行切换实例，而是继承了其他地方设置的切换（例如扇出/重新连接），指向非默认实例。为避免将机密信息写入错误实例，服务器会阻止写入（请求不会到达n8n，也不会消耗配额），并返回：

json

{
  "error": "INSTANCE_AMBIGUOUS",
  "message": "… 发起此请求的会话从未自行切换到该实例 … 请在当前会话重新调用n8n_instances({mode:\"switch\", name:\"…\"})以确认目标实例 …",
  "lastSelected": { "id": "…", "name": "…" },
  "default":      { "id": "…", "name": "…" }
}

修复方法：确定你实际想要的实例（

lastSelected

是继承的切换目标，

default

是账户默认实例），在当前会话调用

n8n_instances({mode:"switch", name:"…"})

，然后重试写入操作。参见准则6。

How targeting behaves (mental model)

目标实例的行为逻辑（心智模型）

A
```
switch
```
binds this session to the chosen instance. The binding persists for the rest of the session and survives reconnects, idle, and backend deploys (~24h, the MCP session lifetime) — you should not need to re-switch before every call.
Other sessions / terminals are independent: switching here does not move them.
One session targets one instance at a time. There is no per-call instance argument; you change the target only via
```
switch
```
.
Reads and non-credential writes route to the currently-selected instance, silently — a misroute produces wrong data or a
```
NOT_FOUND
```
, not an error.
Credential writes are the one guarded case. They route the same way, except the server fail-closes the ambiguous state (a session that never switched, recovered onto a non-default instance) with
```
INSTANCE_AMBIGUOUS
```
. This is a safety net, not a substitute for rule 4: an explicit switch to the wrong instance still writes there.
If your selected instance is deleted (the user removes it mid-session), the next call silently falls back to your default instance — no error. So default's data appearing where you expected another instance's can look like "my data vanished." Re-list to see where you are.

```
switch
```
操作会绑定当前会话到所选实例。该绑定会在会话剩余时间内持续生效，即使重新连接、闲置或后端部署（MCP会话生命周期约24小时）——你无需在每次调用前重新切换。
其他会话/终端是独立的：当前会话切换实例不会影响它们。
一个会话同一时间只能指向一个实例。没有针对单次调用的实例参数；只能通过
```
switch
```
更改目标实例。
读取操作和非凭据写入操作会静默路由到当前选中的实例——路由错误会导致返回错误数据或NOT_FOUND，不会触发错误。
凭据写入是唯一受保护的场景。它们的路由方式相同，但服务器会在模糊状态下触发失败关闭（会话从未切换实例，恢复后指向非默认实例），返回
```
INSTANCE_AMBIGUOUS
```
错误。这只是一个安全网，不能替代准则4：如果明确切换到错误实例，写入操作仍会执行。
如果选中的实例被删除（用户在会话中途移除实例），下一次调用会静默回退到默认实例——不会报错。因此，当你预期看到其他实例的数据，却出现默认实例的数据时，可能会误以为“我的数据消失了”。请重新调用list查看当前指向的实例。

Recovery playbook

恢复指南

Symptom	What it usually means	Do this
`INSTANCE_AMBIGUOUS` on a credential create/update/delete	This session never switched itself; the system won't guess which instance to write the secret to	Run `n8n_instances({mode:"switch", name:"<target>"})` on this session (the error names `lastSelected` and `default` — pick the one you want), then retry the write. Never retry blindly.
`NOT_FOUND` for a workflow/datatable/credential you know exists	You're pointed at the wrong instance — not that it was deleted	`n8n_instances({mode:"list"})` → check `current` . If it's not your target, `switch` and retry. Do not recreate the object.
A read returns empty or unfamiliar data	Wrong-instance read, or a silent fallback to `default` after your instance was deleted	`n8n_instances({mode:"list"})` , confirm `current` , switch if needed, re-read before drawing conclusions.
`UNKNOWN_INSTANCE` on `switch`	The `name` is wrong (typo, or you guessed)	Read the `available` names in the error and switch to one of those. Names are case-insensitive.
`n8n_health_check` reports an `instanceName` you didn't expect	This session is on a different instance than you think	`switch` to the intended instance, then proceed.
Repeated misroutes within one turn	You batched a `switch` with dependent work	Split them: `switch` alone, await the result, then operate one logical step at a time.

After any recovery switch, sanity-check with

n8n_instances({mode:"list"})

(read

current

) as the primary signal.

n8n_health_check

also returns the resolved instance under

details.instanceName

, but it can be absent on some paths (legacy/chat), so treat it as a secondary confirmation.

症状	通常原因	解决方法
凭据创建/更新/删除时返回 `INSTANCE_AMBIGUOUS`	当前会话从未自行切换实例；系统无法猜测应将机密信息写入哪个实例	在当前会话调用 `n8n_instances({mode:"switch", name:"<target>"})` （错误信息中会列出 `lastSelected` 和 `default` ——选择你需要的实例），然后重试写入操作。切勿盲目重试。
你确定存在的工作流/数据表/凭据返回NOT_FOUND	你指向了错误的实例——不是对象被删除	调用 `n8n_instances({mode:"list"})` → 检查 `current` 。如果不是目标实例，切换后重试。不要重新创建对象。
读取操作返回空数据或陌生数据	路由到错误实例，或所选实例被删除后静默回退到 `default`	调用 `n8n_instances({mode:"list"})` ，确认 `current` ，必要时切换实例，重新读取后再下结论。
调用 `switch` 时返回 `UNKNOWN_INSTANCE`	`name` 错误（拼写错误或猜测的名称）	查看错误信息中的 `available` 名称，切换到其中一个。名称不区分大小写。
`n8n_health_check` 返回的 `instanceName` 不符合预期	当前会话指向的实例与你认为的不同	切换到目标实例，然后继续操作。
同一轮操作中反复出现路由错误	你将 `switch` 操作和依赖操作放在了同一个批次中	拆分操作：单独执行 `switch` ，等待结果返回，然后逐个执行逻辑步骤。

在任何恢复切换后，请通过

n8n_instances({mode:"list"})

（查看

current

）进行 sanity 检查，这是主要信号。

n8n_health_check

也会在

details.instanceName

下返回解析后的实例，但在某些路径（旧版/聊天）中可能缺失，因此将其视为次要确认方式。

Credential operations (highest stakes)

凭据操作（最高风险）

Credentials hold live secrets, and a misrouted credential write puts a secret on the wrong instance. The server protects the ambiguous case automatically — if this session never picked a target and inherited a switch to a non-default instance, the write fails closed with

INSTANCE_AMBIGUOUS

(rule 6) and never reaches n8n. But that net is narrow: a credential write on a session that did switch goes through to whatever instance it switched to, with no second guess. So:

Verify
current
immediately before
```
n8n_manage_credentials
```
create/update/delete — call
```
n8n_instances({mode:"list"})
```
in the same short sequence, not 10 steps earlier where a later switch could have moved you.
On
INSTANCE_AMBIGUOUS
, switch on this session to confirm the target, then retry — don't work around it.
Credential reads (
```
action:"list"
```
/
```
"get"
```
/
```
"getSchema"
```
) are not gated and don't write a secret, but a read off the wrong instance returns the wrong schema or list — so still verify
```
current
```
if the result looks wrong.
For the
```
n8n_manage_credentials
```
tool itself (CRUD shapes,
```
getSchema
```
discovery, never inlining secrets into text fields), see
```
n8n-mcp-tools-expert
```
.

凭据包含实时机密信息，路由错误的凭据写入会将机密信息放到错误的实例上。服务器会自动保护模糊场景——如果当前会话从未选择目标实例，而是继承了指向非默认实例的切换，写入操作会触发

INSTANCE_AMBIGUOUS

错误并失败关闭（准则6），且不会到达n8n。但这个安全网的范围很窄：如果会话已经切换实例，凭据写入会直接发送到切换后的实例，不会再次确认。因此：

在执行
n8n_manage_credentials
创建/更新/删除操作前，立即验证
current
——在同一个短序列中调用
```
n8n_instances({mode:"list"})
```
，不要在10步前检查，因为后续的切换可能已经更改了目标实例。
遇到
INSTANCE_AMBIGUOUS
错误时，在当前会话切换实例以确认目标，然后重试——不要试图绕过。
凭据读取操作（
```
action:"list"
```
/
```
"get"
```
/
```
"getSchema"
```
）不受限制，也不会写入机密信息，但如果路由到错误实例，会返回错误的架构或列表——因此如果结果不符合预期，仍需验证
```
current
```
。
关于
```
n8n_manage_credentials
```
工具本身（CRUD结构、
```
getSchema
```
发现、切勿将机密信息内联到文本字段），请参考
```
n8n-mcp-tools-expert
```
。

Common multi-instance task: copy something between instances

常见多实例任务：在实例间复制对象

To recreate a credential or workflow from instance A on instance B:

1. switch → A;  read the source (n8n_manage_credentials get / n8n_get_workflow)
2. switch → B   (its own call — never batched with the create below)
3. n8n_instances({mode:"list"})  → confirm current == B
4. create on B  (n8n_manage_credentials create / n8n_create_workflow)

Do each instance's steps in its own turn; never overlap

switch → B

with the create-on-B call (rule 3), and switch explicitly on this session before the credential write so it isn't ambiguous (rules 4 and 6).

要将实例A上的凭据或工作流复制到实例B：

1. 切换到实例A；读取源对象（n8n_manage_credentials get / n8n_get_workflow）
2. 切换到实例B   (单独调用——切勿与后续的创建操作放在同一个批次)
3. n8n_instances({mode:"list"})  → 确认current == B
4. 在实例B上创建对象  (n8n_manage_credentials create / n8n_create_workflow)

每个实例的步骤要单独执行；切勿将

switch → B

与在B上创建对象的操作重叠（准则3），并且在凭据写入前要在当前会话明确切换实例，避免出现模糊状态（准则4和6）。

Quick reference

快速参考

See instances + where you are:

n8n_instances({mode:"list"})

→

{ current, default, available }

Change target:

n8n_instances({mode:"switch", name:"<name>"})

— its own turn, then operate

Confirm target:
```
current
```
from
```
list
```
(primary);
```
details.instanceName
```
from
```
n8n_health_check
```
(secondary, may be absent)
```
UNKNOWN_INSTANCE
```
→ switch to a name from the error's
```
available
```
list, then retry
```
INSTANCE_AMBIGUOUS
```
(credential write) →
```
switch
```
on this session to confirm the target, then retry
Unexpected
```
NOT_FOUND
```
→ verify the instance, switch, retry; do not recreate
Before credential writes → re-
```
list
```
, confirm
```
current
```
, then write (the fail-close only covers the ambiguous case)

查看实例及当前指向：

n8n_instances({mode:"list"})

→ 返回

{ current, default, available }

更改目标实例：
```
n8n_instances({mode:"switch", name:"<name>"})
```
——单独执行，然后再操作
确认目标实例：
```
list
```
返回的
```
current
```
（主要方式）；
```
n8n_health_check
```
返回的
```
details.instanceName
```
（次要方式，可能缺失）
```
UNKNOWN_INSTANCE
```
→ 切换到错误信息中
```
available
```
列表里的名称，然后重试
```
INSTANCE_AMBIGUOUS
```
（凭据写入）→ 在当前会话切换实例确认目标，然后重试
意外的NOT_FOUND → 验证实例，切换后重试；不要重新创建对象
凭据写入前 → 重新调用
```
list
```
，确认
```
current
```
，然后执行写入操作（失败关闭仅覆盖模糊场景）

Integration with other skills

与其他技能的集成

n8n-mcp-tools-expert — owns
```
n8n_manage_credentials
```
(CRUD +
```
getSchema
```
) and the rule that secrets go through the credential system, never text fields. This skill adds the "which instance?" layer on top.
using-n8n-mcp-skills — the router; consult it for which skill owns a given build step.

n8n-mcp-tools-expert —— 负责
```
n8n_manage_credentials
```
（CRUD +
```
getSchema
```
）以及机密信息必须通过凭据系统处理、切勿放入文本字段的规则。本技能在此基础上增加了“选择哪个实例？”的层面。
using-n8n-mcp-skills —— 路由技能；如需了解哪个技能负责特定构建步骤，请参考该技能。

n8n-multi-instance

Original

Translation

Working with multiple n8n instances over MCP

通过MCP管理多个n8n实例

Golden rules

黄金准则

Core workflow

核心工作流

The
`n8n_instances`
tool

`n8n_instances`
工具

Error envelope (from the
`n8n_instances`
tool)

错误信息（来自
`n8n_instances`
工具）

`INSTANCE_AMBIGUOUS`
(from the credential-write path, not the tool)

`INSTANCE_AMBIGUOUS`
（来自凭据写入流程，而非工具本身）

How targeting behaves (mental model)

目标实例的行为逻辑（心智模型）

Recovery playbook

恢复指南

Credential operations (highest stakes)

凭据操作（最高风险）

Common multi-instance task: copy something between instances

常见多实例任务：在实例间复制对象

Quick reference

快速参考

Integration with other skills

与其他技能的集成

n8n-multi-instance

Original

Translation

Working with multiple n8n instances over MCP

通过MCP管理多个n8n实例

Golden rules

黄金准则

Core workflow

核心工作流

The n8n_instances tool

n8n_instances工具

Error envelope (from the n8n_instances tool)

错误信息（来自n8n_instances工具）

INSTANCE_AMBIGUOUS (from the credential-write path, not the tool)

INSTANCE_AMBIGUOUS（来自凭据写入流程，而非工具本身）

How targeting behaves (mental model)

目标实例的行为逻辑（心智模型）

Recovery playbook

恢复指南

Credential operations (highest stakes)

凭据操作（最高风险）

Common multi-instance task: copy something between instances

常见多实例任务：在实例间复制对象

Quick reference

快速参考

Integration with other skills

与其他技能的集成

The
`n8n_instances`
tool

`n8n_instances`
工具

Error envelope (from the
`n8n_instances`
tool)

错误信息（来自
`n8n_instances`
工具）

`INSTANCE_AMBIGUOUS`
(from the credential-write path, not the tool)

`INSTANCE_AMBIGUOUS`
（来自凭据写入流程，而非工具本身）