このページは英語から機械翻訳されています。英語の原文を読む。

トラブルシューティング

Unity MCP のよくある問題を解決しましょう。AI クライアントにツールが表示されない、サインインや接続エラー、サーバーのダウンロード失敗、NuGet DLL エラー、ポート競合などを扱います。

2026年11月4日に更新 Markdownで表示

このページでは、Unity MCP でよく発生する問題とその解決方法をまとめています。まずはクイックチェックリストを確認し、解決しない場合は以下から該当する症状を探してください。

クイックチェックリスト

  1. Window > AI Game Developer — MCP を開き、タイムラインを確認します。Unity、MCP server、AI agent がすべて緑になっている必要があります。
  2. Unity Console にエラーがないか確認します。プロジェクト内のどこかでコンパイルエラーがあると、プラグインのエディタースクリプトが読み込まれなくなります。
  3. unity-mcp-cli status ./MyUnityProject を実行して、Unity が起動しているか、どのサーバーに接続できるかを確認します。
  4. 設定を変更した後は、必ず AI クライアントを再起動してください。
  5. プラグインと拡張機能が最新バージョンであることを確認します。

AI クライアントに Unity のツールが表示されない

  • Unity の準備ができる前にクライアントが接続した。 クライアント側で MCP サーバーに再接続するか（Claude Code では /mcp）、ウィンドウに Connected と表示されてからクライアントを再起動してください。
  • クライアントが設定されていない、または古い設定が使われている。 ウィンドウでエージェントの Configure（または Reconfigure）をクリックするか、unity-mcp-cli setup-mcp <agent> . を実行してからクライアントを再起動してください。
  • クラウドモードにサインインしていない。 ウィンドウに「Authorization Required」と表示されます。Authorize をクリックし、ブラウザでコードを承認してください。
  • 複数のプロジェクトが開かれている。 ピン留めされていない https://ai-game.dev/mcp URL は、別のエディターにルーティングされる可能性があります。Configure が書き込むピン留めされた URL を使用してください。
  • エージェントが別のフォルダから起動されている。 .mcp.json や .cursor/mcp.json などのプロジェクトレベルの設定は、クライアントが Unity プロジェクトフォルダ内で実行されている場合にのみ読み込まれます。
  • VS Code の場合、Copilot Chat を Agent モードに切り替えてください。

クラウドのサインインに関する問題

  • 「Authorization Required」が繰り返し表示される。 認証情報の有効期限が切れたか、取り消されています。もう一度 Authorize をクリックするか、unity-mcp-cli login --force を実行してください。
  • 「Connection Required」と表示される。 サインインは成功しましたが、Unity に接続されていません。Connect をクリックしてください。
  • 誤ったアカウントでサインインしている。 Revoke をクリックして（マシン上のすべての AI Game Dev ツールからサインアウトします）、正しいアカウントで Authorize してください。unity-mcp-cli login はアカウントを切り替える前に確認を求めます。

アカウントのセッションとデバイスの管理については、Authentication で説明しています。

ローカル MCP サーバーが起動しない（Custom モード）

  • バイナリがダウンロードされていない。 バイナリは Library/mcp-server/<platform>/ に配置されます。ダウンロードに失敗した場合（オフライン、ファイアウォール、プロキシ）、ウィンドウに「Server binary error」と Download / Retry server ボタンが表示されます。Tools > AI Game Developer > Server > Download Binaries を使うこともできます。
  • ウイルス対策ソフトが実行ファイルをブロックした。 セキュリティソフトで gamedev-mcp-server を許可してから、再試行してください。
  • トランスポートが stdio になっている。 stdio では AI エージェントがサーバーを自身で起動するため、Start ボタンは無効になります。Unity に起動させたい場合は http に切り替えてください。
  • サーバーログを確認する。 Tools > AI Game Developer > Server > Open Logs と Open Log Errors を使用してください。
  • サーバーを直接テストする。 Tools > AI Game Developer > Server > Launch MCP Inspector を実行すると、ローカルサーバーに対して MCP Inspector が開きます（HTTP トランスポートのみ、Node.js が必要）。

