Unreal Mcp

Unreal MCP

Connect AI assistants directly to the Unreal Editor via MCP

Features · How Tools Work · Extending · Installation · Usage · Tools Reference · Troubleshooting

---

Unreal MCP connects AI assistants to the Unreal Editor through the Model Context Protocol. Spawn actors, build Blueprint graphs, construct Behavior Trees, design UMG widgets, edit materials, author cinematics — all from natural language.

253 actions across 21 domains, plus execute_python as an escape hatch — run any BlueprintCallable function or editor subsystem the engine exposes to Python, on the fly.

Easy to extend. Adding an action is a Python function plus a catalog regen — no C++ and no editor rebuild on the Python path. When you need something Python doesn't expose (e.g. reference-skeleton bones), an optional C++ helper layer is there too. See [CLAUDE.md](CLAUDE.md) for the step-by-step workflow.

Click to watch the demo on YouTube

Features

Each row is one namespace tool. The action set is large but the tool list stays small, so it never bloats the model's context. 253 actions across 21 domains.

| Domain | Capabilities | Actions | |---|---|:---:| | actor | Spawn (class/object/surface raycast), transform get/set, properties, live component properties, hierarchy (attach/detach), folders, tags, bounds, selection, duplication, class queries. | 36 | | asset | Duplicate/rename/delete/save, list, dependencies & referencers, metadata tags, directories, search, FBX import/export, texture import, glTF/glb import. | 21 | | material | Create materials & instances, author expression graphs, connect to material properties, MI parameters (scalar/vector/texture/switch), reparent, auto-layout, introspection. | 20 | | blueprint | Create Blueprints, read/build graphs, add/connect/remove nodes, member variables (+ flags), SCS components, compile, auto-layout. | 19 | | util | Run arbitrary Unreal Python, console commands, CVar get/set, world↔screen projection, viewport camera, PIE control, project info, class/enum reflection, output log, log verbosity, LiveCoding compile. | 19 | | animation | AnimSequence info, notify tracks, sync markers, float curves; SkeletalMesh sockets & bones (C++-backed); skeleton info. | 17 | | umg | Create Widget Blueprints, add/remove widgets, reparent/wrap/replace, properties, slot layout, text style, event binding, compile. | 15 | | levelsequence | Create cinematics, camera with Camera Cut track, spawnable/possessable bindings, transform & skeletal-anim tracks, keyframes, Sequencer open/close. | 13 | | behaviortree | Create & read Behavior Trees, Blackboard keys, build complete BT hierarchies. | 12 | | editor | Selection, material/mesh replacement, Blueprint-based replacement, actor merge/join, Proxy Geometry baking, asset-editor open/get/close. | 12 | | staticmesh | Mesh info (LODs/tris/verts), LOD generation & reuse, materials, collision (simple/convex/per-LOD). | 12 | | gas | Gameplay Ability System: Ability/Effect Blueprint authoring, effect modifiers, costs & cooldowns, gameplay tags. | 11 | | datatable | Create DataTables, read/write rows (JSON/CSV), columns, row management. | 8 | | level | Create/open levels, list actors, world settings, current-level path, save. | 7 | | controlrig | Create Control Rigs (bones imported from a mesh), hierarchy authoring, RigVM unit nodes, recompile. | 6 | | layer | Create/delete layers, assign actors, list layer contents. | 6 | | retarget | IK Rig & IK Retargeter authoring, chain auto-mapping, batch animation retargeting. | 6 | | animblueprint | Create Animation Blueprints (skeleton-bound), AnimGraph sequence player + locomotion state machine authoring (C++-backed). | 4 | | game | Game mode, Enhanced Input actions & mappings. | 3 | | texture | Texture info, sRGB and compression settings. | 3 | | vision | Capture the viewport / any pose / auto-framed actors as MCP Images with on-image actor labels — the assistant sees and identifies the scene. | 3 |

How Tools Work

Each domain is a single MCP tool. You call it with an action name and a params object:

// tool: "actor"
{ "action": "spawn_from_class",
  "params": { "class_path": "/Script/Engine.PointLight", "location": [0, 0, 200] } }

To discover what a domain can do and the exact parameters each action takes, pass list_actions:

// tool: "material"
{ "action": "list_actions" }
// → { "actions": { "create_expression": { "params": "...", "doc": "..." }, ... } }

Need something not covered by a built-in action? Use util / execute_python to run any Unreal Python directly — the full engine API is available with no C++ build.

Extending

Adding a tool is intentionally low-friction — anyone comfortable with Python can do it:

1. Add a ue_(...) function (returning a JSON string) to a domain module in

Plugins/UnrealMCPython/Content/Python/UnrealMCPython/_actions.py.

1. Run python generate_catalog.py — the action is now exposed by its domain tool.
2. (Optional) add an in-editor test in tests/test_.py.

