Unreal Engine MCP Server for Claude Desktop

Claude Desktop 向け Unreal Engine MCP サーバー

このリポジトリには、Claude Desktop が Remote Control API 経由で Unreal Engine 5.3 と連携し、テキストプロンプトに基づいて 3D オブジェクトを作成・操作できる Model Context Protocol（MCP）Python サーバーが含まれています。この連携により、Claude は自然言語を使って Unreal Engine の 3D シーンを構築・変更できます。これは、テキストからゲームを生成する技術に向けた初期段階を示すものです。

現在の機能：

• Claude Desktop のテキストプロンプトを使って、Unreal Engine Editor 内のアセットを配置
• プリミティブ形状を組み合わせるためのスタティックメッシュを作成
• アセットを探すために Unreal プロジェクトのフォルダーを検索
• 現在のレベル内のアクターを一覧表示し、現在のエディター選択項目を確認
• MCP から現在のレベルを保存
• 任意の Unreal Remote Control 関数を呼び出し
• Remote Control プロパティエンドポイントを介して Unreal オブジェクトのプロパティを読み書き
• MCP 以外のエージェント向けの、コマンドごとの --help に対応した直接 CLI
• 共通の城ワークフロー、サンプルエージェントスキル、TLA+ ユースケースモデル
• 城のリセットワークフローと、標準搭載の城向け MCP ツール

クイックスタート

1. 必要条件

• Python 3.10+
• Remote Control API（プラグイン）を有効にした Unreal Engine 5.3

2. インストール

リポジトリをクローンし、編集可能モードでインストールします：

git clone https://github.com/runeape-sats/unreal-mcp.git
cd unreal-mcp
pip install -e .

これにより、unreal-mcp-cli コマンドがインストールされ、unreal_mcp パッケージをインポートできるようになります。

3. MCP サーバーを設定

• Claude Desktop を使用している場合は、File → Settings → Developer → Edit Config から claude_desktop_config.json を開き、ローカルリポジトリへのパスを調整して、以下を追加します：

{
  "mcpServers": {
    "unreal-mcp": {
      "command": "uv",
      "args": ["--directory", "\\path\\to\\unreal-mcp", "run", "unreal_mcp_server.py"],
      "env": {}
    }
  }
}

すでにほかの MCP サーバー（blender-mcp など）を設定している場合、競合を防ぐために無効にする必要があることがあります。

4. Unreal Engine を起動

プロジェクトを開いて Unreal Engine を起動し、Remote Control API プラグインが有効になっていることを確認します。

5. MCP クライアントを起動（Claude Desktop など）

• 新しい設定を読み込むため、Claude Desktop を再起動します（つまり、システムトレイに Claude のアイコンが表示されなくなるまで完全に終了する必要があります）。Claude に Unreal Engine 内のオブジェクト作成を依頼すると、接続を確認できます。

プロジェクト構成

unreal_mcp/              # Core package
  __init__.py
  server.py              # MCP server — registers all tools
  cli.py                 # Direct CLI with subcommands and --help
  connection.py          # HTTP connection to Unreal Remote Control API
  actors.py              # Actor create / modify / delete helpers
  assets.py              # Asset discovery and level info
  remote.py              # Generic Remote Control and editor helpers
  utils.py               # Shared constants and parsing utilities

examples/                # Example workflows (separate from core)
  castle/
    workflow.py           # Castle build / verify / reset workflow
    assets/castle-plan.json
    specs/CastleConstruction.tla

tests/                   # Unit tests (20 tests)
  test_castle_assets.py
  test_castle_workflow.py
  test_unreal_cli.py

ルートレベルの shim モジュール（unreal_mcp_server.py、unreal_cli.py など）は、後方互換性のために unreal_mcp.* から再エクスポートします。

機能

基本的なオブジェクト作成

さまざまなパラメーターを使ってプリミティブ形状を作成します：

• キューブ、球体、円柱、平面、円錐
• 位置、回転、スケールを指定
• 色やマテリアルを指定

プロンプトの例：「位置 100、200、50 に赤いキューブを作成」

Blueprint アクターの作成

Blueprint クラスからアクターをスポーンします：

• 建物、小道具、キャラクターなど
• 「基本的なオブジェクト作成」と同様のカスタムパラメーター

