Prerequisites

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

Installation

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_<engine>_<version>.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_<version>.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 _<your engine>_ 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_<your engine>_<version>.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.

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"

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.

<details> <summary>Config file locations by client</summary>

</details>

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.

<details> <summary><strong>actor</strong> (36)</summary>

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

</details>

<details> <summary><strong>asset</strong> (21)</summary>

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

</details>

<details> <summary><strong>material</strong> (20)</summary>

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

</details>

<details> <summary><strong>blueprint</strong> (19)</summary>

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

</details>

<details> <summary><strong>util</strong> (19)</summary>

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

</details>

<details> <summary><strong>animation</strong> (17)</summary>

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

</details>

<details> <summary><strong>umg</strong> (15)</summary>

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

</details>

<details> <summary><strong>level_sequence</strong> (13)</summary>

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

</details>

<details> <summary><strong>behavior_tree</strong> (12)</summary>

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

</details>

<details> <summary><strong>editor</strong> (12)</summary>

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

</details>

<details> <summary><strong>static_mesh</strong> (12)</summary>

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

</details>

<details> <summary><strong>gas</strong> (11)</summary>

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

</details>

<details> <summary><strong>data_table</strong> (8)</summary>

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

</details>

<details> <summary><strong>level</strong> (7)</summary>

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

</details>

<details> <summary><strong>control_rig</strong> (6)</summary>

add_rig_bone · add_rig_null · add_unit_node · create_control_rig · get_control_rig_info · recompile_control_rig

</details>

<details> <summary><strong>layer</strong> (6)</summary>

add_actor_to_layer · create_layer · delete_layer · get_actors_in_layer · list_layers · remove_actor_from_layer

</details>

<details> <summary><strong>retarget</strong> (6)</summary>

add_retarget_chain · auto_map_chains · batch_retarget · create_ik_rig · create_retargeter · get_ik_rig_info

</details>

<details> <summary><strong>anim_blueprint</strong> (4)</summary>

add_anim_graph_sequence_player · build_anim_state_machine · create_anim_blueprint · get_anim_blueprint_info

</details>

<details> <summary><strong>game</strong> (3)</summary>

add_input_action · add_input_mapping · set_game_mode

</details>

<details> <summary><strong>texture</strong> (3)</summary>

get_texture_info · set_texture_compression · set_texture_srgb

</details>

<details> <summary><strong>vision</strong> (3)</summary>

capture_actors · capture_from · capture_viewport

</details>

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

Troubleshooting