UnrealMCP — AI Bridge for Unreal Engine 5

UnrealMCP — Unreal Engine 5 向け AI ブリッジ

Claude Code、Cursor、Windsurf、またはあらゆる MCP クライアントから Unreal Engine 5 エディターを操作できます。 マテリアルの作成、Blueprint グラフの接続、Niagara システムの作成、アクターのスポーン、データテーブルの編集、パフォーマンスのプロファイリングまで、すべて指示するだけで実行できます。15 カテゴリにわたる 288 個のコマンドを、ターミナルを離れずに利用できます。

これはコミュニティ版です

コミュニティ版は、対応範囲において安定しており、機能も完成しています。開発が放棄されたわけではありませんが、積極的に開発されているわけでもありません。現在、新しいサブシステムの開発は、メンテナンスが継続されている商用版の **CodeFizz Editor Agent**に移行しています。ここにあるすべての機能は引き続き動作し、Issue も引き続き確認されます。MIT ライセンスは永久に有効です。

Control Rig、PCG、Sequencer、Mutable、Procedural Vegetation、オーディオと MetaSounds、Behavior Trees と EQS、または UE 5.6／5.7／5.8 向けのパッケージ済みバイナリが必要な場合は、Pro 版をご利用ください。

コミュニティ版と Pro 版の比較

コマンド一覧を見る → · ドキュメント · 3 日間の無料トライアル

すでに UE 5.8 をお使いですか？ Epic は 5.8 でファーストパーティの MCP サーバーを提供しています（実験的機能、localhost のみ）。何かを購入する前に、まず試してみる価値があります。このリポジトリと Pro 版は、Epic の MCP サーバーが対応していない 5.6 と 5.7 にも対応しています。

このリポジトリの 2 つの利用方法

どちらもエディター内で動作する同じ C++ プラグインと通信します。ワークフローに合った方法を使うか、両方を併用してください。

クイックスタート

オプション A：CLI（Claude Code におすすめ）

# 1. Install
npm install -g unrealcli

# 2. Go to any UE5 project and install the plugin
cd YourProject/
ue-cli init

# 3. Open the editor, then verify
ue-cli health_check

これだけです。Python も設定ファイルも MCP のセットアップも必要ありません。

オプション B：MCP サーバー（Cursor、Windsurf など向け）

# 1. Clone the plugin into your project
git clone https://github.com/aadeshrao123/Unreal-MCP.git Plugins/UnrealMCP

# 2. Install the Python MCP server
pip install unrealmcp

# 3. Add to your AI tool's config (see MCP Setup section below)

仕組み

                    ┌──────────────────────────────────────────┐
                    │         Unreal Engine 5 Editor            │
                    │                                          │
                    │   C++ Plugin (UnrealMCPBridge)           │
                    │   TCP server on localhost:55557           │
                    │   288 commands: materials, blueprints,   │
                    │   niagara, statetree, actors, data       │
                    │   tables, profiling, and more            │
                    └──────────────┬───────────────────────────┘
                                   │ TCP/JSON
                    ┌──────────────┴───────────────────────────┐
                    │                                          │
          ┌─────────┴─────────┐              ┌─────────┴──────────┐
          │   CLI (ue-cli)    │              │  MCP Server        │
          │   Go binary       │              │  Python (unrealmcp)│
          │   Direct TCP      │              │  stdio → TCP       │
          │                   │              │                    │
          │  Claude Code      │              │  Cursor, Windsurf, │
          │  (via Bash tool)  │              │  VS Code, Rider... │
          └───────────────────┘              └────────────────────┘

C++ プラグインはエディター内で動作し、TCP 経由で 288 個のコマンドを公開します。CLI と MCP サーバーは、同じプラグインにつながる 2 つの異なる入り口です。

CLI リファレンス

インストール

# From npm (recommended)
npm install -g unrealcli

# Or download binary directly from GitHub Releases
# https://github.com/aadeshrao123/Unreal-MCP/releases

対応プラットフォーム： Windows（x64）、macOS（Intel ＋ Apple Silicon）、Linux（x64 ＋ ARM64）

