# N8n Multi Instance

Use when an n8n-mcp account targets more than one n8n instance, i.e.

- Repository: https://github.com/czlonkowski/n8n-skills (6563 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-24
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add czlonkowski/n8n-skills --skill n8n-multi-instance -g -a claude-code -y`
Codex: `npx skills add czlonkowski/n8n-skills --skill n8n-multi-instance -g -a codex -y`
Cursor: `npx skills add czlonkowski/n8n-skills --skill n8n-multi-instance -g -a cursor -y`
Gemini CLI: `npx skills add czlonkowski/n8n-skills --skill n8n-multi-instance -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add czlonkowski/n8n-skills`

## 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), several agents or chats work on one account in parallel, a workflow / datatable / credential / execution call returns an unexpected NOT_FOUND or reads data you don't recognize, or a call is refused with `INSTANCE_AMBIGUOUS` or `INSTANCE_NOT_FOUND`. Covers naming the target instance on each call with the `instance` argument, setting the default with `switch`, verifying the target before high-stakes work, credential writes above all, and recovering from misroutes and 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 error.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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).

There are two ways to say which instance a call should hit:

- **Name it on the call**, every n8n tool (`n8n_get_workflow`, `n8n_list_workflows`,
  `n8n_update_partial_workflow`, `n8n_manage_datatable`, `n8n_manage_credentials`,
  `n8n_executions`, `n8n_test_workflow`, `n8n_health_check`, …) takes an optional
  `instance: "<name>"`. It routes **that one call** and changes nothing else. **Prefer this.**
- **Set the default with `switch`**, `n8n_instances({mode:"switch", name})` sets the instance used
  by calls that *don't* name one.

The default is shared more widely than it looks. On claude.ai (and other hosted connectors) one
connection serves **every chat and agent** using it, so a `switch` in one chat moves all the
others too, and their next unnamed call silently lands on your instance. A wrong target is
usually silent: a read returns the wrong data and a write lands in the wrong place. So name the
instance.

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

> **Availability.** The `instance` argument needs hosted n8n-mcp backend 0.1.120+ / n8n-mcp
> 2.94.0+. It is there when the n8n tools' input schemas list an `instance` property (and the
> `n8n_instances` list output carries a `hint` about it). If it isn't listed, the server predates
> it: fall back to `switch`, in its own turn, as described under *Switching*.

## Golden rules

The rest: https://github.com/czlonkowski/n8n-skills/blob/HEAD/skills/n8n-multi-instance/SKILL.md