ポートの競合

各プロジェクトには、そのパスから導出される 20000 から 29999 の間の固定ポートが割り当てられます。そのポートを別のプロセスがすでに使用している場合、ウィンドウには MCP サーバーが External と表示されます。プロセスを特定してください。

netstat -ano | findstr :<port>
lsof -i :<port>

そのプロセスを停止するか、切断して Server URL に別のポート（例: http://localhost:25000）を入力し、エージェントが新しいポートを使用するように再度 Configure をクリックしてください。

コンパイル中の切断

Unity はコードを変更するたび、および Play モードに入るたびにスクリプトをリロードします。プラグインはリロード前に切断し、リロード後に再接続するため、短時間の「Disconnected」や「Connecting...」は正常です。リロード中に実行中だったツール呼び出しは失敗する可能性があります。その場合はエージェントに再試行を依頼してください。

インストール後のコンパイルエラーまたは DLL の欠落

プラグインは .NET 依存関係を NuGet から Assets/Plugins/NuGet にダウンロードします。

  • McpPlugin、ReflectorNet、SignalR の型が見つからないというエラー。 最初のインポートが完了するのを待ってから、Tools > AI Game Developer > Dependencies > Force Resolve NuGet DLLs を使用してください。
  • Windows で「Path too long」が発生する。 Unity のランタイムは、長いパスが有効になっていても、Windows の 260 文字のパス制限を超える DLL を開けません。プロジェクトを C:/Projects/MyGame のような短いフォルダに移動してください。
  • クリーン再インストール。 Unity を閉じ、Assets/Plugins/NuGet とその .meta ファイルを削除して、プロジェクトを再度開きます。

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

Console に「The project path contains spaces」と表示された場合は、プロジェクトをスペースを含まないフォルダに移動してください。このようなパスは使用中に問題を引き起こす可能性があるため、プラグインが警告しています。

ツール呼び出しの失敗またはタイムアウト

  • 「object not found」などのエラー。 名前やパスを推測するのではなく、まずエージェントにクエリ（例: rql-query）を実行するよう依頼してください。アセットパスは Assets/ で始まります。
  • 長時間の処理がタイムアウトする。 遅いベイクや大規模なテスト実行の場合は、ウィンドウの Tool timeout (ms) を増やしてください（デフォルトは 300000）。
  • バッチモードでスクリーンショットが失敗する。 -nographics で起動したエディターにはグラフィックスデバイスがありません。-nographics を付けずにヘッドレスで起動してください。unity-mcp-cli open --headless はすでにそうしています。
  • カスタムツールがスレッドエラーをスローする。 Unity API の呼び出しを MainThread.Instance.Run でラップしてください。Custom tools を参照してください。

unity-mcp-cli の問題

  • open が「Enter Safe Mode?」で止まる。 CLI は自動的に Ignore をクリックします。macOS ではターミナルにアクセシビリティ権限を付与してください。Linux では xdotool をインストールしてください。
  • exec が待機した後に諦める。 プロジェクトが CLI の起動していないエディターで開かれており、そのプラグインがローカルで応答していません（たとえばクラウドに接続している）。プラグインを接続するか、Custom に切り替えるか、--url を指定してください。
  • setup-skills が失敗する。 プラグインが接続された実行中のエディターが必要です。先に open と wait-for-ready を実行してください。
  • --verbose を使用すると、任意のコマンドで詳細なログを確認できます。

完全リセット

  1. Unity を閉じます。
  2. プロジェクト内の Library/mcp-server/ を削除します。
  3. Unity を再度開き、Tools > AI Game Developer > Reset Config を選択します。
  4. 再度サインインする（Cloud）か、サーバーを起動して（Custom）、エージェントの Configure をクリックします。
  5. AI クライアントを再起動します。

サポートを受ける

AI Game Developer ウィンドウ下部の Help / Talk（Discord）または Bug Report（GitHub issues）を使用してください。Unity のバージョン、OS、プラグインのバージョン（ウィンドウに表示）、Console のエラー、再現手順を含めてください。FAQ やサイト全体の FAQ を参照することもできます。