UnrealMCP — Unreal Engine 5.7向けネイティブMCP

English | 简体中文

UnrealMCPは、自己完結型のUnreal Engine 5.7 Editor Code Pluginです。Codexや他のローカルMCPクライアントが、開いているUnreal Editorを検査・制御できるようにし、公開するMCPツールは正確に1つ、unrealのみです。

同梱のプラグインはNode.js、npm、Pythonパッケージ、または別途インストールするゲートウェイサービスを必要としません。次の2つのランタイムコンポーネントが含まれています：

• Binaries/Win64/UnrealMCPGateway.exe — MCPクライアントによって起動されるネイティブC++ stdio MCPサーバー。

• Binaries/Win64/UnrealEditor-UnrealMCP.dll — ループバックワーカーを保持し、Unrealの処理をゲームスレッドにディスパッチするエディタモジュール。

ハイライト

• ワンツールのサーフェス: ディスカバリ、ヘルスチェック、実行、非同期タスク制御はすべてunrealの背後にあります。

• 自己完結型: 配布可能なプラグインには、ネイティブstdioゲートウェイとUnreal Editorワーカーが含まれています。

• エージェントフレンドリー: 順序付きのPython/コンソールバッチにより、リフレクションされたUE APIやUnLuaなどのプロジェクト固有のシステムへの柔軟なパスが提供されます。

• ゲームスレッドセーフ: UObjectとエディタ操作はUnrealのゲームスレッド上でディスパッチされます。

• Fab指向のパッケージング: リリース自動化により、外部ランタイムなしのクリーンな単一プラグインZIPが生成されます。

flowchart LR
    C["Codex / MCP client"] -->|"stdio JSON-RPC"| G["Native gateway EXE"]
    G -->|"127.0.0.1 HTTP + optional bearer token"| P["UnrealMCP Editor plugin"]
    P -->|"Game Thread"| U["UE Python / console / UObject APIs"]

ステータスと互換性

機能カタログは、UE 5.8の公式AllToolsetsアグリゲートによって有効化されるすべてのプラグイングループを、UE 5.7のPython/リフレクションおよびコンソールメカニズムを通じてカバーしています。UE 5.8にのみ存在するサブシステムは、標準のUE 5.7では作成できません。必要な5.7サブシステムまたはオプションプラグインが利用可能な場合、同等のワークフローが機能します。機能カバレッジを参照してください。

目次

• クイックスタート

• インストール

• Codexに接続する

• 最初の接続を確認する

• ワンツールAPI

• 機能モデル

• ソースからビルドする

• テスト

• トラブルシューティング

• セキュリティと運用上の制限

• リポジトリマップ

• 配布ノート

クイックスタート

1. デスクリプタが追加のネストディレクトリなしで<Project>/Plugins/UnrealMCP/UnrealMCP.upluginに配置されるようにプラグインを展開します。

2. Minimal MCP for Unreal EditorとPython Editor Script Pluginを有効にし、Unreal Editorを再起動します。

3. 以下の設定を、ユーザーレベルの~/.codex/config.tomlまたは信頼されたプロジェクト内の.codex/config.tomlに保存します。コマンドを絶対パスのゲートウェイパスに置き換えてください。

4. Codexを再起動し、/mcpでunrealが接続されていることを確認し、エージェントにhealthアクションを呼び出してもらいます。

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

正常な結果には、ok: true、実際のエンジンバージョン、is_game_thread: true、python_loaded: trueが含まれます。Unreal Editorは、対象プロジェクトを読み込んだ状態で開いたままにしておく必要があります。

インストール

プロジェクトインストール

バイナリをコピーまたは置き換える前にUnreal Editorを閉じてください。パッケージ化されたUnrealMCPディレクトリを次の場所に展開またはコピーします:

<Project>/Plugins/UnrealMCP

デスクリプタは最終的に次の場所に配置される必要があります:

<Project>/Plugins/UnrealMCP/UnrealMCP.uplugin

プロジェクトを開き、Edit → PluginsでMinimal MCP for Unreal EditorとPython Editor Script Pluginを有効にして、エディタを再起動します。

エンジンインストール

同じエンジンビルドを使用する複数のプロジェクトでプラグインを利用できるようにするには、次の場所にインストールします:

C:/Program Files/Epic Games/UE_5.7/Engine/Plugins/Marketplace/UnrealMCP

管理者権限が必要になる場合があります。プロジェクトローカルのインストールは通常、プロジェクトと一緒にバージョン管理しやすく、開発時には優先されます。

Codexに接続する

Codexデスクトップ、Codex CLI、IDE拡張機能はMCP設定を共有します。ローカルstdioサーバーは、設定されたcommandから起動されます。設定はグローバルに~/.codex/config.toml、または信頼されたプロジェクト内の.codex/config.tomlに置くことができます。公式Codex MCPドキュメントを参照してください。

WindowsのTOMLパスではフォワードスラッシュを使用します:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

また、CodexデスクトップのSettings → MCP servers → Add → STDIOでサーバーを追加することもできます。設定を保存したら、Codexを再起動し、/mcpを使用してサーバーが接続されていることを確認します。

