Unity Mcp

Unity MCP ✨

LLM を使って Unity アプリを作成しましょう！

Unity MCP は、AI アシスタント（例：Claude、Cursor、Windsurf、VS Code）が Model Context Protocol（MCP）を通じて Unity Editor と連携できる、エンドツーエンドのツールチェーンです。LLM にツールを提供することで、Unity Editor 内からアセットの管理、シーンの操作、スクリプトの編集、ワークフローの自動化を直接行えます。

---

💬 このリポジトリについて

このリポジトリには、以下が含まれています。

• Editor 内でローカル HTTP ブリッジを実行する Unity Editor パッケージ
• Unity の操作を MCP ツールとして公開する TypeScript ベースの MCP サーバー（stdio）
• すばやく動作確認できる TypeScript のサンプル MCP クライアント

[LLM / MCP Client] ⇄ [MCP Server (Node/TypeScript)] ⇄ [Unity Bridge (Unity Editor)]

---

主な機能 🚀

• 🗣️ 自然言語による操作 — LLM に Unity のタスクを実行するよう依頼できます
• 🛠️ 強力なツール — アセット、シーン、ゲームオブジェクト、コンポーネント、Editor ユーティリティ、パッケージ、プレイモードなどに対応
• 🤖 自動化 — 繰り返し行う Editor タスクや複数ステップのタスクをスクリプト化できます
• 🎨 ビジュアルスクリプティングとの連携 — 事前構築済みのテンプレートを使い、MCP 操作から Unity Visual Scripting のグラフを作成できます
• 🔍 コンソールの自動検証 — 各ツールの操作後に Unity コンソールのエラーや警告を自動で確認します
• ✅ 強化されたエラー処理 — 操作に失敗すると、コンソールの情報を含むフィードバックがすぐに得られます
• 🎮 スマートなプレイモード制御 — コンパイルエラーがある場合、プレイモードへの移行を防ぎます
• 🧩 拡張可能 — ワークフローの拡大に合わせて、新しい Unity エンドポイントや MCP ツールを追加できます

利用可能なツール

ツール名にはアンダースコアのみが使われます。主なツールは以下のとおりです。

• unity_console — Unity コンソールの読み取りまたはクリア
• unity_play — Play Mode の開始／停止／一時停止／再開
• unity_packages — UPM の一覧表示／インストール／削除
• unity_assets — AssetDatabase の一覧表示／検索／更新
• unity_selection — 選択項目の取得／設定
• unity_gameObject — 階層項目の作成／取得／設定／削除
• unity_component — コンポーネントの追加／更新／取得／破棄
• unity_editor — 状態、情報、通知、buildTarget、設定、invoke
• unity_scene — 開く／保存／別名で保存／読み込まれたシーンの取得／作成／クリーンなシーンの作成／アンロード／クリア
• unity_prefab — Prefab インスタンスの適用／元に戻す
• unity_bake — ライティングのベイクを開始
• unity_profiler — メモリスナップショット
• unity_import — 一般的なテクスチャインポーターの設定
• unity_menu — Editor のメニュー項目を実行
• unity_asset — アセットをシーンにインスタンス化
• unity_tests — EditMode／PlayMode テストの実行
• unity_rendering — ライト／カメラ／マテリアルの作成、プロパティの設定
• unity_gameplay — Rigidbody／Collider ヘルパー、タグ／レイヤー
• unity_code — ファイルの書き込み、スクリプトの作成、スクリプトのアタッチ、コンパイル
• unity_visualscripting — ビジュアルスクリプトの作成、ノードの追加、ワークフローの接続
• unity_visualscripting_templates — ワークフローテンプレートの閲覧、検索、適用
• unity_import - .unitypackages のインポート、または外部ファイルの Unity プロジェクトへのコピー

---

仕組み 🤔

• Unity Bridge — ローカル HTTP API と SSE ログを提供する Editor 専用パッケージ（127.0.0.1:58888）
• MCP サーバー — MCP ツール呼び出しを Unity Bridge のエンドポイントに変換する Node/TypeScript プロセス
• MCP クライアント — stdio 経由で MCP に対応する LLM IDE またはエージェント

---

インストール ⚙️

注意：Unity 2022.3+ と Node.js 18+ が必要です。

1) Unity Bridge パッケージをインストールする

• Unity で Package Manager を開き、+ → Add package from disk... を選択します
• PathToFile/UnityBridge/Packages/com.example.mcp.unitybridge/package.json を選択します
• Unity の読み込みを待ち、Play Mode に一度入ります（またはスクリプトのコンパイルが完了するまで待ちます）

ブリッジが実行中になると、Console に次のように表示されます。

UnityMcpBridge running at http://127.0.0.1:58888/

2) MCP サーバーの依存関係をインストールする

cd MCP/server
npm install

任意（サンプルクライアント）：

cd MCP/client
npm install

3) MCP サーバーをビルドする

cd MCP/server
npm run build

TypeScript を直接使って開発モードで実行することもできます：

cd MCP/server
npm run dev

---

MCP クライアント（Cursor、VS Code、Claude Code など）を設定する

ビルドしたサーバーを指定するエントリーを、MCP クライアントの設定に追加します。ツール名にはアンダースコア形式のみを使用してください。

設定例（JSON）：