プロンプトの例：「/Game/CustomAsset/Blueprints/BP_Bench01 にある Blueprint からベンチをスポーン」

シーン操作

既存のオブジェクトを変更します：

• 位置、回転、スケールを変更
• 色やマテリアルを調整
• 表示状態を切り替え

プロンプトの例：「キューブを位置 0、0、100 に移動して、45 度回転」

エディターの情報確認と選択

現在のレベルとエディターの選択項目を確認します：

• 現在のレベル内のすべてのアクターを、必要に応じてトランスフォームも含めて一覧表示
• エディターで現在選択されているアクターを読み取り
• MCP からラベルでアクターを選択
• 変更をまとめて適用した後、現在のレベルを保存

プロンプトの例：「ラベルに『Bench』が含まれるすべてのアクターを一覧表示してから、それらを選択」

汎用リモートコントロールアクセス

サーバーに汎用のリモートコントロール用の抜け道が追加され、専用の MCP ツールがまだ用意されていない Unreal の機能にもアクセスできるようになりました。

• 任意のオブジェクトパス上の関数を呼び出す
• アクターラベルを自動的にオブジェクトパスへ解決する
• プロパティの読み取りや書き込み時に、クラスでコンポーネントを指定する
• /remote/object/property 経由でプロパティを読み書きする

新しい Python ラッパーを追加せずに、ライト、ポストプロセスボリューム、コンポーネント、エディターのサブシステム、カスタムの Blueprint 公開 API を操作する場合に便利です。

CLI からの直接アクセス

MCP に対応していないエージェントは、代わりに直接 CLI を使用できます。

• unreal-mcp-cli --help で、すべてのコマンドを一覧表示します
• unreal-mcp-cli <command> --help で、関数の使い方を確認できます
• コマンドは、MCP サーバーと同じ Unreal ヘルパーモジュールに直接ルーティングされます

コマンドの例：

unreal-mcp-cli commands
unreal-mcp-cli list-level-actors --kwargs "filter=Castle max_results=20"
unreal-mcp-cli remote-call --kwargs "actor_label=SkyLight function_name=GetActorLocation"

編集可能なスクリプトをまだインストールしていない場合は、.venv\Scripts\python.exe unreal_cli.py --help を使用してください。

Castle Skill と TLA+ モデル

リポジトリに以下が追加されました。

• 再利用可能な城のプラン：examples/castle/assets/castle-plan.json
• サンプルスキル：.github/skills/unreal-castle-builder/SKILL.md
• TLA+ のユースケースモデル：examples/castle/specs/CastleConstruction.tla
• CLI と MCP サーバーの両方に、城の作成、検証、リセット専用のエントリーポイント

城のワークフローでは、エージェントが CLI のヘルプを確認し、基本シェイプから城を構築して、アクターを一覧表示して結果を検証できます。 構築ワークフローでは、デフォルトで新しい城を配置する前に、同じ予定ラベルを持つ古い城のアクターを削除します。必要なコアアクターのセットは維持したまま、レイアウト、サイズ、パレット、ヨー角に決定論的なバリエーションプリセットを指定できるようになりました。リセットワークフローではプレフィックスを指定して城を削除できます。また、TLA+ モデルでは、正常な完了に加えて、再試行、再構築、バリエーションの選択も扱うようになりました。

アセットの検索

使用可能なアセットを検索して一覧表示します。

• アセットタイプ（ブループリント、メッシュ、マテリアル）で絞り込む
• 特定のパス内を検索する
• 特定の用語に一致するアセットを検索する

プロンプトの例：「プロジェクト内のベンチのスタティックメッシュをすべて一覧表示してください」

プロンプトの例

Claude で使用できるプロンプトの例を以下に示します。

Create a blue sphere at position 0, 100, 50 with scale 2, 2, 2

Create a scene with a red cube at 0,0,0, a green sphere at 100,0,0, and a blue cylinder at 0,100,0

List all blueprint assets in the /Game/CustomAsset folder

Get information about the current level

Create a cylinder and then change its color to yellow

List all actors whose label contains Bench

Show me the actors currently selected in the editor

Select actors Bench_A, Bench_B, and Bench_C

Save the current level

Set the intensity property on actor KeyLight to 5000

Call a remote function on actor SkyLight to recapture the scene