MCPクライアントはネイティブゲートウェイのみを起動します。Unreal Editorを起動することはありません。ツール呼び出しを行う前に、Unreal Editorで対象プロジェクトを開いてください。

ポートと認証

ワーカーは127.0.0.1にのみバインドします。次の環境変数は、エディタとゲートウェイがそれぞれ独立して読み取ります:

認証のためには、Unreal EditorとCodexを起動する前に同じトークンを設定してください。トークンをコミットしないでください:

$env:UE_MCP_WORKER_TOKEN = '<a-long-random-token>'
$env:UE_MCP_WORKER_PORT = '18777'
& 'C:\Program Files\Epic Games\UE_5.7\Engine\Binaries\Win64\UnrealEditor.exe' 'C:\path\Project.uproject'

Codexがそのシェルから起動されない場合は、同じ値をMCPサーバー設定に指定してください:

[mcp_servers.unreal]
command = "C:/absolute/project/path/Plugins/UnrealMCP/Binaries/Win64/UnrealMCPGateway.exe"
startup_timeout_sec = 15
tool_timeout_sec = 3600

[mcp_servers.unreal.env]
UE_MCP_WORKER_PORT = "18777"
UE_MCP_WORKER_TOKEN = "replace-with-the-same-token-used-by-the-editor"
UE_MCP_TIMEOUT_MS = "30000"

最初の接続を確認する

MCPクライアントにunrealを次のように呼び出してもらいます:

{
  "action": "health"
}

正常な応答は次のような形式になります:

{
  "ok": true,
  "data": {
    "ok": true,
    "engine_version": "5.7.x-...",
    "is_game_thread": true,
    "python_loaded": true,
    "transport": "loopback-http"
  }
}

次にエンジンの読み取りを確認します:

{
  "action": "execute",
  "transaction": false,
  "commands": [
    {
      "kind": "python",
      "mode": "eval",
      "label": "engine-version",
      "code": "unreal.SystemLibrary.get_engine_version()"
    }
  ]
}

evalは1つのPython式を評価してその値を返します。execはステートメントまたは複数行スクリプトを実行します。unrealモジュールは、プラグインのPython実行環境で利用できます。

ワンツールAPI

unrealはアクション判別型スキーマを使用するため、MCPクライアントはディスカバリ、実行、ヘルスチェック、長時間実行タスクの制御を保持しつつ、ツール定義を1つだけ受け取ります。

機能のディスカバリ

UE APIを選択する前に、独立した機能カタログを検索してください:

{
  "action": "discover",
  "query": "create and compile a blueprint",
  "limit": 5
}

blueprint、asset、niagara、pcg、slate、umg、unluaなどの正確なドメインにはdomainを使用します。クエリなしでdiscoverを呼び出すと、要求された上限までのカタログエントリが返されます。

順序付きバッチの実行

executeバッチは、最大100個のPythonまたはコンソールコマンドを受け入れます。コマンドはゲームスレッド上で順番に実行されます。

{
  "action": "execute",
  "run": "sync",
  "transaction": true,
  "continue_on_error": false,
  "timeout_ms": 120000,
  "commands": [
    {
      "kind": "python",
      "mode": "exec",
      "label": "select-all-static-mesh-actors",
      "code": "subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\nactors = subsystem.get_all_level_actors()\nsubsystem.set_selected_level_actors([a for a in actors if isinstance(a, unreal.StaticMeshActor)])"
    },
    {
      "kind": "console",
      "label": "show-fps",
      "command": "stat fps"
    }
  ]
}

• transactionはデフォルトでtrueで、バッチ全体が成功したときに1つのエディタのアンドゥレコードを作成します。

• continue_on_errorはデフォルトでfalseです。有効にすると、後続のコマンドも実行されますが、いずれかのコマンドが失敗した場合、全体の結果は失敗のままです。

• timeout_msは100～3600000ミリ秒を受け入れ、その呼び出しのUE_MCP_TIMEOUT_MSを上書きします。

• Pythonの結果とキャプチャされたPythonログ、またはコンソール出力がコマンドごとに返されます。

読み取り専用のクエリや、Unrealのトランザクションに関与しないAPIにはtransaction: falseを使用します。UnrealのトランザクションはUNDOレコードであり、ファイルシステムやソース管理のロールバックではありません。

非同期処理の実行と確認

長いバッチの場合は、非同期で送信します:

{
  "action": "execute",
  "run": "async",
  "timeout_ms": 3600000,
  "commands": [
    {
      "kind": "console",
      "command": "Automation RunTests Project"
    }
  ]
}

応答にはtask_idが含まれます。タスクのポーリングまたは一覧表示は次のように行います:

{ "action": "task", "command": "get", "task_id": "<uuid>" }

{ "action": "task", "command": "list" }

タスクをキャンセル済みとしてマークするには:

{ "action": "task", "command": "cancel", "task_id": "<uuid>" }

