MCP Unity Editor (Game Engine)

MCP Unity エディター（ゲームエンジン）

                              ,/(/.   *(/,                                  
                          */(((((/.   *((((((*.                             
                     .*((((((((((/.   *((((((((((/.                         
                 ./((((((((((((((/    *((((((((((((((/,                     

             ,/(((((((((((((/*.           */(((((((((((((/*.                
            ,%%#((/((((((*                    ,/(((((/(#&@@(                
            ,%%##%%##((((((/*.             ,/((((/(#&@@@@@@(                
            ,%%######%%##((/(((/*.    .*/(((//(%@@@@@@@@@@@(                
            ,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(                
            ,%%####%(    /#%#%%%##(//(#@@@@@@@%,   #@@@@@@@(                
            ,%%####%(        *#%###%@@@@@@(        #@@@@@@@(                
            ,%%####%(           #%#%@@@@,          #@@@@@@@(                
            ,%%##%%%(           #%#%@@@@,          #@@@@@@@(                
            ,%%%#*              #%#%@@@@,             *%@@@(                
            .,      ,/##*.      #%#%@@@@,     ./&@#*      *`                
                ,/#%#####%%#/,  #%#%@@@@, ,/&@@@@@@@@@&\.                    
                 `*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´                   
                    `*%%###########%@@@@@@@@@@@@@@&*´                        
                        `*%%%######%@@@@@@@@@@&*´                            
                            `*#%%##%@@@@@&*´                                 
                               `*%#%@&*´                                     
                                                       
     ███╗   ███╗ ██████╗██████╗         ██╗   ██╗███╗   ██╗██╗████████╗██╗   ██╗
     ████╗ ████║██╔════╝██╔══██╗        ██║   ██║████╗  ██║██║╚══██╔══╝╚██╗ ██╔╝
     ██╔████╔██║██║     ██████╔╝        ██║   ██║██╔██╗ ██║██║   ██║    ╚████╔╝ 
     ██║╚██╔╝██║██║     ██╔═══╝         ██║   ██║██║╚██╗██║██║   ██║     ╚██╔╝  
     ██║ ╚═╝ ██║╚██████╗██║             ╚██████╔╝██║ ╚████║██║   ██║      ██║   
     ╚═╝     ╚═╝ ╚═════╝╚═╝              ╚═════╝ ╚═╝  ╚═══╝╚═╝   ╚═╝      ╚═╝   

MCP Unity は、Unity Editor 用の Model Context Protocol の実装であり、AI アシスタントが Unity プロジェクトを操作できるようにします。このパッケージは、Unity と MCP プロトコルを実装する Node.js サーバーをつなぐブリッジを提供し、Cursor、Windsurf、Claude Code、Codex CLI、GitHub Copilot、Google Antigravity、OpenCode などの AI エージェントが Unity Editor 内で操作を実行できるようにします。

機能

IDE 連携 — パッケージキャッシュへのアクセス

MCP Unity は、Unity の Library/PackedCache フォルダーをワークスペースに追加することで、VSCode のような IDE（Visual Studio Code、Cursor、Windsurf、Google Antigravity）と自動的に連携します。この機能により、次のことが可能になります。

• Unity パッケージのコードインテリジェンスが向上します
• Unity パッケージのオートコンプリートと型情報が改善されます
• AI コーディングアシスタントがプロジェクトの依存関係を理解しやすくなります

MCP サーバーのツール

以下のツールを使用して、MCP 経由で Unity のシーンや GameObject を操作および照会できます。

• execute_menu_item：Unity のメニュー項目（MenuItem 属性が付与された関数）を実行します

  プロンプトの例：「メニュー項目『GameObject/Create Empty』を実行して、新しい空の GameObject を作成してください」

• select_gameobject：パスまたはインスタンス ID によって、Unity のヒエラルキー内のゲームオブジェクトを選択します

  プロンプトの例：「シーン内の Main Camera オブジェクトを選択してください」

• update_gameobject：GameObject の基本プロパティ（名前、タグ、レイヤー、アクティブ／静的状態）を更新します。GameObject が存在しない場合は作成します

  プロンプトの例：「Player オブジェクトのタグを『Enemy』に設定し、非アクティブにしてください」

• update_component：GameObject のコンポーネントフィールドを更新します。対象のコンポーネントが GameObject に含まれていない場合は追加します

  プロンプトの例：「Player オブジェクトに Rigidbody コンポーネントを追加し、質量を 5 に設定してください」

• add_package：Unity Package Manager に新しいパッケージをインストールします

  プロンプトの例：「プロジェクトに TextMeshPro パッケージを追加してください」

• run_tests：Unity Test Runner を使用してテストを実行します

  プロンプトの例：「プロジェクト内の EditMode テストをすべて実行してください」

• send_console_log：コンソールログを Unity に送信します

  プロンプトの例：「コンソールログを Unity Editor に送信してください」

• add_asset_to_scene：AssetDatabase からアセットを Unity のシーンに追加します

  プロンプトの例：「プロジェクト内の Player プレハブを現在のシーンに追加してください」

• create_prefab：任意の MonoBehaviour スクリプトとシリアライズされたフィールド値を指定して、プレハブを作成します

  プロンプトの例：「『PlayerController』スクリプトから『Player』という名前のプレハブを作成してください」

• create_scene：新しいシーンを作成し、指定したパスに保存します

  プロンプトの例：「Scenes フォルダーに『Level1』という新しいシーンを作成してください」

• load_scene：パスまたは名前でシーンを読み込みます。加算読み込みも指定できます

  プロンプトの例：「MainMenu シーンを読み込んでください」

• delete_scene：パスまたは名前でシーンを削除し、Build Settings からも削除します

  プロンプトの例：「プロジェクトから古い TestScene を削除してください」

• get_gameobject：特定の GameObject の詳細情報を、すべてのコンポーネントとともに取得します

  プロンプトの例：「Player GameObject の詳細を取得して」

• get_console_logs：Unity コンソールのログをページネーション対応で取得します

  プロンプトの例：「Unity コンソールの直近 20 件のエラーログを表示して」

• recompile_scripts：Unity プロジェクト内のすべてのスクリプトを再コンパイルします

  プロンプトの例：「Unity プロジェクト内のスクリプトを再コンパイルして」

• save_scene：現在アクティブなシーンを保存します。必要に応じて、新しいパスに「名前を付けて保存」できます

  プロンプトの例：「現在のシーンを保存して」または「シーンを 'Assets/Scenes/Level2.unity' として保存して」

• get_scene_info：名前、パス、変更状態、読み込み済みのすべてのシーンなど、アクティブなシーンの情報を取得します

  プロンプトの例：「プロジェクトで現在読み込まれているシーンを教えて」

• unload_scene：ヒエラルキーからシーンをアンロードします（シーンアセットは削除しません）

  プロンプトの例：「ヒエラルキーから UI シーンをアンロードして」

• duplicate_gameobject：シーン内の GameObject を複製します。名前の変更や親の変更も指定できます

  プロンプトの例：「Enemy プレハブを 5 個複製して、Enemy_1 から Enemy_5 に名前を変更して」

• delete_gameobject：シーンから GameObject を削除します

  プロンプトの例：「古い Player オブジェクトをシーンから削除して」

• reparent_gameobject：ヒエラルキー内の GameObject の親を変更します

  プロンプトの例：「HealthBar オブジェクトを UI Canvas の子にして」

• move_gameobject：GameObject を新しい位置に移動します（ローカル空間またはワールド空間）

  プロンプトの例：「Player オブジェクトをワールド空間の位置 (10, 0, 5) に移動して」

• rotate_gameobject：GameObject を新しい回転に設定します（ローカル空間またはワールド空間、オイラー角またはクォータニオン）

  プロンプトの例：「Camera を Y 軸で 45 度回転して」

• scale_gameobject：GameObject のローカルスケールを新しい値に設定します

  プロンプトの例：「Enemy オブジェクトのサイズを 2 倍にして」

• set_transform：1 回の操作で GameObject の位置、回転、スケールを設定します

  プロンプトの例：「Cube の位置を (0, 5, 0)、回転を (0, 90, 0)、スケールを (2, 2, 2) に設定して」

• create_material：指定したシェーダーを使って新しいマテリアルを作成し、プロジェクトに保存します

  プロンプトの例：「URP Lit シェーダーを使って、'EnemyMaterial' という名前の赤いマテリアルを作成して」

• assign_material：GameObject の Renderer コンポーネントにマテリアルを割り当てます

  プロンプトの例：「'EnemyMaterial' を Enemy GameObject に割り当てて」

• modify_material：既存のマテリアルのプロパティ（色、浮動小数点値、テクスチャ）を変更します

  プロンプトの例：「'EnemyMaterial' の色を青に変更して、メタリックを 0.8 に設定して」

• get_material_info：シェーダーやすべてのプロパティを含む、マテリアルの詳細情報を取得します

  プロンプトの例：「'PlayerMaterial' のすべてのプロパティを表示して」

• batch_execute：複数のツール操作を 1 回のバッチリクエストで実行し、リクエストの往復を減らします。失敗時に任意でロールバックでき、アトミックな操作も可能です

  プロンプトの例：「1 回のバッチ操作で、Enemy_1 から Enemy_10 という名前の空の GameObject を 10 個作成して」

MCP App ツール

• show_unity_dashboard：VS Code で Unity ダッシュボード MCP App を開きます（VS Code 1.109+ が必要です）

  プロンプトの例：「Unity ダッシュボードアプリを開いて」

• get_play_mode_status：Unity のプレイモードの状態（isPlaying、isPaused）を取得します

  プロンプトの例：「Unity はプレイモードですか？」

• set_play_mode_status：アクションを指定して Unity のプレイモードを操作します。'play'（開始または一時停止解除）、'pause'（一時停止の切り替え）、'stop'（プレイモード終了）、'step'（1 フレーム進める）を指定できます

  プロンプトの例：「Unity のプレイモードを開始して」または「ゲームを一時停止して」または「1 フレーム進めて」

MCP サーバーのリソース

• unity://menu-items：Unity Editor で利用可能なすべてのメニュー項目の一覧を取得し、execute_menu_item ツールを使いやすくします

  プロンプトの例：「GameObject の作成に関連するメニュー項目をすべて表示してください」

• unity://scenes-hierarchy：現在の Unity シーンの階層にあるすべてのゲームオブジェクトの一覧を取得します

  プロンプトの例：「現在のシーン階層の構造を表示してください」

• unity://gameobject/{id}：シーン階層にあるインスタンス ID またはオブジェクトパスを指定して、特定の GameObject の詳細情報を取得します。GameObject のすべてのコンポーネントと、シリアライズされたプロパティおよびフィールドも含まれます

  プロンプトの例：「Player GameObject の詳細情報を取得してください」

• unity://logs：Unity コンソールのすべてのログの一覧を取得します

  プロンプトの例：「Unity コンソールの最近のエラーメッセージを表示してください」

• unity://packages：Unity Package Manager から、インストール済みおよび利用可能なパッケージの情報を取得します

  プロンプトの例：「Unity プロジェクトに現在インストールされているパッケージをすべて一覧表示してください」

• unity://assets：Unity Asset Database 内のアセットに関する情報を取得します

  プロンプトの例：「プロジェクト内のすべてのテクスチャアセットを検索してください」

• unity://tests/{testMode}：Unity Test Runner のテストに関する情報を取得します

  プロンプトの例：「Unity プロジェクトで利用可能なテストをすべて一覧表示してください」

• ui://unity-dashboard：Unity ダッシュボードの MCP App UI

  プロンプトの例：「Unity ダッシュボードアプリを開いてください」

MCP サーバーのプロンプト

プロンプトは、一般的な Unity タスク向けに用意された、事前設定済みのテンプレートです。特定のシナリオで適切な操作手順や利用可能なツールを AI アシスタントが理解できるよう支援します。

• unity_dashboard：Unity ダッシュボード MCP アプリを、その機能に関するコンテキスト情報とともに開きます

  **使用方法：**AI アシスタントでプロンプト「unity_dashboard」を使用すると、Unity ダッシュボードにガイド付きでアクセスできます

• gameobject_handling_strategy：GameObject を扱うための構造化されたワークフローを提供します。使用するツールとリソースも含まれます

  **使用方法：**AI アシスタントで GameObject の ID、名前、またはパスとともにプロンプト「gameobject_handling_strategy」を使用すると、手順に沿ったガイダンスを利用できます

要件

• Unity 6 以降 — サーバーのインストールに必要です
• Node.js 18 以降 — サーバーの起動に必要です
• npm 9 以降 — サーバーのデバッグに必要です

メモ

スペースを含むプロジェクトパス

MCP Unity は、スペースを含むプロジェクトパスに対応しています。ただし、接続に問題が発生した場合は、トラブルシューティングとして、スペースを含まないパスにプロジェクトを移動してみてください。

例：

• ✅ 推奨： C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame
• ✅ 対応： C:\Users\Your User\Documents\Unity Projects\My Awesome Game

インストール

この MCP Unity サーバーのインストールは、複数の手順で構成されています。

手順 1：Node.js をインストールする

MCP Unity サーバーを実行するには、Node.js 18 以降がコンピューターにインストールされている必要があります。

ステップ 3：AI LLM クライアントを設定する

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "${workspaceFolder}/Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-unity": {
      "type": "local",
      "enabled": true,
      "command": ["node", "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"],
      "environment": {}
    }
  }
}

AI クライアントが WebSocket サーバーに接続すると、ウィンドウ内の緑色のボックスに自動的に表示されます

オプション：WebSocket ポートを設定する

デフォルトでは、WebSocket サーバーはポート「8090」で実行されます。変更するには：

1. Unity Editor を開きます
2. Tools > MCP Unity > Server Window に移動します
3. 「Connection Port」の値を任意のポート番号に変更します
4. Unity は値を ProjectSettings/McpUnitySettings.json に保存します
5. Node.js サーバーを再起動します

Node ブリッジは、インストール済みのパッケージパスからこのプロジェクト設定ファイルを検出するため、MCP クライアントの作業ディレクトリには依存しません。1 つの Node プロセスで値を上書きするには、UNITY_PORT を設定します。例：UNITY_PORT=9001 node build/index.js。

オプション：タイムアウトを設定する

デフォルトでは、MCP サーバーと WebSocket 間のタイムアウトは 10 秒です。 変更するには：

1. Unity Editor を開きます
2. Tools > MCP Unity > Server Window に移動します
3. 「Request Timeout (seconds)」の値を任意のタイムアウト秒数に変更します
4. Unity は値を ProjectSettings/McpUnitySettings.json に保存します
5. Node.js サーバーを再起動します

1 つの Node プロセスで値を上書きするには、秒単位で UNITY_REQUEST_TIMEOUT を設定します。例：UNITY_REQUEST_TIMEOUT=30 node build/index.js。

ヒント

AI コーディング IDE（Claude Desktop、Cursor IDE、Windsurf IDE など）と MCP サーバー間のタイムアウトは、IDE によって異なります。

オプション：永続的なヘッドレス MCP ホストを実行する

CI やクラウドビルドでブリッジの起動や npm の実行が行われないよう、MCP Unity はデフォルトで -batchmode では無効になっています。長時間稼働するヘッドレス Editor を MCP ホストとして実行するには、Unity の起動前に、Server Window で Allow Batch Mode Server を有効にするか、MCP_UNITY_ALLOW_BATCH_MODE=true を設定してオプトインします：

MCP_UNITY_ALLOW_BATCH_MODE=true Unity -batchmode -nographics -projectPath /path/to/project -logFile /path/to/unity.log

オプトインすると、Unity 側の WebSocket サーバーは通常どおり起動しますが、バッチモードでは npm install や npm run build は実行されません。Node ブリッジがビルド済みで、MCP クライアントから利用できることを確認してください。

ブリッジ設定の解決

Node ブリッジは、各接続値を次の順序で解決します：環境変数（UNITY_PORT、UNITY_HOST、または UNITY_REQUEST_TIMEOUT）、MCP_UNITY_SETTINGS_PATH、インストール済みパッケージより上位の ProjectSettings/McpUnitySettings.json ファイル、その後に作業ディレクトリより上位で見つかったファイル、最後にデフォルト値です。生成された MCP 設定では、MCP_UNITY_SETTINGS_PATH と MCP_UNITY_AUTH_TOKEN_PATH が明示的に設定されます。ブリッジは値の取得元をログに記録し、デフォルト値にフォールバックする前に警告します。

ブリッジのセキュリティとパッケージのインストール

MCP Unity は、プロジェクトごとに 256 ビットの認証トークンを Library/McpUnity/bridge-token に作成します。トークンの解決順序は厳密に定められており、MCP_UNITY_AUTH_TOKEN、MCP_UNITY_AUTH_TOKEN_PATH、検出された Unity プロジェクトの隣にあるトークンの順に優先されます。明示的に指定された値が存在しない場合や形式が正しくない場合は、フォールバックせずに失敗します。生成される設定ではトークンファイルのパスを使用し、シークレットを ProjectSettings にコピーすることはありません。

Unity エンドポイントでは、ユーザー名 mcp-unity の HTTP Basic 認証情報が必要です。また、Origin ヘッダーを含むすべての WebSocket ハンドシェイクを拒否します。WebSocket を直接統合する場合は、認証を行い、Origin を含めないでください。Server Window を使用してトークンをコピーまたは再生成してください。トークンをローテーションした後は、すべての MCP クライアントプロセスを再起動してください。

Unity パッケージはコンパイル時に Editor コードを実行できるため、add_package ツールはデフォルトで無効になっています。パッケージソースと MCP クライアントが信頼できる場合に限り、Tools > MCP Unity > Server Window で Allow Package Installation を有効にするか、ProjectSettings/McpUnitySettings.json で AllowPackageInstallation を true に設定してください。

バージョン 1.5.0 では、1.4.x の Node ブリッジは意図的に拒否されます。Unity と Node の両方のパッケージコンポーネントをアップグレードし、パッケージキャッシュのパスが変わった場合は Unity の Configure アクションを再度実行してから、MCP クライアントを再起動してください。

オプション：リモート MCP ブリッジ接続を許可する

デフォルトでは、WebSocket サーバーは 'localhost' にバインドします。他のマシンからの MCP ブリッジ接続を許可するには、次の手順を実行します。

1. Unity Editor を開きます
2. Tools > MCP Unity > Server Window に移動します
3. 「Allow Remote Connections」チェックボックスを有効にします
4. Unity は WebSocket サーバーを '0.0.0.0'（すべてのインターフェース）にバインドします
5. 新しいホスト設定を適用するため、Node.js サーバーを再起動します
6. MCP ブリッジをリモートで実行するときは、環境変数 UNITY_HOST に Unity マシンの IP アドレスを設定します：UNITY_HOST=192.168.1.100 node server.js

リモートトランスポートは引き続き暗号化されない ws:// です。認証によって不正アクセスは防げますが、通信内容は隠されません。リモートでの使用は、信頼できるネットワーク、VPN、または SSH トンネルに限定してください。Unity プロジェクトのトークンファイルを読み取れないリモートブリッジには、安全なシークレット管理の仕組みを通じて MCP_UNITY_AUTH_TOKEN を渡す必要があります。

サーバーのデバッグ

npx @modelcontextprotocol/inspector node Server~/build/index.js

npx @modelcontextprotocol/inspector node Server~/build/index.js

よくある質問

Error:
Connection failed: Unknown error

トラブルシューティング: WSL2（Windows 11）のネットワーキング

Unity が Windows 11 上で動作している一方、MCP（Node.js）サーバーを WSL2 内で実行している場合、ws://localhost:8090/McpUnity への接続が ECONNREFUSED で失敗することがあります。

原因: WSL2 と Windows は別々のネットワーク名前空間を持っているため、WSL2 内の localhost は Windows ホストを指しません。デフォルトでは、Unity は localhost:8090 でリッスンしています。

解決策 1 — WSL2 のミラーモードネットワーキングを有効にする（推奨）

• Windows 11: 設定 → システム → 開発者向け → WSL → 「ミラーモードネットワーキング」を有効にします。
• または .wslconfig 経由で（その後 wsl --shutdown を実行し、WSL を再度開きます）：

[wsl2]
networkingMode=mirrored

有効にすると、localhost が Windows と WSL2 の間で共有されるため、デフォルト設定（localhost:8090）が機能します。

解決策 2 — Node クライアントを Windows ホストに向ける

MCP クライアントを起動する前に、WSL シェルで設定します：

# Use the Windows host IP detected from resolv.conf
export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')

これにより、Server~/src/unity/mcpUnity.ts は localhost の代わりに ws://$UNITY_HOST:8090/McpUnity に接続します（UNITY_HOST を読み取り、存在する場合は ProjectSettings/McpUnitySettings.json 内の Host も尊重することがあります）。

解決策 3 — Unity からのリモート接続を許可する

• Unity: Tools → MCP Unity → Server Window → 「Allow Remote Connections」を有効にします（Unity は 0.0.0.0 にバインドされます）。
• Windows ファイアウォールが、設定されたポート（デフォルト 8090）での受信 TCP を許可していることを確認します。
• WSL2 から、Windows ホストの IP（解決策 2 を参照）に接続するか、ミラーモードが有効になっていれば localhost に接続します。

メモ

デフォルトポートは 8090 です。Unity Server Window（Tools → MCP Unity → Server Window）で変更できます。この値は McpUnitySettings にマッピングされ、ProjectSettings/McpUnitySettings.json に永続化されます。

接続性を検証する

npm i -g wscat
# After enabling mirrored networking
wscat -c ws://localhost:8090/McpUnity
# Or using the Windows host IP
wscat -c ws://$UNITY_HOST:8090/McpUnity

テストの実行

C# テスト（Unity）

Unity の Test Runner を使用してテストを実行します：

1. Unity Editor を開きます
2. Window > General > Test Runner に移動します
3. 「EditMode」タブを選択します
4. 「Run All」をクリックしてすべてのテストを実行します

TypeScript テスト（サーバー）

Jest を使用してテストを実行します：

cd Server~
npm test

ウォッチモードでテストを実行するには：

npm run test:watch

サポートとフィードバック

ご質問やサポートが必要な場合は、このリポジトリで issue を作成するか、あるいは以下の方法でお問い合わせください：

• Linkedin:
• Discord: gamester7178
• Email: [email protected]

コントリビューション

コントリビューションを歓迎します！お気軽に Pull Request を送信するか、リクエスト内容を添えて Issue を作成してください。

変更をコミットする際は、Conventional Commits 形式に従ってください。

ライセンス

このプロジェクトは MIT License の下にあります。

謝辞

• Model Context Protocol
• Unity Technologies
• Node.js
• WebSocket-Sharp