Use the CLI help for the castle workflow

Create a castle from basic shapes with prefix SkillCastle

Create a grand sandstone courtyard castle at a new placement

Verify the SkillCastle actors exist in the level

Reset the SkillCastle actors after verification

新しい MCP ツール

既存のスポーン、変更、削除、アセット検索ツールに加えて、サーバーで以下を利用できるようになりました。

• list_level_actors：任意のフィルタリングやトランスフォーム情報を指定して、アクターを一覧表示します
• get_selected_actors：現在の Unreal Editor の選択内容を確認します
• select_actors：ラベルでアクターを選択します
• save_current_level：開いているマップを保存します
• remote_call：オブジェクトパスまたはアクターラベルで、任意の Unreal Remote Control 関数を呼び出します
• get_object_property：任意の Unreal オブジェクトのプロパティを読み取ります
• set_object_property：任意の Unreal オブジェクトのプロパティを書き込みます
• create_basic_castle：共有のプリミティブ城ワークフローを MCP から直接構築します
• verify_basic_castle：プレフィックスで、想定される城のアクターセットを検証します
• reset_basic_castle：プレフィックスまたは厳密なプランラベルで、城のアクターを削除します

城の作成エントリーポイントでは、layout、size、palette、origin、yaw を指定して、エージェントが意図的に城のバリエーションを生成できます。検証ステップでは、引き続き同じ必須ラベルが確認されます。

複雑な remote_call やプロパティの書き込みでは、ネストしたパラメーター構造体を適切に解析できるよう、JSON 形式の引数を使用してください。

CLI のセットアップ

unreal-mcp-cli コマンドを使用できるように、仮想環境内でプロジェクトを編集可能モードでインストールします。

.venv\Scripts\python.exe -m pip install -e .
unreal-mcp-cli --help

便利なコマンドのパターン：

unreal-mcp-cli create-static-mesh-actor --help
unreal-mcp-cli create-basic-castle --prefix SkillCastle --layout courtyard --size grand --palette sandstone
unreal-mcp-cli create-basic-castle --prefix Bastion01 --origin 6000,1200,0 --yaw 45 --palette obsidian
unreal-mcp-cli list-level-actors --kwargs "filter=SkillCastle max_results=40"
unreal-mcp-cli verify-basic-castle --prefix SkillCastle
unreal-mcp-cli reset-basic-castle --prefix SkillCastle --strict-plan

create-basic-castle はデフォルトで、一致する古い城のアクターを置き換えます。重複して重ねて配置したい場合に限り、--keep-existing を使用してください。 名前付きプリセットでは、制御されたバリエーションを指定できます。--layout はフットプリントを変更し、--size は全体のスケールを変更し、--palette はデフォルトの色を変更します。また、--origin または --yaw は配置や向きを変更します。

テスト

自動テストを実行するには、次のコマンドを実行します。

.venv\Scripts\python.exe -m unittest discover -s tests -v

これらのテストでは、CLI の機能、共有の城の計画、TLA+ のアクターセット、サンプルスキルの配線を確認します。

トラブルシューティング

接続の問題

• MCP サーバーを起動する前に、Unreal Engine が実行中であることを確認してください
• Unreal Engine で Remote Control API プラグインが有効になっていることを確認してください
• 別のプロセスがポート 30010 を使用していないか確認してください
• ファイアウォールが接続をブロックしていないことを確認してください

オブジェクトが表示されない

• Unreal Engine の出力ログにエラーがないか確認してください
• オブジェクトが原点（0,0,0）から離れすぎた場所に作成されていないことを確認してください
• 問題を特定するため、リクエストを簡素化してみてください

ログ

サーバーは詳細な情報をコンソールに記録します。問題が発生した場合は、ログでエラーメッセージとトレースバックを確認してください。

開発

開発モードでサーバーを実行するには、次のコマンドを実行します。

pip install mcp[cli]
mcp dev unreal_mcp_server.py

貢献

貢献を歓迎します！これは Claude と Unreal Engine の統合であり、改善できる点はたくさんあります。

• シーンの説明に対する自然言語処理の改善
• より複雑なオブジェクト作成機能
• Unreal Engine のさらなる機能への対応
• エラー処理とフィードバックの改善

ライセンス

MIT ライセンス