セットアップ

# Navigate to your UE5 project
cd MyProject/

# Install the C++ plugin (one-time)
ue-cli init
# → Creates Plugins/UnrealMCP/ with C++ source
# → Patches .uproject to enable the plugin
# → Open editor to compile, then you're ready

# Verify everything works
ue-cli doctor

使い方

# Every command follows this pattern:
ue-cli <command> [--flag value]

# Examples:
ue-cli health_check
ue-cli find_assets --class-type material --path /Game
ue-cli spawn_actor --name MyCube --type StaticMeshActor --location "[0,0,100]"
ue-cli get_data_table_rows --data-table-path /Game/Data/DT_Items
ue-cli save_all

# For complex params, use --json:
ue-cli build_material_graph --json '{"material_path":"/Game/M_Test","nodes":[...],"connections":[...]}'

# Or pipe from stdin:
echo '{"material_path":"/Game/M_Test","nodes":[...]}' | ue-cli build_material_graph --json -

ヘルプと機能の確認

# See all commands grouped by category
ue-cli --help

# See flags for a specific command
ue-cli find_assets --help

# Dump all commands with descriptions, flags, and examples (for AI assistants)
ue-cli list_commands

グローバルフラグ

主なコマンド

アセット

ue-cli find_assets --class-type material --path /Game/Materials
ue-cli list_assets --path /Game --class-filter blueprint
ue-cli get_asset_properties --asset-path /Game/Materials/M_Base
ue-cli import_asset --source-file "C:/Art/texture.png" --destination-path /Game/Textures
ue-cli save_asset --asset-path /Game/Materials/M_Base
ue-cli save_all

ブループリント

ue-cli create_blueprint --name BP_MyActor --parent-class Actor
ue-cli add_component_to_blueprint --blueprint-path /Game/BP_MyActor --component-class StaticMeshComponent
ue-cli add_event_node --blueprint-name BP_MyActor --event-name BeginPlay
ue-cli compile_blueprint --blueprint-name BP_MyActor
ue-cli read_blueprint_content --blueprint-path /Game/BP_MyActor

マテリアル

ue-cli create_material --name M_Red --path /Game/Materials
ue-cli build_material_graph --material-path /Game/Materials/M_Red \
  --nodes '[{"type":"Constant3Vector","pos_x":-400,"properties":{"Constant":"(R=1,G=0,B=0)"}}]' \
  --connections '[{"from_node":0,"to_node":"material","to_pin":"BaseColor"}]'
ue-cli create_material_instance --parent-path /Game/Materials/M_Base --name MI_Red

データテーブル

ue-cli get_data_table_schema --data-table-path /Game/Data/DT_Items
ue-cli get_data_table_rows --data-table-path /Game/Data/DT_Items
ue-cli add_data_table_row --data-table-path /Game/Data/DT_Items --row-name CopperOre \
  --data '{"DisplayName":"Copper Ore","StackSize":100}'
ue-cli update_data_table_row --data-table-path /Game/Data/DT_Items --row-name CopperOre \
  --data '{"StackSize":200}'

アクターとレベル

ue-cli get_actors_in_level
ue-cli spawn_actor --name MyCube --type StaticMeshActor --location "[0,0,100]"
ue-cli spawn_blueprint_actor --blueprint-path /Game/BP_MyActor --location "[500,0,0]"
ue-cli find_actors_by_name --pattern "Light"
ue-cli get_world_info
ue-cli take_screenshot

パフォーマンスプロファイリング

# Record → Stop → Analyze
ue-cli performance_start_trace --channels "cpu,gpu,frame"
# ... play the game ...
ue-cli performance_stop_trace
ue-cli performance_analyze_insight --query diagnose
ue-cli performance_analyze_insight --query flame --count 20
ue-cli performance_analyze_insight --query search --filter "ConveyorProcessor"

Enhanced Input

ue-cli create_input_action --asset-path /Game/Input/IA_Jump --value-type Boolean
ue-cli create_input_mapping_context --asset-path /Game/Input/IMC_Default
ue-cli add_key_mapping --context-path /Game/Input/IMC_Default --action-path /Game/Input/IA_Jump --key SpaceBar

