MCP Unity Editor（ゲームエンジン）

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

MCP Unityは、Unityエディター向けのModel Context Protocolの実装であり、AIアシスタントがUnityプロジェクトと対話できるようにします。このパッケージは、UnityとMCPプロトコルを実装するNode.jsサーバー間のブリッジを提供し、Claude、Windsurf、CursorなどのAIエージェントがUnityエディター内で操作を実行できるようにします。

機能

IDE統合 - パッケージキャッシュアクセス

MCP Unityは、UnityのLibrary/PackedCacheフォルダーをワークスペースに追加することで、VSCode系IDE（Visual Studio Code、Cursor、Windsurf）との自動統合を提供します。この機能により：

• Unityパッケージのコードインテリジェンスが向上
• Unityパッケージのより良いオートコンプリートと型情報が有効化
• AIコーディングアシスタントがプロジェクトの依存関係を理解するのに役立つ

MCPサーバーツール

• execute_menu_item: Unityメニュー項目（MenuItem属性でタグ付けされた関数）を実行

  例: "新しい空のGameObjectを作成するためにメニュー項目'GameObject/Create Empty'を実行"

• select_gameobject: パスまたはインスタンスIDでUnity階層内のゲームオブジェクトを選択

  例: "シーン内のMain Cameraオブジェクトを選択"

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

  例: "Playerオブジェクトのタグを ‘Enemy’ に設定し、非アクティブにする"

• update_component: GameObject上のコンポーネントフィールドを更新、またはGameObjectに含まれていない場合は追加

  例: "PlayerオブジェクトにRigidbodyコンポーネントを追加し、その質量を5に設定"

• add_package: Unityパッケージマネージャーに新しいパッケージをインストール

  例: "プロジェクトにTextMeshProパッケージを追加"

• run_tests: Unityテストランナーを使用してテストを実行

  例: "プロジェクト内のすべてのEditModeテストを実行"

• send_console_log: Unityにコンソールログを送信

  例: "Unity Editorにコンソールログを送信"

• add_asset_to_scene: AssetDatabaseからアセットをUnityシーンに追加

  例: "プロジェクトからPlayerプレハブを現在のシーンに追加"

• create_prefab: プレハブを作成し、オプションでMonoBehaviourスクリプトとシリアライズされたフィールド値を設定

  例: "'PlayerController'スクリプトから'Player'という名前のプレハブを作成"

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

  例: "Unityプロジェクト内のすべてのスクリプトを再コンパイル"

• create_scene: 新しいシーンを作成し、指定されたパスに保存

  例: "Scenesフォルダに'Level1'という新しいシーンを作成"

• load_scene: パスまたは名前でシーンをロード（オプションで追加ロード可能）

  例: "MainMenuシーンをロード"

• delete_scene: パスまたは名前でシーンを削除し、ビルド設定から削除

  例: "プロジェクトから古いTestSceneを削除"

• get_gameobject: すべてのコンポーネントを含む特定のGameObjectの詳細情報を取得

  例: "Player GameObjectの詳細を取得"

• get_console_logs: ページネーションをサポートしてUnityコンソールからログを取得

  例: "Unityコンソールから最新の20件のエラーログを表示"

• 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: 単一の操作で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: 単一のバッチリクエストで複数のツール操作を実行し、ラウンドトリップを削減しアトミック操作を可能にする（失敗時のロールバックオプション付き）

  例: "単一のバッチ操作でEnemy_1からEnemy_10という名前の10個の空のGameObjectを作成"

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: play（開始または再開）、pause（一時停止の切替）、stop（プレイモードの終了）、step（1 フレーム進める）で Unity のプレイモードを操作

  例: "Unity のプレイモードを開始"、"ゲームを一時停止"、または "1 フレーム進めて"

MCPサーバーリソース

• unity://menu-items: execute_menu_itemツールを容易にするために、Unityエディターで利用可能なすべてのメニュー項目のリストを取得

  例: "GameObject作成に関連する利用可能なすべてのメニュー項目を表示"

• unity://scenes-hierarchy: 現在のUnityシーン階層内のすべてのゲームオブジェクトのリストを取得

  例: "現在のシーン階層構造を表示"

• unity://gameobject/{id}: シーン階層内のインスタンスIDまたはオブジェクトパスで特定のGameObjectに関する詳細情報を取得

  例: "Player GameObjectに関する詳細情報を取得"

• unity://logs: Unityコンソールからのすべてのログのリストを取得

  例: "Unityコンソールからの最近のエラーメッセージを表示"

• unity://packages: Unityパッケージマネージャーからインストール済みおよび利用可能なパッケージ情報を取得

  例: "プロジェクトに現在インストールされているすべてのパッケージをリスト"

