UnityMCP VRC

UnityMCP-VRC

Claude（または任意の MCP クライアント）から Unity Editor を操作できます。Unity Editor のプラグインが Editor 内で小規模な HTTP サーバーを起動し、小規模なMCP サーバー（Node/TypeScript）がツール呼び出しごとに 1 件のリクエストを送信して、Claude にツールを公開します。Editor 内で C# を実行したり、Editor やシーンの状態を読み取ったり、Unity のコンソールログを取得したりできます。

Arodoid/UnityMCP をフォークして大幅にリファクタリングし、Claude を使ってVRChat / UdonSharpやBasisのワールドを作ることに重点を置いています。ただし、その大半は通常の Unity 開発でも機能します。Unity 2022.3 から Unity 6までで動作します（コマンドサンドボックスはプロジェクトごとにコンパイルバックエンドを選択します。詳細は後述）。take_screenshot と get_object_details ツールは setohima/UnityMCP-VRC から移植し、このプロジェクトの接続モデルに合わせて調整しました。

Debug Window — プラグインの HTTP サーバーが Editor 内で待ち受けています（各インスタンスは個別のポートを使用します）。

主な特長

• 複数の Editor と、複数の Claude セッション。 各 Editor のプラグインは独自の HTTP サーバーを動的なポートで起動して共有レジストリに登録するため、複数のプロジェクトを同時に実行し、それぞれを名前で指定できます。また、任意の数の Claude セッションから同じ Editor を操作できます。固定ポートの競合や、「接続済みなのに応答しない」ゾンビサーバーは発生しません。
• ローカルかつ認証済み。 Editor のエンドポイントは 127.0.0.1 のみで待ち受け、すべてのコマンドに、ローカルのインスタンスレジストリから読み取った、Editor のセッションごとに生成される暗号学的にランダムなトークンが必要です。
• 実際の C# を実行。 execute_editor_command は、LLM が作成した C#（独自の using、クラス、関数を含む）を実行します。読み込み済みのすべてのアセンブリ（UnityEngine、パッケージ、VRChat/UdonSharp、Basis、プロジェクトスクリプト）からアセンブリ参照を自動検出するため、手動でリストを管理する必要はありません。
• Unity 2022.3 から Unity 6 まで。 コマンドサンドボックスは、.NET Framework プロジェクト（Unity 2022 / VRChat で一般的）では Mono のインプロセスコンパイラを使ってコンパイルします。また、Mono の方法を利用できない .NET Standard プロジェクト（Unity 6 のデフォルト）では、Editor に同梱されている Roslyn の csc に自動的にフォールバックします。フォールバックは一度検出され、キャッシュされるため、設定は不要です。詳細：docs/005。
• 状態を制限。 get_editor_state はシーンやプロジェクトの状態を要求に応じて返します。大規模なプロジェクトでもコンテキストウィンドウを圧迫しないよう、サイズに上限があります。
• 処理内容を確認。 take_screenshot は Scene またはゲームカメラを画像として Claude に返し、get_object_details は GameObject のコンポーネントや境界情報を出力します。そのため、視覚的な反復作業や調査のたびに C# を手書きする必要はありません。
• 再コンパイル後も動作。 ドメインリロード中は HTTP リスナーが一時的に停止するだけです。破棄が必要な永続ソケットはないため、リロード中に送信されたリクエストは Editor が復帰するまで再試行されます。
• ライブ Debug Window。 サーバーの待ち受け状態、直近のリクエスト、メインスレッドのキューを表示するため、接続の問題がすぐにわかります。
• VRChat ヘルパーと MCP リソースにより、Claude の UdonSharp 成功率を高めます。

ツール