Niagara VFX

# Create a system from an emitter template, then tweak it
ue-cli create_niagara_system --asset-path /Game/VFX/NS_Sparks \
  --template "/Niagara/DefaultAssets/FX_Sparks.FX_Sparks"
ue-cli get_niagara_system_info --asset-path /Game/VFX/NS_Sparks
ue-cli set_niagara_module_input --asset-path /Game/VFX/NS_Sparks \
  --emitter-name Sparks --stack SpawnStack \
  --module-name "Spawn Rate" --input-name SpawnRate --value 250
ue-cli compile_niagara_system --asset-path /Game/VFX/NS_Sparks

# Spawn it in the level
ue-cli spawn_niagara_effect --asset-path /Game/VFX/NS_Sparks --location "[0,0,200]"

StateTree

# Create a StateTree, add a state with a task, compile
ue-cli create_statetree --asset-path /Game/AI/ST_Enemy
ue-cli add_statetree_state --asset-path /Game/AI/ST_Enemy --state-name Patrol
ue-cli add_statetree_task --asset-path /Game/AI/ST_Enemy \
  --state-name Patrol --task-type "MassEnemyNestPatrolTask"
ue-cli add_statetree_transition --asset-path /Game/AI/ST_Enemy \
  --from-state Patrol --trigger OnEvent --event-tag "Enemy.SeePlayer"
ue-cli compile_statetree --asset-path /Game/AI/ST_Enemy

Mass Config Traits（部分的な編集）

# Modify a single trait property without touching the rest of the trait array
ue-cli get_mass_config_traits --asset-path /Game/Mass/Enemy_Config
ue-cli set_mass_config_trait_property --asset-path /Game/Mass/Enemy_Config \
  --trait-class MassMovementTrait --property-name MaxSpeed --property-value 600

ウィジェット（UMG）

ue-cli get_widget_tree --widget-blueprint-path /Game/UI/WBP_HUD
ue-cli add_widget --widget-blueprint-path /Game/UI/WBP_HUD --widget-class TextBlock \
  --parent-widget-name RootCanvas --widget-name TitleText \
  --widget-properties '{"Text":"Hello World"}'

診断

# Check entire setup
ue-cli doctor

# Output:
#   [ok] Project            MyProject/MyProject.uproject
#   [ok] Plugin directory   Plugins/UnrealMCP/ exists
#   [ok] Plugin source      Source/UnrealMCPBridge/ exists
#   [ok] UProject entry     UnrealMCP plugin listed and enabled
#   [ok] Port file          port 55557
#   [ok] TCP connection     Connected to 127.0.0.1:55557
#   [ok] Health check       Bridge is responsive
#   All checks passed. ue-cli is ready to use.

MCP サーバーのセットアップ

Model Context Protocol（Cursor、Windsurf、VS Code など）を使用する AI ツール向けです。

要件

• Unreal Engine 5.7（5.7 でテスト済み。以前の 5.x バージョンでも動作する可能性があります）
• Python 3.10+
• UE5 プラグイン（.uplugin によって自動的に有効化されます）：
  • PythonScriptPlugin
  • EditorScriptingUtilities
  • EnhancedInput

インストール

pip install unrealmcp

セットアップスクリプト（手動設定の代替）

セットアップスクリプトは unrealmcp pip パッケージをインストールし、使用する AI ツールの MCP 設定を自動的に作成します。

Windows：

cd Plugins\UnrealMCP
install.bat

macOS / Linux：

cd Plugins/UnrealMCP
bash install.sh

スクリプトでは、MCP 設定の作成場所を選択します。

AI ツールの設定

