ChiR24-unreal_mcp

EngineWire

EngineWire は Claude、Cursor、VS Code、その他あらゆる MCP クライアントを起動中の Unreal Editor に接続し、
ネイティブ C++ エディタープラグインを通じて、レベル、Blueprint、UI、マテリアル、エフェクトなどを作成できるようにします。

_{🧭 1 つのツールで 400 以上の機能  ·  ⚙️ ネイティブ C++ エディタープラグイン  ·  🌐 HTTP または stdio  ·  🔐 デフォルトでローカル接続、トークン保護付き  ·  🎮 Unreal Engine 5.0 – 5.8}

🌐 enginewire.dev  ·  🛒 Fab  ·  🚀 クイックスタート  ·  📖 Wiki  ·  📦 リリース  ·  💬 ディスカッション

📌 この README はどのバージョンについて説明していますか？ この README では、安定版リリースの 0.6.0 について説明しています。対象は、Fab および リリースページのプラグインと、npm の unreal-engine-mcp-server（latest）です。以前のリリースである 0.5.30 は、1 つではなく 23 個の個別ツールを公開します。0.5.30 のプラグインを使い続けるには、[email protected] に固定してください。0.5.x からのアップグレードをご覧ください。

目次 · できること · 仕組み · クイックスタート · unreal ツール · 設定 · セキュリティ · エンジンプラグイン · Docker · ドキュメント · 開発 · コミュニティ

できること

合計 450 以上の機能を、単一の MCP ツールから利用できます。アシスタントは平易な言葉で検索して機能を見つけるため、名前を覚える必要はありません。全機能の一覧は、生成されたアクションリファレンスをご覧ください。

_{MCP で構築されたプラットフォーマーレベルを Unreal Editor 5.8 で表示しています。右下はプラグインのステータスで、MCP :3000 (1) はネイティブサーバーがポート 3000 で実行され、1 つのクライアントが接続されていることを示します。}

仕組み

EngineWire プラグインはエディター内で動作し、エディターのゲームスレッド上ですべての処理を行い、MCP サーバーとしても機能します。クライアントは 2 つの方法で接続でき、どちらも同じ単一のツール unreal を利用します。

すべて 127.0.0.1 で待ち受け、変更しない限りプロジェクトの機能トークンが必要です。

クイックスタート

クイックスタートのページでは、スクリーンショット付きで手順を説明しています。Unreal Engine 5.0～5.8 が必要です。Fab からインストールする場合、ほかに必要なものはありません。ソースからプラグインをビルドするには、C++ コードを含むプロジェクトが必要です（ブループリントのみのプロジェクトでは、Fab からインストールするか、ビルド済みバイナリを使用できます）。

1. プラグインを追加する

Fab から（コンパイラーは不要です）。 Fab の EngineWire を入手します。Epic Games Launcher で Unreal Engine › Library › Fab Library を開き、EngineWire を探して、お使いのエンジンバージョンの Install to Engine をクリックします。プロジェクトを開き、Edit › Plugins で EngineWire を有効にして、エディターを再起動します。Fab 版ではネイティブサーバーが無効になっています。Edit › Project Settings › Plugins › EngineWire › Native MCP で Enable Native MCP Server を有効にし、もう一度再起動します。Fab のアップデートには Epic の審査があるため、Fab 版はこのページの最新リリースより古い場合があります。

リリースから。 Releases page から最新リリースの EngineWire-plugin-<version>.zip をダウンロードし、含まれている EngineWire フォルダーをプロジェクトにコピーします。

MyGame/Plugins/EngineWire/

または、このリポジトリをクローンして plugins/EngineWire/ をコピーするか、"AdditionalPluginDirectories": ["C:/Path/To/Unreal_mcp/plugins"] を使って .uproject からフォルダーを参照します。

プロジェクトを開き、Unreal にプラグインを再ビルドさせます。読み込まれると、ステータスバーに MCP :3000 (0) と表示されます。プラグインはポート 3000 で MCP を提供します。"Engine modules cannot be compiled at runtime" と表示された場合は、Visual Studio、Rider または Xcode でプロジェクトを一度ビルドしてください。詳しくは Installation をご覧ください。

https://github.com/user-attachments/assets/d8b86ebc-4364-48c9-9781-de854bf3ef7d

node scripts/package-plugin.mjs "C:/Program Files/Epic Games/UE_5.7"

ルート A · ネイティブ HTTP（Node.js 不要）

1. Enable Native MCP Server はデフォルトで有効です（Edit › Project Settings › Plugins › EngineWire、ポート 3000）。Fab ビルドでは無効になっています。無効になっているプロジェクトでは、有効にしてからエディターを再起動する必要があります。

   

2. プラグインが生成した機能トークンを確認します：<YourProject>/Saved/MCP/capability-token。パスワードと同様に扱ってください。

