Unity操作が苦手なエンジニアがUnity-MCP + Claude Codeを導入してみた

はじめに

Unityでゲームを作りたいものの、普段の業務でUnityを使う機会がなく、エディタの操作(GameObjectの配置、コンポーネントのアタッチ、シーン構築など)がなかなか身につかない——そんな悩みを抱えていました。コード自体は書けるのに、エディタ上での「配置」「組み立て」の部分でいつも手が止まってしまう、という方は少なくないと思います。

そこで見つけたのが Unity-MCP です。Claude Codeなどのエージェントから自然言語でUnityエディタを直接操作できるOSSツールで、「シーンに立方体を1つ作って」のような指示だけで実際にUnity上にオブジェクトが生成されます。

本記事では、このUnity-MCPをClaude Codeと連携させてセットアップする手順と、実際に遭遇したトラブルとその解決方法をまとめます。素直に進めば数分の作業ですが、今回は接続エラーにハマったため、そのトラブルシューティング込みで記録しておきます。

• リポジトリ: IvanMurzak/Unity-MCP
• ライセンス: Apache-2.0(商用利用も無料)
• 2026年6月時点でGitHubスター3,000超
• 対応Unityバージョン: 2022.3以降(LTS版でOK。今回は2022.3.48f1で動作確認)

できること

Unity-MCPは70以上のMCPツールを標準搭載しており、以下のような操作を自然言語から実行できます。

• GameObjectの作成・複製・削除・親子関係の設定
• コンポーネントの追加・編集
• マテリアル・プレハブの作成
• シーンの作成・保存・切り替え
• C#スクリプトの読み書き・動的実行(Roslynによるコンパイル)
• コンソールログの取得
• プロファイラでのパフォーマンス計測
  対応エージェントはClaude Code、Claude Desktop、GitHub Copilot、Cursor、Gemini CLIなど幅広く、今回はClaude Codeを使用しました。

前提条件

• Unity 2022.3以降
• Node.js / npmがインストール済みであること
• プロジェクトパスに空白を含まないこと(例: C:/MyProjects/MyProject はOK、C:/My Projects/MyProject はNG)

セットアップ手順

1. unity-mcp-cliのインストール

npm install -g unity-mcp-cli

2. Unityプロジェクトへのプラグイン導入

対象のUnityプロジェクトパスを指定して実行します。

unity-mcp-cli install-plugin "C:\Users\xxxx\ProjectName"

√  Resolved plugin version: 0.83.1
✔  Updated C:\Users\xxxx\ProjectName\Packages\manifest.json
ℹ  Installing Unity-MCP plugin v0.83.1 into: C:\Users\xxxx\ProjectName
✔  Done! Open the project in Unity Editor to complete installation.

Packages/manifest.json にOpenUPMのスコープ付きレジストリ(package.openupm.com)が自動追加されます。

3. Unityエディタでプロジェクトを開く

unity-mcp-cli open "C:\Users\xxxx\ProjectName"

トラブル①: 「Unity is running as administrator」警告

管理者権限で開いたターミナルからunity-mcp-cli openを実行すると、Unityエディタも管理者権限を引き継いでしまい、以下の警告が表示されました。

Unity is running with Administrator privileges, which is not supported...

対処法: 「Restart Unity as a standard user」を選択し、標準ユーザー権限で再起動します。以降の作業も、管理者権限でない通常のターミナルから行います。

トラブル②: Scoped Registryのインポートダイアログ

Unityエディタを開くと、Package Managerの設定画面にScoped Registry追加のダイアログが表示されました。

これはinstall-pluginがPackages/manifest.jsonにOpenUPMのレジストリ(スコープ: com.ivanmurzak)を追加したことをUnityが検知したものです。「Close」を押した後、Package Manager画面の「Apply」ボタンで設定を確定します。

Applyがグレーアウトしている場合は、すでに設定が反映済みで保存すべき変更がない状態なので問題ありません。左メニューに「AI Game Developer」の項目が追加されていれば、プラグインの組み込みは成功しています。

AI Game Developerウィンドウの設定

Window > AI Game Developer を開くと、接続設定画面が表示されます。デフォルトは「Cloud」モードになっていました。

外部サービスへの依存や認証を避けたい場合は「Custom」タブに切り替えます。認証(Authorize)は不要になり、ローカル完結のhttp://localhost:xxxxx経由での接続になります。

「AI agent」セクションでは、Claude Codeを選択すると「Setup Required」として2つの項目が表示されます。