タスクの状態はゲートウェイプロセスに保持され、Codexがそのプロセスを停止すると失われます。キャンセルはベストエフォートです。トラッキングをキャンセル済みとしてマークしますが、Unrealのゲームスレッドにすでにディスパッチされた処理は完了する可能性があり、ロールバックされません。

機能モデル

このプラグインは、意図的に何百もの狭いラッパーツールを避けています。discoverはレシピと推奨APIを提供し、executeはUE 5.7のリフレクションされたPythonサーフェス、コンソールコマンド、オプションのエンジンプラグイン、およびUnLuaなどのプロジェクト固有のAPIに到達します。

カタログは、UE 5.8のAllToolsetsの全21グループをマッピングします。これには、エディタ/アセット/Blueprint作業、AIとナビゲーション、アニメーション、自動化、設定、会話、Data Registry、Dataflow、Game Features、Gameplay TagsとGAS、Niagara、PCG、物理、プラグイン、セマンティック検索、Slate、StateTree、UMG、World Conditionsが含まれます。

カバレッジはルーティングとメカニズムのカバレッジであり、UE 5.8専用のクラスがUE 5.7に存在することを主張するものではありません。オプションのワークフローでは、対応するエンジンまたはプロジェクトのプラグインを有効にする必要があります。その根拠と5つの最小化パスは、ツール最小化に文書化されています。

ソースからビルドする

必要条件:

• Unreal Engine 5.7のソース/ビルドインストール。スクリプトはデフォルトでC:\Program Files\Epic Games\UE_5.7を使用します。

• UE 5.7がサポートするVisual Studio C++ツールチェーン。

• PowerShell。

• Node.js 20+はオプションのMCPプロトコルテストのみに使用します。Nodeは製品のランタイム依存関係ではありません。

ネイティブゲートウェイをその場でコンパイルします:

.\scripts\build-native-gateway.ps1

完全なプラグインパッケージを新しいディレクトリにビルドします:

.\scripts\build-plugin.ps1 -OutputDirectory 'C:\Temp\UnrealMCP-Package'

単一トップレベルのFab ZIPを作成します:

.\scripts\build-fab-package.ps1 -OutputFile '.\artifacts\UnrealMCP-0.2.0-UE5.7-Win64.zip'

パッケージ化されたプラグインには、デスクリプタ、ソース、設定、リソース、ネイティブDLLとEXE、ライセンス表示、英語と簡体字中国語のREADME、設計ドキュメントが含まれます。Fab ZIPには、トップレベルのUnrealMCP/ディレクトリが1つだけ含まれ、Intermediate、PDBファイル、Nodeパッケージ、開発用テストプロジェクトは除外されます。

各エンジンバージョンとプラットフォームには、独自にコンパイルおよびテストされたバイナリパッケージが必要です。現在のデスクリプタはWin64のみを対象としています。

テスト

メタデータとネイティブのモダン/レガシーMCP統合テストを実行します:

npm install
npm test

完全なネイティブstdioゲートウェイ → ループバックワーカー → ゲームスレッド → UE Pythonパスを実行します:

.\scripts\build-native-gateway.ps1
.\scripts\test-worker-e2e.ps1

エンドツーエンドテストは、含まれているUE57MCPTest.uprojectをヘッドレスで隔離されたポート上で起動し、検証後にシャットダウンします。選択したポートが使用中の場合は、無関係な自動テストインスタンスを閉じてください。

トラブルシューティング

ゲートウェイはMCPプロトコルメッセージをstdoutにのみ書き込み、診断情報はstderrに書き込みます。プラグインの起動、バインド、認証、実行エラーは、LogUnrealMCPの下のUnreal Output Logに表示されます。

セキュリティと運用上の制限

executeは意図的に任意のUnreal Pythonおよびコンソールコマンドを許可します。このツールへのアクセスは、エージェントが開いているエディタプロジェクトを操作することを許可することと同等に扱ってください。

• ワーカーはループバックにのみバインドします。リモートネットワークサービスではありません。

• Bearer認証は任意ですが、共有マシンでは推奨されます。

• リクエストボディは4 MiB、バッチは100コマンドに制限されています。

• UObjectおよびエディタへのアクセスはゲームスレッド上で実行されます。

• ツールの引数、プロジェクトファイル、ログ、またはコミットされたCodex設定にシークレットを置かないでください。

• 破壊的なアセット、設定、プラグイン、ファイルシステム操作にはソース管理を使用してください。

リポジトリマップ

配布に関する注意

生成されたZIPは、Fabの技術レビューに適した単一のインストール可能なUE Code Pluginとして構成されています。マーケットプレイスでの公開には、販売者/リスティングのメタデータと、プラグインアイコンやスクリーンショットなどのビジュアルアセットに加えて、宣伝するすべてのエンジンバージョンとプラットフォームでテストされたパッケージが依然として必要です。

ライセンスの詳細はLICENSEにあり、サードパーティの通知はTHIRD_PARTY_NOTICES.mdにあります。追加の設計ノート: アーキテクチャ、機能カバレッジ、ツール最小化。

このプロジェクトが役に立ったなら、Star ⭐ を付けていただけると幸いです。