ツール	説明
list_unity_instances	現在実行中の Unity Editor（名前、プロジェクト、instanceId）を一覧表示し、選択できるようにします。
select_unity_instance	後続の呼び出しでデフォルトの対象となる Editor を（セッションごとに）選択します。呼び出し時に instance= で上書きすることもできます。
execute_editor_command	LLM が作成した C# を Editor 内でコンパイルして実行し、結果とログを返します。大規模なインポートなど時間のかかる処理向けに、任意の timeoutMs（デフォルトは 60s、最大 300s）を指定できます。
get_editor_state	必要に応じて Unity／シーン／プロジェクトの状態を返します（上限あり）。
get_object_details	1 つの GameObject を調査し、Transform、コンポーネント、サイズ情報（Renderer の境界、メッシュの頂点数、共有メッシュ／マテリアル名）を返します。
get_logs	Unity の最近のコンソールログを返します。
clear_logs	Editor にバッファリングされたコンソールログを消去します（例：失敗したスニペットによる古いエラーを消去し、後続の get_logs の結果が曖昧にならないようにします）。
take_screenshot	Scene ビューまたはゲームカメラを JPEG／PNG 画像としてレンダリングし、Claude が編集結果を確認できるようにします。
get_command_page	ページ分割された、サイズ超過のツール結果の後続ページを取得します。対象は execute_editor_command、get_object_details、get_editor_state です（自動的に使用されます）。

はじめに

1. MCP サーバーをビルドする

cd unity-mcp-server
npm install
npm run build      # compiles to build/index.js and copies text resources

2. プラグインを Unity に追加する

• UnityMCPPlugin/ フォルダー全体をプロジェクトの Assets/ にドラッグします。Unity はインポート時に .meta ファイルを再生成します。リポジトリではこれらを追跡しません。
• UnityMCP メニューが表示されます。Debug Window を開いてドッキングします。Unity の実行中は、Server の行が緑色で Listening と表示されます。

3. Claude から接続する — stdio MCP サーバーをクライアントに追加します。Claude Desktop の場合（開発者モードを有効にしてから、File > Settings）：

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["C:\\git\\UnityMCP\\unity-mcp-server\\build\\index.js"]
    }
  }
}

または、Claude Code の場合：claude mcp add unity -- node C:\git\UnityMCP\unity-mcp-server\build\index.js

4. 動作を確認する — Debug Window で Server: Listening を確認します。Claude の起動後に MCP Client の行が表示されることも確認してください（複数のセッションを接続すると、それぞれが表示されます）。Claude にプロンプトを送ります。スクリプトでエラーが発生した場合は、UnityMCP > Script Tester で原因を調べます。

複数の Editor を使う

必要な数だけプロジェクトを開けます。各プロジェクトはプロジェクトフォルダー名で登録されます。1 つの Claude セッション内で：

1. list_unity_instances — 実行中のものを確認します（名前・プロジェクト・instanceId）。
2. select_unity_instance <name> — セッションの残りの呼び出しで対象となるものを選択します。個々の呼び出しでは instance=<name> で上書きできます。

インスタンスを選択するまではツールを実行できないため、誤ったプロジェクトに呼び出しが送られることはありません。セッションを最初から特定のプロジェクトに固定するには、MCP サーバーの env に UNITYMCP_INSTANCE=<name> を設定します（そうすればエージェントが選択する必要はありません）。検出情報の記録は %LOCALAPPDATA%\UnityMCP\instances\ に保存されます（UNITYMCP_REGISTRY_DIR で変更可能）。これらの記録にはローカル MCP サーバーが使用する非公開のセッショントークンも含まれるため、コピーしたり公開したりしないでください。各 Editor には、Debug Window に名前と instanceId が表示されます。

プラグインは、レジストリディレクトリとトークンファイルへのアクセスを現在の OS ユーザーに制限します。カスタムの UNITYMCP_REGISTRY_DIR には、そのユーザーが所有する専用ディレクトリを指定する必要があります。そのアクセス権も制限されます。Editor と MCP サーバーには同じディレクトリを使用してください。