• Skills(推奨): 一番上の「Enable Skills」ボタンで有効化
• MCP Configuration: 「Configure」ボタンで.mcp.jsonを生成
  ここが今回のハマりポイントでした。 Skillsの「Auto-generate」にチェックを入れて「Generate」ボタンを押しても、AI agentのステータスが赤いままでした。

原因は、Skills(使い方の説明)とMCP Configuration(接続設定そのもの)は別物で、両方を設定する必要があったためです。「Model Context Protocol (MCP)」欄の「Configure」ボタンも押して.mcp.jsonを生成することで解決しました。

拡張機能(Extensions)としてAnimation、Tilemap、ProBuilderなども用意されています。2Dゲームなら後々Tilemap拡張が役立ちそうです。

トラブル③: Version handshake failed(本命のエラー)

MCP Configurationを設定した後も、Consoleに大量の警告が出続けました。

エラーログを確認すると、以下が根本原因でした。

fail: [AI] McpManagerClientHub McpManagerClientHub Version handshake failed: No response from server.

Unity(クライアント)がMCPサーバーに接続しようとしたものの、サーバーから応答がない状態です。

切り分けの流れ

1. Windows Defenderのブロックを疑う → 保護の履歴を確認したが、unity-mcp-server.exe個別のブロック記録はなし。今回は無関係でした。

2. サーバープロセスの有無を確認 → タスクマネージャーでunity-mcp-server.exeは見当たらないが、netstat -anoでポートは実際にLISTENING状態。矛盾している = 何かがおかしい兆候。

3. Unity.exeの多重起動を疑う → タスクマネージャーで検索すると、Unity.exeが3つ同時に実行中でした。管理者権限での再起動やCLIでの複数回起動により、古いプロセスが残ってしまっていたようです。
   

4. 全プロセスを終了して再起動 → タスクを全終了し、Unityエディタを1つだけクリーンに起動し直しましたが、それでも解決せず。

5. ゾンビプロセスの発見 → netstat -anoで見えていたPIDをタスクマネージャーの表示と突き合わせたところ、Unity.exeを全部終了したにもかかわらず、古いサーバープロセスのPIDだけがポートを掴んだまま残っていました。

  netstat -ano | findstr 20357
  TCP         0.0.0.0:20357          0.0.0.0:0              LISTENING       21028
  TCP         [::]:20357             [::]:0                 LISTENING       21028

    # PIDを直接指定して強制終了
    taskkill /PID 21028 /F

    # ポートが解放されたことを確認
    netstat -ano | findstr 20357
    # → 何も表示されなければ解放成功

1. クリーンな状態で再起動 → ポート解放後にunity-mcp-cli openで開き直したところ、無事「Unity: Connected」「MCP server: Running」が両方緑になりました。
   教訓: Unity-MCPは特定のポート(プロジェクトパスのSHA256ハッシュから決定される固定ポート)でサーバーを待ち受けます。Unityエディタを強制終了したり、管理者権限⇔標準ユーザーの切り替えで再起動を繰り返すと、サーバープロセスだけがゾンビ化してポートを掴んだまま残ることがあるようです。接続エラーが起きたら、まずnetstat -ano | findstr <ポート番号>でポートの状態を確認し、該当PIDをtaskkill /PID <PID> /Fで強制終了するのが有効な対処法でした。

動作確認

すべての接続が緑になったら、プロジェクトフォルダでClaude Codeを開き、指示を出します。

MCPツール実行の許可を求められるので、内容を確認して許可します(繰り返し使う場合は「このプロジェクトでは今後許可」を選ぶと以降スムーズです)。

Game Viewを確認すると、実際に立方体(Cube)が生成されていました。

自然言語の指示だけで実際にUnityシーンにオブジェクトが生成される、という一連の動作を確認できました。

まとめ

Unity-MCPを使うことで、「コードは書けるがエディタ操作に慣れていない」というエンジニアでも、自然言語での指示だけでシーン構築を進められるようになります。特に、絵担当・デザイン担当とプログラマーが分業しているチームでは、プログラマー側がアセットの仮配置までAI経由で素早く進め、後からデザイナーが本番アセットに差し替える、という分担もやりやすくなりそうです。

セットアップ自体は本来数分で終わる作業ですが、今回のように管理者権限の切り替えや複数回の起動を挟むと、サーバープロセスがゾンビ化して接続エラーに繋がることがあります。同様のエラーに遭遇した方は、まずnetstatでポートの状態を確認してみることをおすすめします。

今後、実際のゲーム制作を通じて使い勝手を検証していく予定です。

参考リンク

• IvanMurzak/Unity-MCP (GitHub)
• Unity-MCP Wiki - Troubleshooting
• Unity-MCP Wiki - Installation Guide