The Python path needs no C++ and no editor rebuild. New domain? Drop in a _actions.py and list it in the generator. For an API that Python doesn't expose, an optional C++ helper (MCPythonHelper) is available. Full details in [CLAUDE.md](CLAUDE.md).

Installation

Prerequisites

• Unreal Engine 5.6+
• Python 3.11+
• uv — fast Python package manager
• An MCP client (Claude Desktop, VS Code, Cursor, etc.)

Step 1 — Install the Plugin

Option A: Download from GitHub Releases (Recommended)

Each release ships two kinds of plugin asset. Most users want the precompiled one for their exact engine version:

• ✅ UnrealMCPython__.zip (e.g. UnrealMCPython_5.8_2.2.0.zip) — precompiled for that exact UE version. No C++ toolchain, no rebuild — just drop it in and launch. Pick the one matching your engine version.
• 🛠️ UnrealMCPython_Source_.zip — source only, for C++ developers (the CI release pipeline runs on Linux and does not compile the C++ module). Unreal tries to compile it on first open, which requires Visual Studio with the "Game development with C++" workload. Without that toolchain the build fails and the editor closes — so don't use this one unless you intend to compile.

Extract, then copy Plugins/UnrealMCPython/ into your project's Plugins/ folder:

YourProject/
└── Plugins/
    └── UnrealMCPython/
        ├── Binaries/   (precompiled zip only)
        ├── Source/
        ├── Content/
        └── UnrealMCPython.uplugin

Keep the mcp-server/ folder from the zip in a convenient location — you'll need its path in Step 3.

> [!NOTE] > Precompiled binaries are engine-version-specific. If there's no __ zip for your version, either ask for one in an issue or use the source zip and let Unreal compile it on first open (Windows: Visual Studio with the "Game development with C++" workload). Maintainers build the per-version binaries locally with tools/build-plugin.ps1 (the CI pipeline can't — GitHub-hosted runners have no Unreal Engine).

> [!WARNING] > Seeing 'UnrealMCPython' was designed for build 5.7.0 … load anyway? or a rebuild that fails and closes the editor? You downloaded the source zip (or a binary for a different engine version). Download the UnrealMCPython__.zip that matches your engine instead — it loads without compiling. (Source builds from releases ≤ 2.2.0 also pin an old engine version; this is fixed on main.)

Option B: Install from Fab

> [!NOTE] > The Fab version may lag behind the latest GitHub release. After installing from Fab, you still need the mcp-server/ folder from this repository.

Step 2 — Enable Plugins in Unreal

1. Open your project in Unreal Engine
2. Edit > Plugins — enable Unreal-MCPython and Python Editor Script Plugin
3. Restart the editor

Step 3 — Configure your MCP Client

Add the server to your MCP client config:

{
  "mcpServers": {
    "unreal-mcpython": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/absolute/path/to/unreal-mcp/mcp-server",
        "run",
        "src/unreal_mcp/main.py"
      ]
    }
  }
}

> [!IMPORTANT] > Replace the path with the actual absolute path to your mcp-server folder.

Config file locations by client

| Client | Path | |---|---| | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | VS Code / Cursor | .vscode/mcp.json in your workspace |

Step 4 — Connect

1. Restart your MCP client
2. The MCP server starts automatically
3. Verify — you should see the 19 Unreal-MCPython domain tools listed in your client

Usage

Just describe what you want in natural language:

"Place 10 trees randomly on the terrain surface"
"Find all static meshes with 'rock' in the name"
"Create M_Ground, add a Constant3Vector for base color, and connect it"
"Explain what the selected Blueprint nodes do"
"Create BP_Door from Actor, add a bool 'IsOpen' variable exposed on spawn"
"Build a Behavior Tree with a Selector root and MoveTo/Wait tasks"
"Create a HUD widget with a health bar and a 'Score: 0' label"
"Make a 6-second level sequence with a CineCamera flying from (0,0,200) to (1200,600,500)"
"Tag all PointLights in the level and move them to a 'Lighting' layer"

Tools Reference

Pass any action below to its domain tool. Use { "action": "list_actions" } on a domain to see each action's parameters and docs.

actor (36)

add_actor_tag · attach_actor · delete_by_label · detach_actor · duplicate_actor · duplicate_selected · get_actor_bounds · get_actor_folder · get_actor_tags · get_actors_of_class · get_all_details · get_attached_actors · get_component_property · get_in_view_frustum · get_property · get_selected_actors · get_transform · invert_selection · line_trace · list_actor_components · list_all_with_locations · remove_actor_tag · rename_actor · select_actors · select_all · set_actor_folder · set_actor_hidden · set_component_property · set_location · set_property · set_rotation · set_scale · set_transform · spawn_from_class · spawn_from_object · spawn_on_surface_raycast

asset (21)

