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

よくあるUnreal MCPの問題を解決 - プラグインが読み込まれない、ブリッジが見つからない、接続が止まる、AIエージェントにUnrealツールがない、古いビルド、ツールエラー。

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

このページでは、Unreal MCPでよく発生する問題とその解決方法をまとめています。まずクイックチェックを確認し、該当するセクションへ進んでください。

## クイックチェック

1. **プラグインは読み込まれていますか?** エディタの起動後、Output Logに`[Unreal-MCP] plugin loaded`が含まれているはずです。
2. **ウィンドウには何と表示されていますか?** **Tools**、**AI Game Developer**を開き、ステータス行(Connected、Connecting、Reconnecting、Disconnected、No MCP bridge)を確認します。
3. **CLIからはどう見えていますか?** `unreal-mcp-cli status --path ./YourProject`を実行します。
4. **ログを確認する。** ウィンドウの**Open log file**を使うか、Output Logを`LogUnrealMcp`カテゴリでフィルタするか、エージェントに`console | where Verbosity == "Error"`を要求してください。

## プラグインが読み込まれない

`[Unreal-MCP] plugin loaded`の行がない場合、エディタモジュールの起動に失敗しています。

- Output Logでプラグインの起動エラーや壊れた`.uplugin`を探してください。
- プロジェクトが、動作するコンパイラツールチェーンを備えた**C++プロジェクト**であることを確認してください。詳しくは[インストール](https://ai-game.dev/ja/docs/wiki/unreal/installation#requirements)を参照してください。
- Unrealがモジュールが見つからない、またはプラグインに互換性がないと表示する場合は、再ビルドさせるか、`unreal-mcp-cli open ./YourProject`でプロジェクトを開いてください。このコマンドはネイティブモジュールを先にビルドし、それらのプロンプトを閉じます。

## アップデートが反映されない

Unrealのインクリメンタルビルドでは、プラグインのソースが変更されても古い`Intermediate/`フォルダが残っていると、古いプラグインコードが保持されることがあります。

- `unreal-mcp-cli update ./YourProject`でアップデートします。このコマンドはデフォルトでビルドキャッシュをクリーンします。
- 手動でコピーした場合は、エディタを閉じ、`Plugins/UnrealMCP/Intermediate/`と`Plugins/UnrealMCP/Binaries/`内のC++ファイルを削除し(`Binaries/ThirdParty/`は残す)、再度開いてください。

## 「No MCP bridge」と表示される、またはブリッジが再起動を繰り返す

プラグインにはブリッジプロセス`unreal-mcp-bridge`が必要です。ウィンドウにはブリッジの状態と再起動回数が表示されます。

- ログに`no sidecar binary resolved for rid <rid>`と表示される場合、ブリッジが見つかっていません。
  - **アプリまたはCLIインストール:** ブリッジは同梱されています。`unreal-mcp-cli install-plugin ./YourProject`(またはアプリから)で再インストールしてください。パッケージにご使用のプラットフォームが含まれていない可能性があります。
  - **ソースチェックアウト:** `unreal-mcp-cli bootstrap-local ./YourProject`でビルドするか、`UNREAL_MCP_BRIDGE_PATH`を設定してください。
- 原因を修正した後、ウィンドウ下部の**Restart bridge**をクリックしてください。

## 「Connecting」または「Reconnecting」のまま止まる

- **クラウドモード:** サインインしているか確認します。ウィンドウに「Sign in required」と表示される場合、保存されたサインインの有効期限が切れています。**Authorize**をクリックし、新しいコードを承認してください。
- マシンがai-game.devに到達できるか確認してください(プロキシやファイアウォールのルール)。
- **カスタムモード:** ローカルサーバーが起動していること(MCP serverカードの**Start**、または`--start-server`)と、**Server URL**がそのサーバーを指していることを確認してください。
- **Disconnect**の後に**Connect**を実行するか、**Restart bridge**を実行してください。

## ローカルサーバーが「No connected clients」と表示する

ローカルの`gamedev-mcp-server`が`No connected clients. Retrying`をログに出力し、その後HTTP 500を返す場合、エディタはまだ**Cloud**モードのままで、ローカルサーバーではなくai-game.devに接続しています。ウィンドウで**Custom**に切り替えるか、`UNREAL_MCP_CONNECTION_MODE=Custom`を設定するか、`unreal-mcp-cli open`に`--connection-mode Custom`(または`--host`)を渡してください。

## AIエージェントにUnrealツールがない

- エージェントの設定を確認します。`unreal-mcp-cli setup-mcp <agent> --path ./YourProject --dry-run`を実行して比較するか、AI agentセクションの**Configure**(または**Reconfigure**)をクリックしてください。
- 設定変更後はエージェントを再起動またはリロードしてください。多くのクライアントは起動時にのみMCP設定を読み込みます。
- Claude Codeは起動したフォルダの`.mcp.json`を読み込みます。プロジェクトフォルダで起動してください。
- エディタを一度も開く前に`setup-mcp`で設定した場合、設定がクラウドではなく`localhost`を指している可能性があります。プロジェクトを一度開いてから`setup-mcp`を再実行するか、`--url`を渡してください。
- Connectionセクションの**AI agents**行を確認してください。エージェントが一覧にない場合、そのエージェントはエディタと同じサーバーに接続していません。
- **MCP Tools**ウィンドウでツールを非表示にした場合や`UNREAL_MCP_TOOLS`を設定した場合、エージェントに表示されるツールは少なくなります。

## エージェントが誤ったエディタに接続する

1つのアカウントで複数のエディタを使用する場合は、プロジェクト固定URL(`/mcp/p/<pin>`)を使用してください。これは`setup-mcp`がデフォルトで書き込みます。`--no-pin`を付けずに`setup-mcp`を再実行してください。詳しくは[AIクライアントの接続](https://ai-game.dev/ja/docs/wiki/unreal/connecting-ai-clients#pinned-url)を参照してください。

## エージェントでの401エラー

- Cloud モードでは、URL のみの設定ではエージェント自身がサインインする必要があります。エージェントに OAuth サインインを実行させるか、マシンをサインイン（`unreal-mcp-cli login`）してから `setup-mcp` を再度実行し、設定にプロジェクトキーを含めます。
- プロジェクトキーが取り消された場合は、エディタの **Regenerate key** を使用するか、`setup-mcp --regenerate-key` を実行してください。
- **token** 認証の Custom モードでは、設定にエディタと同じトークンが含まれている必要があります。新しいトークンを生成した後は **Reconfigure** を使用してください。

## ツール呼び出しがタイムアウトする

1 回のツール呼び出しはデフォルトで最大 5 分間実行されます。長時間の Python スクリプトや大きなインポートの場合は `UNREAL_MCP_TOOL_TIMEOUT`（ミリ秒）を引き上げてください。`python-execute` にも独自の `timeout`（デフォルト 30 秒）があり、エージェントが呼び出しごとに設定できます。

## スクリーンショットツールがエラーを返す

ピクセルキャプチャには GPU 対応のエディタが必要です。`-nullrhi` では、スクリーンショットツールは構造化されたエラーを返します。`unreal-mcp-cli exec` と `open --headless` はオフスクリーンでレンダリングするエディタを起動するため、そこではキャプチャは引き続き機能します。

## Python ツールが失敗する

`python-execute` は Unreal の Python Editor Script Plugin を使用しており、これは Unreal MCP が有効化します。Python が利用できない場合は、**Edit, Plugins** でプラグインが有効になっているか確認してください。エラーは `snippet.py` の行を指し、これはエージェントが送信したコードです。

## 拡張機能が表示されない

- 拡張機能には Unreal Engine 5.7 以降と Unreal MCP 0.26.0 以降が必要です。
- インストール後、拡張機能をコンパイルする必要があります。エディタを再起動するか、`--build` を使用するか、Extensions セクションで **Compile (Live Coding)** を実行してください。
- Extensions セクションで拡張機能が有効になっているか確認してください。

## それでも解決しない場合

- [FAQ](https://ai-game.dev/ja/docs/wiki/unreal/faq) と一般的な [FAQ](https://ai-game.dev/docs/faq) を参照してください。
- ウィンドウの **Help / Talk** から Discord で質問するか、**Bug Report** で GitHub の issue を作成してください。Unreal のバージョン、OS、ウィンドウのステータス行、関連するログ行を含めてください（トークンは決して含めないでください）。

---

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

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