n8n-multi-instance

MCP 経由で複数の n8n インスタンスを操作する

n8n_instances ツールが利用できる場合、ユーザーはマルチインスタンスモードを有効にしています。1 つの MCP 接続から、複数の n8n インスタンス（例：prod、staging、クライアントやチームごとのインスタンス）にアクセスできます。

呼び出し先のインスタンスを指定する方法は 2 つあります。

• 呼び出し時に名前を指定する — すべての 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（およびその他のホスト型コネクタ）では、1 つの 接続を、それを使用するすべてのチャットとエージェントで共有します。そのため、あるチャットで 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 以外のインスタンスを操作する場合、または同じアカウント上で他のエージェントやチャットと並行して操作する場合は、必ず指定します。例：n8n_list_workflows({instance:"prod"})。名前の大文字と小文字は区別されません。このタスクのすべての呼び出しで同じように名前を指定してください。事前に「設定」する必要はありません。
3. 指定した instance が、気付かないまま置き換えられることはありません。 名前が不明な場合は INSTANCE_NOT_FOUND が返され、利用可能な名前が available に表示されます。その一覧から選んで再試行してください。別のインスタンスにフォールバックすることはありません。
4. switch はデフォルトを変更する場合に限って使用し、接続を使うのが自分だけの場合に限ります。 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を受け取りません。switch用に独自のname引数があります。

n8n_instancesツール

2つのモードがあります（modeは必須で、列挙値による検証が行われます）。

• {mode:"list"} → { current, default, available, hint }。副作用はありません。
  • currentとdefaultは、それぞれ1つのインスタンス{ id, name, url, isDefault }（またはnull）です。
  • availableにはすべてのインスタンスが含まれ、それぞれにisCurrentブール値が追加されます。**name**で照合し、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	nameを指定せずにswitchした	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:"<その名前>"を指定して書き込みを再試行してください。instance引数のないサーバーでは、このセッションでn8n_instances({mode:"switch", name:"…"})を実行してから再試行してください。

ターゲット指定の動作（メンタルモデル）

• 名前を指定した呼び出しは、指定されたインスタンスに送られます。それだけです。ステートレスであり、デフォルトを読み取ることも変更することもありません。
• 名前を指定しない呼び出しは、デフォルトに送られます。この接続で最後に実行されたswitchのインスタンスがあればそれに、なければアカウントのデフォルトに送られます。
• デフォルトを共有する範囲はクライアントによって異なります。 ホスト型コネクター（claude.ai、および1つのチャットを複数のMCPセッションに分散するもの）は、接続ごとにデフォルトを1つ保持し、その接続上のすべてのチャットとエージェントで共有します。安定したMCPセッションを持つ直接接続型クライアント（Claude Code、Cursor）は、ターミナルごとにデフォルトを保持しますが、再接続後は接続で最後に切り替えたインスタンスにフォールバックすることがあります。いずれの場合も、別の作業によってデフォルトが変わる可能性があります。そのため、ルール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

切り替えに依存する作業とswitchをまとめて実行してはいけません。また、切り替えると、その接続を共有するすべてのチャットに影響することを忘れないでください。

復旧手順

症状	通常考えられる原因	対応方法
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 を参照してください。

よくある複数インスタンス間のタスク：インスタンス間で何かをコピーする

インスタンス A の認証情報またはワークフローを、インスタンス B に再作成するには、次のようにします。

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 }
• 1 回の呼び出しで対象を指定：任意の 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 — ルーターです。ビルド手順ごとにどのスキルが担当するかを確認する際に参照してください。