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.

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

	Community (this repo)	CodeFizz Editor Agent (Pro)
Commands	288	900+
Categories	15	28
Engine support	Build it yourself	5.6, 5.7, 5.8
Blueprints, Materials, Niagara, StateTree	Yes	Yes, and deeper
Control Rig, PCG, Sequencer	No	Yes
Mutable, Procedural Vegetation	No	Yes
Audio, MetaSounds, Sound Cues	No	Yes
Behavior Trees, EQS	No	Yes
Insights profiling	Basic	Full trace analysis
Install	Clone, build, configure	One command, no compiler needed
Updates	Community pace	Shipped continuously
Support	GitHub issues	Priority, private Discord

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

	CLI	MCP Server
Install	npm install -g unrealcli	pip install unrealmcp
Dependencies	None (single binary)	Python 3.10+
Works with	Claude Code (via Bash)	Claude Code, Cursor, Windsurf, VS Code, Gemini CLI, Rider, Zed, Amazon Q
Protocol	Direct TCP	MCP over stdio

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. 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

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 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)

---

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 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

Usage

# 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 -

Help & Discovery

# 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

Global Flags

Flag	Description
--port <int>	TCP port override (default: auto-discover from port file)
--timeout <int>	Timeout in seconds (default: 30, large ops: 300)
--json <string>	Full params as JSON string (use - for stdin)
--version	Print version

Key Commands

Assets

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

Blueprints

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

Materials

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

Data Tables

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}'

Actors & Level

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

Performance Profiling

# 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 (Surgical Editing)

# 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