• unity://assets: Unityアセットデータベース内のアセット情報を取得

  例: "プロジェクト内のすべてのテクスチャアセットを検索"

• unity://tests/{testMode}: Unityテストランナー内のテスト情報を取得

  例: "プロジェクトで利用可能なすべてのテストをリスト"

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

  例: "Unity ダッシュボードアプリを開いて"

MCP サーバープロンプト

プロンプトは、一般的な Unity タスクのガイド付きワークフローを提供する事前設定済みテンプレートです。特定のシナリオにおける適切な操作順序と利用可能なツールを AI アシスタントが理解するのに役立ちます。

• unity_dashboard: 機能に関するコンテキスト情報とともに Unity ダッシュボード MCP App を開く

  使い方: AI アシスタントで unity_dashboard プロンプトを使用すると、Unity ダッシュボードへのガイド付きアクセスを得られます

• gameobject_handling_strategy: 使用するツールとリソースを含む、GameObject 操作の構造化されたワークフローを提供

  使い方: AI アシスタントで GameObject の ID、名前、またはパスとともに gameobject_handling_strategy プロンプトを使用すると、段階的なガイダンスを得られます

要件

• Unity 6以降 - サーバーをインストールするため
• Node.js 18以降 - サーバーを起動するため
• npm 9以降 - サーバーをデバッグするため

[!NOTE] スペースを含むプロジェクトパス

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以降がインストールされている必要があります：

ステップ2: Unityパッケージマネージャー経由でUnity MCPサーバーパッケージをインストール

1. Unityパッケージマネージャーを開く（Window > Package Manager）
2. 左上隅の"+"ボタンをクリック
3. "Add package from git URL..."を選択
4. 入力: https://github.com/CoderGamester/mcp-unity.git
5. "Add"をクリック

ステップ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": {}
    }
  }
}

サーバーの起動

1. Unityエディターを開く
2. Tools > MCP Unity > Server Window に移動
3. "Start Server" をクリックして WebSocket サーバーを起動
4. AI コーディング IDE（例: Cursor、Windsurf、Claude Code、Codex CLI、GitHub Copilot、Google Antigravity、OpenCode など）を開き、Unity ツールの実行を開始

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

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

デフォルトでは、WebSocket サーバーは '8090' ポートで動作します。変更するには:

1. Unityエディターを開く
2. Tools > MCP Unity > Server Window に移動
3. "Connection Port" の値を希望のポート番号に変更
4. Unity は値を ProjectSettings/McpUnitySettings.json に保存
5. Node.js サーバーを再起動

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

オプション: タイムアウト設定

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

1. Unityエディターを開く
2. Tools > MCP Unity > Server Window に移動
3. Request Timeout (seconds) の値を希望のタイムアウト秒数に変更
4. Unity は値を ProjectSettings/McpUnitySettings.json に保存
5. Node.jsサーバーを再起動

プロセスごとに上書きするには、秒単位の UNITY_REQUEST_TIMEOUT を設定します（例：UNITY_REQUEST_TIMEOUT=30 node build/index.js）。

[!TIP]
AIコーディングIDE（Claude Desktop、Cursor IDE、Windsurf IDEなど）とMCPサーバー間のタイムアウトは、使用するIDEによって異なる場合があります。

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

MCP Unity は、CI とクラウドビルドでブリッジが起動したり npm が実行されたりしないよう、既定では -batchmode で無効です。長時間稼働するヘッドレス Editor を MCP ホストとして実行するには、Server Window で Allow Batch Mode Server を有効にするか、Unity の起動前に 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 エディターを開く
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）のネットワーク

WSL2 内で MCP（Node.js）サーバーを実行し、Unity が Windows 11 上で動作している場合、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

有効化後は Windows と WSL2 で localhost が共有され、既定設定（localhost:8090）で動作します。

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

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

# resolv.conf から検出した Windows ホスト IP を使用
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」を有効化（0.0.0.0 にバインド）。
• Windows ファイアウォールで、設定したポート（既定 8090）への受信 TCP を許可します。
• WSL2 からは、Windows ホストの IP（解決策 2 を参照）またはミラー化有効時は localhost へ接続します。

[!NOTE] 既定のポートは 8090 です。Unity の Server Window（Tools → MCP Unity → Server Window）で変更できます。値は McpUnitySettings に対応し、ProjectSettings/McpUnitySettings.json に保存されます。

接続確認

npm i -g wscat
# ミラー化ネットワーク有効化後
wscat -c ws://localhost:8090/McpUnity
# または Windows ホスト 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]

貢献

貢献は大歓迎です！プルリクエストを送信するか、Issueを開いてください。

コミットメッセージはConventional Commits形式に従ってください。

ライセンス

本プロジェクトはMIT Licenseの下で提供されます。

謝辞

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