n8n-multi-instance

Switch and verify n8n instance targets for MCP sessions before workflow and credential operations.

6.2k|1.0k|Updated Oct 20, 2025
One-click install
npx skills add https://github.com/czlonkowski/n8n-skills --skill n8n-multi-instance
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: n8n-multi-instance
Source: https://github.com/czlonkowski/n8n-skills/tree/main/skills/n8n-multi-instance
Command: npx skills add https://github.com/czlonkowski/n8n-skills --skill n8n-multi-instance

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

When an n8n-mcp account runs in multi-instance mode, every workflow, datatable, credential, and execution call silently routes to whichever n8n instance the session currently targets. A wrong target produces wrong data, misleading NOT_FOUND errors, or secrets written to the wrong instance, usually with no error at all.

Core Features & Use Cases

  • Instance discovery and switching: List available instances with n8n_instances({mode:"list"}) and bind the session by name with mode:"switch", always in its own turn.
  • Pre-write verification: Re-confirm the current instance immediately before credential create/update/delete operations, and handle the INSTANCE_AMBIGUOUS fail-close by switching on the session and retrying.
  • Misroute recovery playbook: Diagnose unexpected NOT_FOUND or empty reads as wrong-instance routing, recover without recreating objects, and detect silent fallback to the default instance.
  • Use Case: You have prod and staging n8n instances and need to create a credential on staging. The skill guides you to list instances, switch to staging in its own call, verify current, then write the credential safely.

Quick Start

Ask the assistant to list your n8n instances, switch this session to the staging instance, and confirm the target before creating a credential there.

Frequently Asked Questions about n8n-multi-instance

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I switch between multiple n8n instances over MCP?

Call n8n_instances with mode "list" to see available instances and the current target, then call it with mode "switch" and the instance name. The switch must be its own tool call, never batched with dependent operations, since parallel calls have no guaranteed order.

Why does n8n_get_workflow return NOT_FOUND for a workflow that exists?

In multi-instance mode, an unexpected NOT_FOUND almost always means the session is targeting the wrong instance, not that the object was deleted. Run n8n_instances list to check the current instance, switch if needed, and retry without recreating the object.

What does the INSTANCE_AMBIGUOUS error mean on credential writes?

INSTANCE_AMBIGUOUS means the server blocked a credential create, update, or delete because this session never switched instances itself but inherited a switch to a non-default instance. Run n8n_instances switch on this session to confirm the target, then retry the write.

Does the n8n instance selection persist across MCP reconnects?

Yes, a switch binds the session for its lifetime, roughly 24 hours, and survives reconnects, idle periods, and backend deploys. Other sessions are independent, and if the selected instance is deleted, calls silently fall back to the default instance.

When does the n8n-multi-instance skill not apply?

It does not apply on single-instance accounts where the n8n_instances tool is absent. In that case all n8n tools target the one instance directly and no switching or target verification is needed.