Widgets (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"}'

Diagnostics

# 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 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\UnrealMCP
install.bat

macOS / Linux:

cd Plugins/UnrealMCP
bash install.sh

The script asks where to create the MCP config:

Scope	What it does	When to use
Project	Creates config next to your .uproject	Only want UnrealMCP in this project
Global	Creates config in your user folder	Want UnrealMCP in all projects

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

Category	Count	Highlights
Core	2	health_check, execute_python
Asset Management	16	find/list/import/duplicate/rename/delete/save
Blueprints	22	create, compile, variables, functions, graph nodes
Materials	35	create, build_material_graph, material functions, Substrate
Data Tables	8	full CRUD on rows + schema introspection
Data Assets	12	data assets + surgical Mass Config trait editing
Actors & Level	19	spawn, transform, properties, screenshot
Enhanced Input	21	actions, mapping contexts, triggers, modifiers
Widgets — UMG	11	widget tree, add/move/rename, slot props
Niagara VFX	96	systems, emitters, stack bindings (nested), scratch pad authoring, graph CRUD, DI member functions, source-menu discovery
StateTree	33	states, tasks, evaluators, transitions, conditions, bindings
Performance Profiling	3	record .utrace + smart analysis (diagnose/spikes/flame)
Debug	2	token tracking, debug toggle

Core (2)

Command	Description
health_check	Verify the bridge is running
execute_python	Run arbitrary Python in the editor

Asset Management (16)

Command	Description
find_assets	Search Asset Registry by class/path/name
list_assets	List assets in a directory
get_asset_info	Asset metadata
get_asset_properties	All editable properties
set_asset_property	Set a property
find_references	Find dependents/dependencies
import_asset	Import external file (PNG, FBX, etc.)
import_assets_batch	Batch import
duplicate_asset	Copy to new location
rename_asset	Rename/move (auto-fix references)
delete_asset	Delete (checks references)
save_asset / save_all	Save dirty assets
open_asset	Open in editor
sync_browser	Navigate Content Browser
get_selected_assets	Currently selected assets

Blueprints (22)

Command	Description
search_parent_classes	Find valid parent classes
create_blueprint	Create from any parent class
compile_blueprint	Compile
read_blueprint_content	Full structure readout
analyze_blueprint_graph	Graph analysis
add_component_to_blueprint	Add component
create/get/set_blueprint_variable	Variable management
set_blueprint_variable_properties	Modify variable settings
create/delete/rename_blueprint_function	Function management
add_function_input/output	Function parameters
get_blueprint_function_details	Function inspection
get/set_blueprint_class_defaults	CDO properties
add_blueprint_node	Add graph node (23+ types)
add_event_node	Add event (BeginPlay, Tick, etc.)
connect_blueprint_nodes	Wire nodes together
delete_blueprint_node	Remove node
set_blueprint_node_property	Edit node properties

Materials (35)

Command	Description
create_material	Create with blend/shading mode
create_material_instance	Create with parameter overrides
build_material_graph	Build complete node graph atomically
get_material_info	Inspect properties/params/textures
set_material_properties	Bulk-set material properties
add/delete/move/duplicate_material_expression	Manage nodes
connect_material_expressions	Wire nodes
set_material_expression_property	Set node property
disconnect_material_expression	Break connection
layout_material_expressions	Auto-layout
recompile_material	Force recompile
get_material_errors	Compilation errors
get/set_material_instance_parameter	MI parameter overrides
list_material_expression_types	Discover node types
get_expression_type_info	Node pins & properties
search_material_functions	Find Material Functions
validate_material_graph	Diagnose issues
trace_material_connection	Trace data flow
cleanup_material_graph	Remove orphaned nodes
add_material_comments	Comment boxes
create/get_material_function	Material Function management
build_material_function_graph	Build MF graph
add/set_material_function_input/output	MF pins
validate/cleanup_material_function	MF diagnostics
apply_material_to_actor/blueprint	Apply materials
get_available_materials	List materials
get_actor/blueprint_material_info	Material slot info

Data Tables (8)

Command	Description
get_data_table_schema	Column names and types
get_data_table_rows / get_data_table_row	Read rows
add_data_table_row	Add with initial data
update_data_table_row	Partial update
delete_data_table_row	Delete row
duplicate_data_table_row	Copy row
rename_data_table_row	Rename row

Data Assets (12)

Command	Description
create_data_asset	Create any UDataAsset subclass
get/set_data_asset_property(ies)	Read/write properties (single or batch)
list_data_assets	Browse by path/class
list_data_asset_classes	Discover all loaded UDataAsset subclasses
get_property_valid_types	Valid dropdown values for a property slot
search_class_paths	Find class paths
get_mass_config_traits	Inspect all traits on a Mass Entity Config asset
add_mass_config_trait	Append a new trait to a Mass Config (non-destructive)
set_mass_config_trait_property	Surgical in-place edit of a single trait property — never replaces the Traits array
remove_mass_config_trait	Remove a single trait by index or class without affecting siblings

Actors & Level (19)

Command	Description
spawn_actor	Spawn built-in actor types
spawn_blueprint_actor	Spawn BP actor
spawn_actor_from_class	Spawn from class name
get_actors_in_level	List all actors
find_actors_by_name	Search by name pattern
get_actor_properties	Read actor properties
set_actor_transform	Set location/rotation/scale
delete_actor	Remove from level
get_selected_actors	Viewport selection
get_world_info	Level info
set_static_mesh_properties	Mesh assignment
set_physics_properties	Physics config
set_mesh_material_color	Material color
apply_material_to_actor/blueprint	Apply material
get_actor/blueprint_material_info	Material slots
get_available_materials	List materials
take_screenshot	Capture viewport

Enhanced Input (21)

Command	Description
create_input_action	Create UInputAction
get/set_input_action_properties	Action properties
add/remove_input_action_trigger	Action triggers
add/remove_input_action_modifier	Action modifiers
list_input_actions	Browse actions
create_input_mapping_context	Create UInputMappingContext
get_input_mapping_context	Read mappings
add/remove/set_key_mapping	Key bindings
add/remove_mapping_trigger/modifier	Per-mapping overrides
list_input_mapping_contexts	Browse contexts
list_trigger_types / list_modifier_types	Discover types
list_input_keys	Valid key names

Widgets — UMG (11)

Command	Description
get_widget_tree	Widget hierarchy
add_widget	Add to parent
remove/move/rename/duplicate_widget	Widget operations
get/set_widget_properties	Widget properties
get/set_slot_properties	Layout slot properties
list_widget_types	Available widget classes

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

Command	Description
create_niagara_system	Create from emitter template or empty
get_niagara_system_info	System metadata, emitters, parameters
list_niagara_systems	Browse Niagara systems by path
delete_niagara_system	Delete a system
compile_niagara_system	Force recompile
set_niagara_system_property	Set top-level system property
get_niagara_system_errors	Compilation errors / warnings
get_niagara_particle_stats	Per-emitter particle stats
get/set_niagara_playback_range	Preview playback range