{
  "unity-mcp": {
    "command": "node",
    "args": [
      "PathToFile/MCP/server/dist/index.js"
    ],
    "env": {
      "UNITY_BRIDGE_URL": "http://127.0.0.1:58888"
    }
  }
}

コンソール検証の設定

このサーバーには、自動コンソール検証機能が含まれています。環境変数で設定してください：

{
  "unity-mcp": {
    "command": "node",
    "args": ["PathToFile/server/dist/index.js"],
    "env": {
      "UNITY_BRIDGE_URL": "http://127.0.0.1:58888",
      "UNITY_CONSOLE_VERIFICATION": "true",
      "UNITY_CONSOLE_CHECK_DELAY_MS": "500"
    }
  }
}

環境変数：

• UNITY_BRIDGE_TOKEN — セキュリティトークン（Unity とサーバーで同じ値を設定）
• UNITY_CONSOLE_VERIFICATION — コンソールの自動チェックを有効化（デフォルト：true）
• UNITY_CONSOLE_CHECK_DELAY_MS — コンソールをチェックするまでの遅延（デフォルト：500ms）
• UNITY_COMPILE_TIMEOUT_MS — スクリプトのコンパイルタイムアウト（デフォルト：120000ms）

注意：

• サーバーは stdio 経由で通信します。クライアントは stdio ツールとして起動してください。
• コンソール検証により、操作の成功／失敗をすぐに確認できます。
• すべてのツール操作で、Unity コンソールのエラーと警告が自動的にチェックされます。

---

使用方法 ▶️

1. ブリッジパッケージをインストールした Unity プロジェクトを開きます。
2. MCP クライアントを起動します。stdio 経由で Node サーバーが起動するはずです。
3. ツールを名前で使用します（例：アクション create を指定した unity_gameObject）。

スモークテストの例（任意）：

cd MCP/client
# Use tsx for both client and server
set MCP_USE_TSX=1   # Windows (PowerShell: $env:MCP_USE_TSX="1")
npm run dev

次の項目を確認できます：

• ツールの検出
• エディターの状態／情報／通知
• コンソールの読み取り／クリア
• GameObject の作成／更新／削除、コンポーネントの操作
• 再生／一時停止／再開／停止
• シーンの保存／別名で保存
• パッケージの一覧表示

---

ビジュアルスクリプティングの統合 🎨

Unity MCP Bridge には、MCP 操作や自然言語コマンドから Unity ビジュアルスクリプティングのグラフを作成できる、強力なビジュアルスクリプティング統合機能が追加されました。

主な機能

• テンプレートシステム：一般的なゲーム開発パターン向けに、ワークフローのテンプレートを用意しています。
• MCP からビジュアルスクリプトへの変換：MCP 操作をビジュアルスクリプトのノードに変換します。
• ノードベースのワークフロー：ビジュアルノードを使って複雑なワークフローを設計できます。
• 自動接続：インテリジェントなノード接続とフロー管理を実現します。

使用例

// Apply a player setup template
await client.callTool("unity_visualscripting_templates", {
  action: "apply",
  templateName: "create_player_setup",
  gameObjectPath: "Player"
});

// Generate visual script from MCP operations
await client.callTool("unity_visualscripting", {
  action: "generateFromMcp",
  gameObjectPath: "GameManager",
  operations: [
    { tool: "unity_console", action: "clear", description: "Clear console", order: 1 },
    { tool: "unity_scene", action: "save", description: "Save scene", order: 2 }
  ],
  autoConnect: true
});

利用可能なテンプレート

• プレイヤー管理：コンポーネントを含む、プレイヤーの完全なセットアップ
• シーン管理：シーン遷移と最適化
• アセット管理：アセットの最適化と検証のワークフロー
• テストと QA：自動テストパイプライン
• ビルドとデプロイ：ビルドとデプロイの完全なプロセス

詳細なドキュメントについては、ビジュアルスクリプティング統合ガイドを参照してください。

---

セキュリティ 🔐

• ブリッジは 127.0.0.1 にバインドされ、任意で X-Unity-Bridge-Token をサポートします。
• 認証には、Unity と MCP サーバーの環境の両方で UNITY_BRIDGE_TOKEN を設定してください。

---

トラブルシューティング ❓

• ECONNREFUSED／タイムアウト — Unity Editor が開いていて、パッケージがインストール済みであり、コンソールにブリッジの実行中メッセージが表示されていることを確認してください。
• 401 Unauthorized — サーバーと Unity の両方で UNITY_BRIDGE_TOKEN を設定してください（EditorPrefs キー MCP_UnityBridge_Token もサポートされています）。
• ポートが使用中 — 別のサービスが 58888 を使用しています。そのサービスを終了するか、環境を調整してください。
• シーン／アセットのパス — プロジェクト相対の Assets/... パスを使用してください。
• コンパイル時のドメインリロード — ブリッジはリロード時にリスナーを再起動します。コンパイル完了後に再試行してください。

---

開発者向け 🛠️

• サーバー：@modelcontextprotocol/sdk、axios、eventsource を使用する TypeScript（ESM）
• クライアント：ほとんどのツールを実行し、Unity コンソールの差分を出力する TypeScript サンプル
• Unity Bridge：C# のエディター専用パッケージ（HttpListener + SSE + メインスレッドキュー）

ビルド／テストコマンド：

# Server
cd MCP/server
npm run dev      # tsx
npm run build    # tsc
node dist/index.js

# Client (optional)
cd MCP/client
npm run dev      # tsx

---