認証なしのトランスポートからアップグレードする場合は、すべての Unity プロジェクトでプラグインを更新し、MCP サーバーを再ビルドして、MCP クライアントを再起動してください。セッショントークンのない古いプラグインは、更新後のサーバーでは検出されません。

トラブルシューティング

• Claude では「Connected」と表示されるのに、Unity では何も起きませんか？ MCP バッジが示すのは、Claude とサーバー間のハンドシェイクのみであり、Unity への接続ではありません。Debug Windowを確認してください。Server: Listening と MCP Client の行が、実際に接続されていることを示します。
• サーバーがバインドされない、または「NOT listening」と表示されますか？ 各 Editor は OS によって割り当てられたポートを使うため、競合は起こりにくいです。Server の行が赤色の場合、Last Error ボックスにバインド失敗の内容が表示されます。Restart Server をクリックして、新しいポートを割り当ててください。
• 呼び出しが停滞したり、タイムアウトしたりしますか？ Editor のフォーカスが外れている間はスロットリングが発生します。Editor の行のキューの深さを確認してください。Unity にフォーカスを戻すか、バックグラウンドで使用する場合は Preferences > General > Interaction Mode > No Throttling を選択してください。
• ドメインの再読み込みに 10～20 秒以上かかります（Unity が「Reloading Domain…」のまま停止しますか）？ Windows では、これは通常、コンパイル直後のアセンブリがウイルス対策ソフトによってスキャンされていることが原因です。再コンパイル後にのみ、Editor のログに Loaded All Assemblies, in N seconds という行が長時間表示されます。プロジェクトの Library/ フォルダー、Unity Editor のインストール先、Unity.exe／bee_backend.exe プロセスを、リアルタイムスキャンの除外対象に追加してください。有効なスキャナーすべてで設定してください（Windows Defender と HP Wolf Pro Security などのベンダー製エージェントなど、1 台のマシンで複数のスキャナーが動作している場合があります）。再読み込みは通常、約 20 秒から約 3 秒に短縮されます。.cs ファイルを書き込む execute_editor_command は再読み込みを発生させるため、これにより MCP の処理ループも直接高速化されます。詳細： docs/004 — 再読み込みが遅い場合。

詳しくは、docs/001 — アーキテクチャをご覧ください。

ドキュメント

• 001 — アーキテクチャ — 現在の仕組み：接続モデル、ワイヤープロトコル、スレッド処理、ライフサイクル、ツール、ファイルマップ、制限事項。まずはこちらをご覧ください。
• 002 — 設計上の決定 — アーキテクチャの背景にある理由：逆向きのステートレス接続、サーバー側のページング、置き換えた WebSocket トランスポートについての説明。
• 003 — 元のフォークからの変更点 — このリポジトリが上流の Arodoid/UnityMCP と異なる点：逆向きのトポロジー、VRChat／UdonSharp のサポート、ページング、ライセンスの変更。
• 004 — Unity Editor の状態 — プラグインが対応する Editor のライフサイクル：コンパイル、ドメインの再読み込み、プレイモード、フォーカス／スロットリング。それぞれがいつ発生し、実行中のコマンドにどう影響するかを説明します。
• 005 — LLM の C# コードの実行 — コマンドのサンドボックス：LLM が作成した C# コードのコンパイル方法（BCL ファサードを含む参照の自動検出）、実行、結果とログのキャプチャ、出力の制限、信頼モデルについて説明します。
• 006 — コードからの UdonSharp コンポーネントの追加 — GameObject に動作する Udon スクリプトを追加するための確実な手順（プログラムアセット + backing UdonBehaviour + プロキシ + CopyProxyToUdon）、各手順が必要な理由、および UdonSharpHelper を使って 1 回の呼び出しにまとめる方法を説明します。

ライセンス

Creative Commons Attribution-NonCommercial 4.0 International （CC BY-NC 4.0）のライセンスに基づいています。