3. サーバーをクライアントに追加し、X-MCP-Capability-Token ヘッダーにトークンを指定します。Claude Code の場合：

   claude mcp add --transport http unreal-engine http://127.0.0.1:3000/mcp --header "X-MCP-Capability-Token: <token>"
   

   または、環境変数からトークンを読み取るプロジェクトの .mcp.json（Claude Code）の場合：

   {
     "mcpServers": {
       "unreal-engine": {
         "type": "http",
         "url": "http://127.0.0.1:3000/mcp",
         "headers": { "X-MCP-Capability-Token": "${UNREAL_MCP_TOKEN}" }
       }
     }
   }
   

   Cursor（.cursor/mcp.json）では、type を含めずに同じ url と headers を指定します。VS Code、Windsurf などの場合は、クライアントの接続を参照してください。

4. **確認する：**クライアントが接続すると、ステータスバーのカウントが増えます。

   

ルート B · stdio（Node.js 20.19+）

このパッケージは、同じ /mcp の前段で動作する小型の stdio プロキシです。/mcp に直接接続したクライアントは、エディターが閉じるかクラッシュするたびにセッションを失い、手動で再接続する必要があります。プロキシ経由では、エディター停止中の呼び出しには NOT_CONNECTED が返され、エディター復帰後の最初の呼び出しで再接続なしに到達します。エディターの直近のツール一覧を保持するため、エディター起動前に開始したセッションでも実際のツールを利用できます。

次の設定をクライアントの MCP 設定に追加してください。例として、Claude Desktop の claude_desktop_config.json を示します。

{
  "mcpServers": {
    "unreal-engine": {
      "command": "npx",
      "args": ["-y", "unreal-engine-mcp-server"],
      "env": {
        "UE_PROJECT_PATH": "C:/Path/To/YourProject"
      }
    }
  }
}

UE_PROJECT_PATH（プロジェクトフォルダーまたはその .uproject）を使って、プロキシは機能トークンを検索します（MCP_AUTOMATION_CAPABILITY_TOKEN を指定すると上書きされます）。UNREAL_MCP_URL は別のエンドポイントを指定します（デフォルトは http://127.0.0.1:3000/mcp）。0.6 プラグインと組み合わせてください。0.5.x プラグインでは unreal ゲートウェイではなく、23 個の個別ツールが提供されます。

3. 試してみる

エディターを開いた状態で、アシスタントに 「現在のレベルにあるアクターを一覧表示して」、「原点から 300 単位上にポイントライトをスポーンして」、または 「ビューポートのスクリーンショットを撮って」 と依頼してください。接続できない場合は、トラブルシューティングを参照してください。

unreal ツール

どちらのルートでも公開される MCP ツールは unreal の1つだけで、4つの操作を備えています。数百ものツールスキーマを読み込む代わりに、モデルがこれから使用する契約だけが読み込まれます。

一般的なやり取り：

{ "operation": "search", "query": "spawn actor" }

{ "operation": "describe", "tool": "control_actor", "action": "spawn" }

{
  "operation": "execute",
  "tool": "control_actor",
  "action": "spawn",
  "params": { "classPath": "/Script/Engine.PointLight", "actorName": "KeyLight", "location": [0, 0, 300] }
}

• パラメーターは厳密に検証されます。 宣言されていない名前は UNDECLARED_PARAMETER として拒否され、使用可能な名前の一覧が返されます。すべてのエラーには実行可能な nextCall が含まれます。
• 削除には同意が必要です。 破壊的な機能はすべて、また一部のリスクを伴う書き込み機能は、describe から取得した consentGrant をトップレベルの consent フィールドに指定した場合にのみ実行されます。
• 名前の指定。 呼び出しでは tool と action の組み合わせ、または "capability": "control_actor.spawn" のような機能 ID を指定します。

実際の応答を含む完全なリファレンス：ゲートウェイの使用。

直接ツール呼び出しからの移行

どちらのルートでも、単一の unreal ツールが今後も使用されます。オプトアウトする方法はなく、23個のツール一覧を復元することもできません。正規のツール名を直接呼び出すクライアント（name: "manage_asset"、name: "control_actor" などを指定した tools/call）には、ルーティングされた呼び出しの代わりに、上限付きでコピーして実行できる DIRECT_TOOL_CALL_REMOVED のレシートが返されます。その nextCall は、ちょうど1段階先へ進みます。未知の名前には { "operation": "search" }、アクションが指定されていない場合は { "operation": "describe", "tool": "<tool>" }、呼び出しですでにアクションが指定されている場合は { "operation": "execute", "tool": "<tool>", "action": "<action>", "params": { ... } } が返されます。その nextCall を unreal で実行して移行を完了してください。アップグレードをご覧ください。

プロトコルのバージョン

