UnrealMCP — AI Bridge for Unreal Engine 5

UnrealMCP — AI Bridge for Unreal Engine 5

Control the Unreal Engine 5 editor from Claude Code, Cursor, Windsurf, or any MCP client. Build materials, wire Blueprint graphs, author Niagara systems, spawn actors, edit data tables and profile performance, all by asking for it. 288 commands across 15 categories, no leaving your terminal.

[License: MIT] [UE 5.3+] [MCP] [Pro version]

This is the community edition

It is stable and feature complete for what it covers. It is not abandoned, and it is not in active development either: new subsystem work now goes into CodeFizz Editor Agent, the maintained commercial build. Everything here keeps working, issues still get read, and the MIT licence is permanent.

If you want Control Rig, PCG, Sequencer, Mutable, Procedural Vegetation, audio and MetaSounds, Behavior Trees and EQS, or packaged binaries for UE 5.6 / 5.7 / 5.8, that lives in Pro.

Community edition vs Pro

See the full command list → · Docs · 3 day free trial

Already on UE 5.8? Epic now ships a first-party MCP server in 5.8 (Experimental, localhost only). It is worth trying before you buy anything. This repo and Pro both also cover 5.6 and 5.7, which Epic's does not.

Two ways to use this repo

Both talk to the same C++ plugin inside the editor. Use whichever fits your workflow, or both.

Quick Start

Option A: CLI (Recommended for Claude Code)

# 1. Installnpm install -g unrealcli
# 2. Go to any UE5 project and install the plugincd YourProject/ue-cli init
# 3. Open the editor, then verifyue-cli health_check

That's it. No Python, no config files, no MCP setup.

Option B: MCP Server (For Cursor, Windsurf, etc.)

# 1. Clone the plugin into your projectgit clone https://github.com/aadeshrao123/Unreal-MCP.git Plugins/UnrealMCP
# 2. Install the Python MCP serverpip install unrealmcp
# 3. Add to your AI tool's config (see MCP Setup section below)

How It Works

                    ┌──────────────────────────────────────────┐                    │         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... │          └───────────────────┘              └────────────────────┘

The C++ plugin runs inside the editor and exposes 288 commands over TCP. The CLI and MCP server are two different front doors to the same plugin.

CLI Reference

Installation

# From npm (recommended)npm install -g unrealcli
# Or download binary directly from GitHub Releases# https://github.com/aadeshrao123/Unreal-MCP/releases

Platforms: Windows (x64), macOS (Intel + Apple Silicon), Linux (x64 + ARM64)

Setup

# Navigate to your UE5 projectcd 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 worksue-cli doctor

Usage

# Every command follows this pattern:ue-cli <command> [--flag value]
# Examples:ue-cli health_checkue-cli find_assets --class-type material --path /Gameue-cli spawn_actor --name MyCube --type StaticMeshActor --location "[0,0,100]"ue-cli get_data_table_rows --data-table-path /Game/Data/DT_Itemsue-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 -

Help & Discovery

# See all commands grouped by categoryue-cli --help
# See flags for a specific commandue-cli find_assets --help
# Dump all commands with descriptions, flags, and examples (for AI assistants)ue-cli list_commands

Global Flags

Key Commands

Assets

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

Blueprints

ue-cli create_blueprint --name BP_MyActor --parent-class Actorue-cli add_component_to_blueprint --blueprint-path /Game/BP_MyActor --component-class StaticMeshComponentue-cli add_event_node --blueprint-name BP_MyActor --event-name BeginPlayue-cli compile_blueprint --blueprint-name BP_MyActorue-cli read_blueprint_content --blueprint-path /Game/BP_MyActor

Materials

ue-cli create_material --name M_Red --path /Game/Materialsue-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

Data Tables

ue-cli get_data_table_schema --data-table-path /Game/Data/DT_Itemsue-cli get_data_table_rows --data-table-path /Game/Data/DT_Itemsue-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}'

Actors & Level

ue-cli get_actors_in_levelue-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_infoue-cli take_screenshot

Performance Profiling

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

Enhanced Input

ue-cli create_input_action --asset-path /Game/Input/IA_Jump --value-type Booleanue-cli create_input_mapping_context --asset-path /Game/Input/IMC_Defaultue-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 itue-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_Sparksue-cli set_niagara_module_input --asset-path /Game/VFX/NS_Sparks \  --emitter-name Sparks --stack SpawnStack \  --module-name "Spawn Rate" --input-name SpawnRate --value 250ue-cli compile_niagara_system --asset-path /Game/VFX/NS_Sparks
# Spawn it in the levelue-cli spawn_niagara_effect --asset-path /Game/VFX/NS_Sparks --location "[0,0,200]"

StateTree

# Create a StateTree, add a state with a task, compileue-cli create_statetree --asset-path /Game/AI/ST_Enemyue-cli add_statetree_state --asset-path /Game/AI/ST_Enemy --state-name Patrolue-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 (Surgical Editing)

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

Widgets (UMG)

ue-cli get_widget_tree --widget-blueprint-path /Game/UI/WBP_HUDue-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"}'

Diagnostics

# Check entire setupue-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 Server Setup

For AI tools that use the Model Context Protocol (Cursor, Windsurf, VS Code, etc.).

Requirements

