unreal-mcp

Claude から実行中の Unreal Engine エディタを操作する MCP サーバーです。

Epic 公式の Python Remote Execution プロトコルを使用します。 239.0.0.1:6766 への UDP マルチキャストでエディタのインスタンスを検出し、その後 TCP チャネルでエディタ内の Python を実行します。

Claude  ──stdio──▶  unreal-mcp  ──UDP discovery + TCP──▶  Unreal Editor (PythonScriptPlugin)

プロトコルのクライアント側はベンダリングされていません。サーバーは実行時にエンジンインストール内の Epic の remote_execution.py を探すため、エンジンバージョンが変わっても動作し続けます。

要件

• Unreal Engine 5.x（5.6 で開発）

• Python 3.10 以上、および uv

Related MCP server: unreal-mcp

セットアップ

1. Unreal でリモート実行を有効にする — ここが誰もが失敗するステップです

リモート実行はデフォルトでオフです。有効にしないと、エディタは検出から見えず、すべてのツールが失敗します。

1. Edit > Plugins → Python Editor Script Plugin を有効化 → 再起動。

2. Edit > Project Settings > Plugins > Python → Enable Remote Execution にチェック。

3. エディタを再起動。

2. インストール

cd unreal-mcp
uv sync

3. Claude に登録

claude_desktop_config.json に追加:

{
  "mcpServers": {
    "unreal": {
      "command": "uv",
      "args": ["--directory", "E:\\Maya\\unreal-mcp", "run", "unreal-mcp"]
    }
  }
}

その後、新しい会話を開始してください — セッション中に追加されたサーバーは、すでに実行中のチャットでは認識されません。

エンジンが標準以外の場所にある場合は、UNREAL_ENGINE_ROOT を設定します:

"env": { "UNREAL_ENGINE_ROOT": "D:\\Epic\\UE_5.6" }

ツール

リスト系ツールは limit / offset でページングし、has_more と next_offset を返します。

結果の返却方法

ツールのボディは、result 変数に代入してセンチネル間の JSON として出力するハーネスでエディタに送信されます。これにより、余分な print() や Unreal のログ行がペイロードを壊すのを防ぎ、エディタ内の例外を stdout に埋もれたトレースバックではなく構造化エラーに変換します。

セキュリティに関する注意

unreal_execute_python は、エディタのインタプリタ内でサンドボックス化されていないコードを、完全な unreal モジュールアクセス権で実行します。プロジェクトのコンテンツを変更または削除できます。エディタ自体の Python コンソールと同じ注意で扱ってください。

トラブルシューティング

「実行中の Unreal Editor が検出されませんでした」 — ほぼ常に上記の Enable Remote Execution 設定が原因です。unreal_get_status で確認してください。

「コマンド実行中に接続が失われました」 — エディタが閉じられたか、モーダルダイアログでブロックされています。ダイアログを閉じて再試行してください。セッションは自動的に再検出します。

複数のエディタが開いている場合 — 最初に検出されたノードが優先されます。 unreal_get_status で全リストが表示されるので、どれがどれか確認できます。