どちらのルートも、initialize で MCP プロトコルのバージョンをネゴシエートします。対応するバージョンは 2025-11-25（最新）、2025-06-18、2025-03-26 です。古いバージョンを要求するクライアントには、2025-11-25 を返します。ネイティブルートでサポートされていない MCP-Protocol-Version ヘッダーが指定された場合は、HTTP 400 を返します。どちらのルートも、リクエストごとに initialize やセッションなしで MCP 2026-07-28 にも対応し、そのバージョンで server/discover に応答します。詳細については、docs/protocol.md をご覧ください。

ほとんどのセットアップで変更が必要なのは、ルート B の UE_PROJECT_PATH だけです。ルート A では設定は不要です。すべての設定は設定ページに記載されています。

プラグイン設定（プロジェクト設定 › プラグイン › EngineWire。Config/DefaultGame.ini に保存されます）：

環境変数（ルート B のみ。クライアントの env ブロック内で指定します）：

セキュリティ

• デフォルトではローカル限定です。 どちらのルートも 127.0.0.1 のみで待ち受けます。LAN アクセスには Allow Non Loopback が必要です。また、ネイティブサーバーは Require Capability Token が有効でない限り、ループバック以外へのバインドを拒否します。
• Capability Token。 プロジェクトごとに <Project>/Saved/MCP/capability-token に生成されます（Capability Token に入力した値が優先されます）。比較は定時間で行われます。トークンをローテーションするには、ファイルを削除してエディターを再起動してください。
• 破壊的な操作への同意。 削除や一部の書き込みには、呼び出しごとの同意許可が必要です。プラグインがこの許可を確認します。
• ガードレール。 アセットパスは /Game、/Engine、/Script、/Temp、/Niagara に制限されます。また、コンテンツパスは、接続中のエディターが報告するマウント配下にある場合もあります。サーバーがファイルとして扱う引数（filePath や、アセット名を指定する場合の outputPath など）では、報告されたマウントは使用されません。コンソールコマンドでエディターを終了したり、コマンドを連結したりする操作はブロックされます。プラグイン独自の設定は自動化からアクセスできません。

詳細はセキュリティを参照してください。脆弱性はGitHub のセキュリティアドバイザリーから非公開で報告してください。

エンジンプラグイン

ブリッジはエンジンプラグインへの依存関係を宣言しているため、Unreal はブリッジと同時にこれらを有効化します。

このプラグインは Unreal Engine 5.0 から 5.8 までの各マイナーバージョンを対象としています。お使いの環境でビルドに失敗する場合は、ビルドログを添えてイシューを作成してください。

Docker

イメージは stdio プロキシを実行します。エディターの 127.0.0.1:3000 にある /mcp に接続する必要があるため、ホストネットワーク（Linux）を使用し、コンテナからプロジェクトフォルダーを読み取れないためトークンを渡してください。

docker build -t unreal-mcp .
docker run -i --rm --network host -e MCP_AUTOMATION_CAPABILITY_TOKEN=<token> unreal-mcp

-t を付けずに -i を使用してください。TTY を使うと stdout 上の MCP ストリームが破損します。

ドキュメント

開発

npm install
npm run build              # clean + compile TypeScript to dist/
npm run dev                # run from source with ts-node
npm run lint               # ESLint (CI fails on any warning)
npm run type-check         # tsc --noEmit, sources and tests
npm run test:unit          # Vitest unit tests (no Unreal required)
npm run test:params        # strict parameter audit
npm run registry:generate  # capability records -> generated contracts, native shards, action reference
npm run registry:check     # fail if generated artifacts drift
npm run manifest:check     # fail if the gateway manifest drifts
npm run eval:check         # search-ranking corpus
npm run version:check      # all version sources agree
npm test                   # integration suite (needs a live Unreal Editor serving /mcp)

src/tools/catalog/capabilities/records/ の機能レコードが唯一の信頼できる情報源です。すべての *.generated.* ファイル、プラグインの MCP/Generated/ シャード、アクションリファレンスは、これらのレコードから生成されます。生成ファイルを手動で編集しないでください。機能の追加方法については、開発をご覧ください。

CI では、次の順に実行します。ESLint（npx eslint . --max-warnings=0）、型チェック、ユニットテスト、registry:check、manifest:check、headers:check、厳格なパラメータ監査（test:params）、eval:check、続いてブロッキング対象となるランタイム依存関係の監査（npm audit --omit=dev --audit-level=moderate）と、参考情報としての全ツリー監査を実行します。Node 20.19 / 26 のマトリックスで build を追加実行します。CI ランナーにはエンジンが含まれていないため、Unreal Engine のルートが設定されている場合にのみプラグインのパッケージングを実行します。リリースアーカイブには Binaries/、Intermediate/、Saved/ は含まれません。

コミュニティ

コントリビューション： プルリクエストは小さく、対象を絞り、Conventional Commits に沿ったタイトルを付けてください。バグについては再現手順を記載し、既存のコードスタイルに従ってください。CONTRIBUTING.mdをご覧ください。

ライセンス

MIT。LICENSEをご覧ください。