• Unreal Engine 5.7 (tested on 5.7, may work on earlier 5.x versions)
• Python 3.10+
• UE5 Plugins (enabled automatically by the .uplugin):
  • PythonScriptPlugin
  • EditorScriptingUtilities
  • EnhancedInput

Install

pip install unrealmcp

Setup Script (Alternative to Manual Config)

The setup script installs the unrealmcp pip package and creates the MCP config for your AI tool automatically.

Windows:

cd Plugins\UnrealMCPinstall.bat

macOS / Linux:

cd Plugins/UnrealMCPbash install.sh

The script asks where to create the MCP config:

Configure Your AI Tool

{  "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"    }  }}

All 288 Commands

Core (2)

Asset Management (16)

Blueprints (22)

Materials (35)

Data Tables (8)

Data Assets (12)

Actors & Level (19)

Enhanced Input (21)

Widgets — UMG (11)

Niagara VFX (96)

End-to-end Niagara authoring — read the full stack, mutate any binding (top-level or nested), author scratch-pad dynamic inputs from scratch, spawn arbitrary graph nodes including data-interface member functions, and discover every valid option the editor's dropdowns expose. Built on Niagara's exported ViewModel / Stack Graph APIs with safe replication of non-exported helpers.

Systems

Emitters

Modules (Spawn / Update / Render stacks)

Stack Input Binding Loop

Parameters & Bindings

Renderers

Scratch Pad — CRUD & Apply

Script Properties (Details Panel)

Script Parameters (Input / Output)

Graph Introspection

Graph Node CRUD

Pin Management

Custom HLSL

Events & Simulation Stages

Level Spawning

Discovery (zero-guess authoring)

StateTree (33, NEW)

Read and author StateTree assets — states, tasks, evaluators, transitions, conditions, parameters, and bindings. Schema-aware: works with both StateTreeSchemaBase and Mass schema variants.

Reading

Authoring

Modification

Removal

Discovery

Performance Profiling (3)

Debug (2)

Usage Examples

These work with both the CLI and MCP server. With the CLI, the AI calls ue-cli via Bash. With MCP, the AI calls tools directly.

Create a Material

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

The AI will call create_material, then build_material_graph to wire up constant nodes to Base Color, Metallic, and Roughness pins.

Spawn Actors

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

The AI will call spawn_actor with actor_type: "PointLight" five times with calculated positions.

Blueprint Creation

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"

The AI will use create_blueprint, add_component_to_blueprint, add_event_node, add_blueprint_node, and connect_blueprint_nodes.

Profile Performance

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

The AI will call performance_start_trace, wait, performance_stop_trace, then performance_analyze_insight with query: "diagnose".

Data Table Management

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

The AI will call get_data_table_schema, then add_data_table_row with the appropriate data.

Configuration

Custom Port

Add to Config/DefaultEngine.ini:

[UnrealMCP]Port=55557

Environment Variable

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

Multiple Editor Instances

Each editor picks a unique port automatically. The CLI and MCP server read the port from Saved/UnrealMCP/port.txt. Use --port flag or UNREAL_MCP_PORT env var to target a specific instance.

Architecture

Plugin Structure

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

Communication Protocol

TCP with length-prefix framing:

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

Request: {"type": "command_name", "params": {...}} Response: {"status": "success", "result": {...}}

Adding Custom Commands

CLI Side (Go)

Add a CommandSpec to the appropriate cmd/*.go file:

{    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 Side (Python)

Create a new file in unrealmcp/tools/:

# unrealmcp/tools/my_tools.pyfrom unrealmcp._bridge import mcpfrom 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})

Register it in unrealmcp/tools/__init__.py:

from unrealmcp.tools import my_tools  # noqa: F401

C++ Side

Add a command handler in Source/UnrealMCPBridge/Private/Commands/ and register it in ExecuteCommand().

Supported AI Tools

Troubleshooting

Releases & Distribution

Releases are automated via GitHub Actions. Push a tag to trigger:

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

Contributing

• Bug? Open an issue
• Feature idea? Open an issue
• Code? Fork, make changes, open a PR

See CONTRIBUTING.md for guidelines.

Enterprise & Studio Integration

Need Unreal MCP integrated into your studio's production pipeline? I work directly with game studios to build custom AI-assisted workflows on top of this tool.

What I offer:

• Pipeline Integration — Set up Unreal MCP within your existing build system, CI/CD, and team workflow so every artist and developer can use AI assistants with your Unreal project out of the box
• Custom Tool Development — Build MCP commands tailored to your studio's proprietary formats, internal tools, and specific production needs that the open-source version doesn't cover
• AI Workflow Design — Design and implement how your team uses AI assistants (Claude, Cursor, Copilot) with Unreal Engine — from material creation to level design to asset pipelines
• Advanced Material & Substrate Systems — Procedural material generation, Substrate workflows, complex shader pipelines — fully automated through MCP

Get in touch:

• Email: [email protected]
• LinkedIn: linkedin.com/in/aadeshyadav
• Discord: destroyerpal
• Portfolio: aadeshyadav.vercel.app

Custom Development & Support

Need help with your Unreal project? I'm available for contract work across the full UE5 C++ stack, from gameplay and multiplayer to editor tooling and Mass Entity systems. See SUPPORT.md for details.

[email protected] · LinkedIn · Portfolio · Discord: destroyerpal

License

MPL-2.0 — see LICENSE for details.