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

トラブルシューティング

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

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

このページでは、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++プロジェクトであることを確認してください。詳しくはインストールを参照してください。
  • 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クライアントの接続を参照してください。

エージェントでの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 と一般的な FAQ を参照してください。
  • ウィンドウの Help / Talk から Discord で質問するか、Bug Report で GitHub の issue を作成してください。Unreal のバージョン、OS、ウィンドウのステータス行、関連するログ行を含めてください（トークンは決して含めないでください）。