# トラブルシューティング — Unity · AI Game Developer Wiki

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

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/unity/troubleshooting)。

このページでは、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](https://ai-game.dev/docs/auth) で説明しています。

## ローカル 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** と表示されます。プロセスを特定してください。

```powershell
netstat -ano | findstr :<port>
```

```bash
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](https://ai-game.dev/ja/docs/wiki/unity/custom-tools#main-thread) を参照してください。

## 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](https://ai-game.dev/ja/docs/wiki/unity/faq) やサイト全体の [FAQ](https://ai-game.dev/docs/faq) を参照することもできます。

---

Source (HTML): https://ai-game.dev/ja/docs/wiki/unity/troubleshooting

Machine-translated (ja) from the English page: https://ai-game.dev/docs/wiki/unity/troubleshooting