跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
搜索与研究

n8n-multi-instance

Use when an n8n-mcp account targets more than one n8n instance — i.e. the `n8n_instances` tool is available, the user mentions multiple n8n instances or environments (prod vs staging, several teams or clients), a workflow / datatable / credential / execution call returns an unexpected NOT_FOUND or reads data you don't recognize, or a credential create/update/delete is refused with an `INSTANCE_AMBIGUOUS` error. Covers choosing and switching which instance this MCP session targets, verifying the target before high-stakes work — credential writes above all — and recovering from misroutes and ambiguous-write fail-closes. Always consult this skill before operating on a specific instance, before any credential create/update/delete on a multi-instance account, or when a call hits the wrong/empty data or an `INSTANCE_AMBIGUOUS` error.

czlonkowski · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add czlonkowski/n8n-skills --skill n8n-multi-instance

技能说明


name: n8n-multi-instance description: Use when an n8n-mcp account targets more than one n8n instance — i.e. the n8n_instances tool is available, the user mentions multiple n8n instances or environments (prod vs staging, several teams or clients), a workflow / datatable / credential / execution call returns an unexpected NOT_FOUND or reads data you don't recognize, or a credential create/update/delete is refused with an INSTANCE_AMBIGUOUS error. Covers choosing and switching which instance this MCP session targets, verifying the target before high-stakes work — credential writes above all — and recovering from misroutes and ambiguous-write fail-closes. Always consult this skill before operating on a specific instance, before any credential create/update/delete on a multi-instance account, or when a call hits the wrong/empty data or an INSTANCE_AMBIGUOUS error.

Working with multiple n8n instances over MCP

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.

Golden rules

Six rules. Each prevents a class of silent misroute.

  1. Discover first. Call n8n_instances({mode:"list"}) before acting so you know the instance names and which one is current.
  2. 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.
  3. 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.
  4. 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.
  5. 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).
  6. 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.

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.

The n8n_instances tool

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.

Error envelope (from the n8n_instances tool)

Every error returns { error: "<CODE>", message, … }. The ones you'll actually hit:

CodeWhenWhat to do
UNKNOWN_INSTANCEname matches no instancePick a name from the available list in the error payload and retry.
NAME_REQUIREDswitch with no nameRe-call with a name (the error lists the valid ones in available).
MULTI_INSTANCE_DISABLEDmulti-instance mode is offThere's nothing to switch; use the n8n tools directly. The user can enable it at the n8n-mcp dashboard.
NO_SESSIONthe request has neither an MCP session id nor a credential idA selection has nowhere to land. Reconnect / initialize a session, then switch.
UNKNOWN_MODEmode wasn't list/switchUse list or switch.
INVALID_CONTEXTserver-side metadata missingA 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.

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

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 / reconn

阅读完整来源 ↗