asset_exists · delete_asset · delete_directory · duplicate_asset · export_fbx · find_by_query · find_referencers · get_asset_info · get_dependencies · get_gltf_import_status · get_metadata_tag · get_static_mesh_details · import_fbx · import_gltf · import_texture · list_assets · make_directory · remove_metadata_tag · rename_asset · save_asset · set_metadata_tag

material (20)

connect_expressions · connect_property · create_expression · create_material · create_material_instance · delete_expression · get_material_info · get_mi_scalar_param · get_mi_static_switch · get_mi_texture_param · get_mi_vector_param · layout_expressions · list_parameters · recompile · set_expression_property · set_instance_parent · set_mi_scalar_param · set_mi_static_switch · set_mi_texture_param · set_mi_vector_param

blueprint (19)

add_blueprint_node · add_component_to_blueprint · add_variable · auto_layout_graph · build_blueprint_graph · compile_blueprint · connect_blueprint_pins · create_blueprint · get_blueprint_graph_info · get_selected_bp_node_infos · get_selected_bp_nodes · list_blueprint_components · list_blueprint_variables · list_callable_functions · remove_blueprint_node · remove_component_from_blueprint · set_blueprint_node_position · set_component_property · set_variable_flags

util (19)

execute_console_command · execute_python · get_cvar · get_output_log · get_project_info · get_viewport_camera · is_in_pie · list_class_properties · list_enum_values · livecoding_compile · print_message · save_all_dirty · screen_to_world · set_cvar · set_log_verbosity · set_viewport_camera · start_pie · stop_pie · world_to_screen

animation (17)

add_float_curve · add_notify_track · add_socket · add_sync_marker · find_socket · get_anim_sequence_info · get_skeletal_mesh_info · get_skeleton_info · list_bones · list_curves · list_notifies · list_notify_tracks · list_sockets · list_sync_markers · remove_curve · remove_notify_track · remove_socket

umg (15)

add_widget · bind_widget_event · compile_widget_blueprint · create_widget_blueprint · get_widget_blueprint_info · get_widget_property · list_widget_events · remove_widget · reparent_widget · replace_widget · set_slot_layout · set_text_style · set_widget_properties · set_widget_property · wrap_widget

level_sequence (13)

add_anim_track · add_camera · add_possessable · add_spawnable_from_class · add_transform_keyframe · add_transform_track · close_sequencer · convert_binding · create_level_sequence · get_sequence_info · open_in_sequencer · remove_binding · set_playback_range

behavior_tree (12)

add_blackboard_key · build_behavior_tree · create_behavior_tree · create_blackboard · get_behavior_tree_structure · get_blackboard_data · get_bt_node_details · get_selected_bt_nodes · list_behavior_trees · list_bt_node_classes · remove_blackboard_key · set_blackboard_to_behavior_tree

editor (12)

close_asset_editor · create_proxy_actor · get_open_assets · get_selected_assets · join_actors · merge_actors · open_editor_for_asset · replace_mesh_on_selected · replace_mesh_on_specified · replace_mtl_on_selected · replace_mtl_on_specified · replace_selected_with_bp

static_mesh (12)

add_simple_collision · get_collision_info · get_lod_screen_sizes · get_static_mesh_info · list_static_mesh_materials · remove_collisions · remove_lods · set_convex_collision · set_lod_for_collision · set_lod_from_static_mesh · set_lods · set_static_mesh_material

gas (11)

add_effect_modifier · add_gameplay_tag · clear_effect_modifiers · create_ability_blueprint · create_effect_blueprint · get_ability_info · get_effect_info · list_gameplay_tags · set_ability_costs · set_ability_tags · set_effect_duration

data_table (8)

create_data_table · does_row_exist · export_to_csv · get_column_names · get_row_names · get_rows_as_json · remove_row · set_rows_from_json

level (7)

create_level · get_current_level_path · list_level_actors · load_level · save_all_levels · save_current_level · set_world_settings

control_rig (6)

add_rig_bone · add_rig_null · add_unit_node · create_control_rig · get_control_rig_info · recompile_control_rig

layer (6)

add_actor_to_layer · create_layer · delete_layer · get_actors_in_layer · list_layers · remove_actor_from_layer

retarget (6)

add_retarget_chain · auto_map_chains · batch_retarget · create_ik_rig · create_retargeter · get_ik_rig_info

anim_blueprint (4)

add_anim_graph_sequence_player · build_anim_state_machine · create_anim_blueprint · get_anim_blueprint_info

game (3)

add_input_action · add_input_mapping · set_game_mode

texture (3)

get_texture_info · set_texture_compression · set_texture_srgb

vision (3)

capture_actors · capture_from · capture_viewport

Troubleshooting

| Problem | Solution | |---|---| | MCP server not starting | Verify Python 3.11+ and uv are installed | | Path errors | Check the absolute path in your client config | | Plugin not visible | Restart UE a

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: GenOrca
• Source: GenOrca/unreal-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.