{
  "mcpServers": {
    "unreal": {
      "type": "stdio",
      "command": "unrealmcp"
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "servers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

{
  "servers": [
    {
      "name": "unreal",
      "command": "unrealmcp"
    }
  ]
}

{
  "context_servers": {
    "unreal": {
      "source": "custom",
      "command": { "path": "unrealmcp" }
    }
  }
}

{
  "mcpServers": {
    "unreal": {
      "command": "unrealmcp"
    }
  }
}

全 288 コマンド

コア（2）

アセット管理（16）

ブループリント（22）

マテリアル（35）

データテーブル（8）

データアセット（12）

アクターとレベル（19）

Enhanced Input（21）

ウィジェット — UMG（11）

Niagara VFX（96）

エンドツーエンドでNiagaraを作成できます。スタック全体の読み取り、トップレベルまたはネストされた任意のバインディングの変更、スクラッチパッドのダイナミック入力の一からの作成、データインターフェースのメンバー関数を含む任意のグラフノードのスポーン、さらにエディターのドロップダウンで公開されるすべての有効なオプションの検出が可能です。Niagaraのエクスポート済みViewModel／Stack Graph APIを基盤とし、エクスポートされていないヘルパーを安全に再現します。

システム

エミッター

モジュール（Spawn／Update／Render スタック）

スタック入力バインディングのループ

パラメーターとバインディング

レンダラー

スクラッチパッド — CRUD と適用

スクリプトのプロパティ（詳細パネル）

スクリプトパラメーター（入力／出力）

グラフのイントロスペクション

グラフノードの CRUD

ピンの管理

カスタム HLSL

イベントとシミュレーションステージ

レベルへのスポーン

検索（推測不要の作成）

StateTree（33、新規）

StateTree アセットの読み取りと作成に対応します — ステート、タスク、評価器、トランジション、条件、パラメーター、バインディングを扱います。スキーマを認識し、StateTreeSchemaBase と Mass スキーマの両方で動作します。

読み取り

作成

変更

削除

検索

パフォーマンスのプロファイリング（3）

デバッグ（2）

使用例

これらは CLI と MCP サーバーの両方で動作します。CLI では、AI が Bash 経由で ue-cli を呼び出します。MCP では、AI がツールを直接呼び出します。

マテリアルの作成

Create a red metallic material at /Game/Materials/M_RedMetal
with roughness 0.3 and metallic 1.0

AI は create_material を呼び出し、続いて build_material_graph を呼び出して、定数ノードを Base Color、Metallic、Roughness ピンに接続します。

アクターのスポーン

Spawn 5 point lights in a circle around the origin at height 300

AI は、計算した位置を指定して actor_type: "PointLight" の spawn_actor を 5 回呼び出します。

ブループリントの作成

Create a Blueprint actor called BP_HealthPickup based on Actor,
add a Sphere Collision component and a Static Mesh component,
set it up so on BeginOverlap it prints "Health Picked Up"

AI は create_blueprint、add_component_to_blueprint、add_event_node、add_blueprint_node、connect_blueprint_nodes を使用します。

パフォーマンスのプロファイリング

Start a performance trace, play for 10 seconds, stop it,
then diagnose the bottlenecks

AI は performance_start_trace を呼び出し、待機してから performance_stop_trace を呼び出し、その後 query: "diagnose" を指定して performance_analyze_insight を呼び出します。

データテーブルの管理

Show me the schema of DT_Items, then add a new row called
"IronIngot" with StackSize 100

AI は get_data_table_schema を呼び出し、続いて適切なデータを指定して add_data_table_row を呼び出します。

設定

カスタムポート

Config/DefaultEngine.ini に追加します：

[UnrealMCP]
Port=55557

環境変数

# Force a specific port (overrides port file)
set UNREAL_MCP_PORT=55560

複数のエディターインスタンス

各エディターは固有のポートを自動的に選択します。CLI と MCP サーバーは Saved/UnrealMCP/port.txt からポートを読み込みます。特定のインスタンスを指定するには、--port フラグまたは UNREAL_MCP_PORT 環境変数を使用します。

アーキテクチャ

プラグイン構成

Plugins/UnrealMCP/
├── UnrealMCP.uplugin              # Plugin manifest
├── cli/                            # Go CLI source (ue-cli)
│   ├── cmd/                        # Command definitions (288 commands)
│   ├── internal/bridge/            # TCP client
│   ├── internal/project/           # Plugin embedding & project detection
│   └── npm/                        # npm package wrapper
├── unrealmcp/                      # Python MCP server
│   ├── _tcp_bridge.py              # TCP communication
│   └── tools/                      # Tool modules (one per category)
├── Source/UnrealMCPBridge/         # C++ editor plugin
│   ├── Public/                     # Headers
│   └── Private/                    # Implementation + command handlers
└── .github/workflows/release.yml   # CI: builds + GitHub Release + npm publish

通信プロトコル

長さプレフィックス方式のフレーミングを使用する TCP：

[4 bytes: big-endian payload length] [N bytes: UTF-8 JSON]

リクエスト：{"type": "command_name", "params": {...}} レスポンス：{"status": "success", "result": {...}}

カスタムコマンドの追加

CLI 側（Go）

適切な cmd/*.go ファイルに CommandSpec を追加します：

{
    Name:    "my_command",
    Group:   "mygroup",
    Short:   "What it does",
    Long:    "Detailed description.",
    Example: "ue-cli my_command --param value",
    Params: []ParamSpec{
        {Name: "param", Type: "string", Required: true, Help: "Description"},
    },
},

MCP 側（Python）

unrealmcp/tools/ に新しいファイルを作成します：

# unrealmcp/tools/my_tools.py
from unrealmcp._bridge import mcp
from unrealmcp._tcp_bridge import _call

@mcp.tool()
def my_command(param: str) -> str:
    """Description shown to the AI assistant."""
    return _call("my_command", {"param": param})

unrealmcp/tools/__init__.py に登録します：

from unrealmcp.tools import my_tools  # noqa: F401

C++ 側

Source/UnrealMCPBridge/Private/Commands/ にコマンドハンドラーを追加し、ExecuteCommand() に登録します。

対応する AI ツール

トラブルシューティング

リリースと配布

リリースは GitHub Actions によって自動化されています。タグをプッシュすると、次の処理が実行されます：

git tag v1.2.2 && git push origin v1.2.2
# → Builds 5 platform binaries
# → Creates GitHub Release
# → Publishes to npm + PyPI

コントリビューション

• バグの報告 Issue を作成
• 機能のアイデア Issue を作成
• コードの変更 フォークして変更を加え、PR を作成してください

ガイドラインについては、CONTRIBUTING.mdをご覧ください。

エンタープライズおよびスタジオとの連携

Unreal MCP をスタジオの制作パイプラインに統合したいですか？このツールを基盤に、AI を活用したカスタムワークフローを構築するため、ゲームスタジオと直接連携しています。

提供内容：

• パイプライン統合 — Unreal MCP を既存のビルドシステム、CI/CD、チームのワークフローに導入し、すべてのアーティストと開発者が、Unreal プロジェクトですぐに AI アシスタントを利用できるようにします
• カスタムツールの開発 — オープンソース版では対応していない、スタジオ独自の形式や内部ツール、具体的な制作ニーズに合わせた MCP コマンドを構築します
• AI ワークフローの設計 — マテリアル作成からレベルデザイン、アセットパイプラインまで、Unreal Engine でチームが AI アシスタント（Claude、Cursor、Copilot）を活用する方法を設計・実装します
• 高度なマテリアルおよび Substrate システム — プロシージャルなマテリアル生成、Substrate ワークフロー、複雑なシェーダーパイプラインを MCP で完全に自動化します

お問い合わせ：

• メール：[email protected]
• LinkedIn：linkedin.com/in/aadeshyadav
• Discord：destroyerpal
• ポートフォリオ：aadeshyadav.vercel.app

カスタム開発とサポート

Unreal プロジェクトについてサポートが必要ですか？ゲームプレイやマルチプレイヤーから、エディターツールや Mass Entity システムまで、UE5 C++ スタック全般の契約業務に対応しています。詳細はSUPPORT.mdをご覧ください。

[email protected] · LinkedIn · ポートフォリオ · Discord：destroyerpal

ライセンス

MPL-2.0 — 詳細はLICENSEをご覧ください。