convez.ai
MCP ServerAutomaçãoIntermediário
GenOrca

Unreal MCP

GenOrca/unreal-mcp

Controle Unreal Engine 5 com IA via Model Context Protocol

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que conecta assistentes de IA diretamente ao Unreal Engine 5, permitindo controlar o editor via Claude com 224 ações em 19 domínios. Suporta criação de atores, Blueprints, árvores de comportamento, widgets UMG, materiais e cinemática via linguagem natural, com extensibilidade em Python e C++.

Instalação

$npx convez-ai GenOrca/unreal-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
149
Forks
18
Acompanhando
3
Saúde
37%
Último commit
há 4 meses
Versão
v2.2.0
Issues abertas
11
Contribuidores
1

Casos de uso

  • Automação de tarefas repetitivas no Unreal Editor
  • Desenvolvimento de ferramentas de game design assistidas por IA
  • Prototipagem rápida de cenas, atores e comportamentos
  • Geração de gráficos de Blueprint e materiais via descrição textual

Veredito

Ferramenta robusta e bem arquitetada para automação do Unreal Editor via IA. A abordagem de namespace tools, extensibilidade em Python e fallback em C++ demonstra maturidade; a falta de documentação portuguesa é irrelevante frente ao valor técnico oferecido.

README

A tradução para o português deste README ainda está na fila.


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.

224 actions across 19 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 for the step-by-step workflow.

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.

DomainCapabilitiesActions
actorSpawn (class/object/surface raycast), transform get/set, properties, live component properties, hierarchy (attach/detach), folders, tags, bounds, selection, duplication, class queries.36
materialCreate materials & instances, author expression graphs, connect to material properties, MI parameters (scalar/vector/texture/switch), reparent, auto-layout, introspection.20
assetDuplicate/rename/delete/save, list, dependencies & referencers, metadata tags, directories, search, FBX import/export, texture import.19
blueprintCreate Blueprints, read/build graphs, add/connect/remove nodes, member variables (+ flags), SCS components, compile, auto-layout.19
animationAnimSequence info, notify tracks, sync markers, float curves; SkeletalMesh sockets & bones (C++-backed); skeleton info.17
utilRun arbitrary Unreal Python, console commands & CVars, viewport camera, PIE control, project info, class/enum reflection, output log, LiveCoding compile.15
level_sequenceCreate cinematics, camera with Camera Cut track, spawnable/possessable bindings, transform & skeletal-anim tracks, keyframes, Sequencer open/close.13
behavior_treeCreate & read Behavior Trees, Blackboard keys, build complete BT hierarchies.12
static_meshMesh info (LODs/tris/verts), LOD generation & reuse, materials, collision (simple/convex/per-LOD).12
umgCreate Widget Blueprints, add/remove widgets (15 types), properties, slot layout, text style, compile.10
editorSelection, material/mesh replacement, Blueprint-based replacement, actor merge/join, Proxy Geometry baking.9
data_tableCreate DataTables, read/write rows (JSON/CSV), columns, row management.8
levelCreate/open levels, list actors, world settings, current-level path, save.7
control_rigCreate Control Rigs (bones imported from a mesh), hierarchy authoring, RigVM unit nodes, recompile.6
layerCreate/delete layers, assign actors, list layer contents.6
retargetIK Rig & IK Retargeter authoring, chain auto-mapping, batch animation retargeting.6
gameGame mode, Enhanced Input actions & mappings.3
textureTexture info, sRGB and compression settings.3
visionCapture 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_<name>(...) function (returning a JSON string) to a domain module in Plugins/UnrealMCPython/Content/Python/UnrealMCPython/<domain>_actions.py.
  2. Run python generate_catalog.py — the action is now exposed by its domain tool.
  3. (Optional) add an in-editor test in tests/test_<domain>.py.

The Python path needs no C++ and no editor rebuild. New domain? Drop in a <domain>_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.

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)

Download the latest zip from Releases and extract it anywhere. Then copy Plugins/UnrealMCPython/ into your project's Plugins/ folder:

YourProject/
└── Plugins/
    └── UnrealMCPython/
        ├── Source/
        ├── Content/
        └── UnrealMCPython.uplugin

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

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.

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

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

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

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

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

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

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 · set_viewport_camera · start_pie · stop_pie

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

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

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

add_widget · compile_widget_blueprint · create_widget_blueprint · get_widget_blueprint_info · get_widget_property · remove_widget · set_slot_layout · set_text_style · set_widget_properties · set_widget_property

Widget types: CanvasPanel, TextBlock, Button, Image, HorizontalBox, VerticalBox, Border, Overlay, ScrollBox, SizeBox, CheckBox, EditableText, EditableTextBox, ProgressBar, Slider

create_proxy_actor · get_selected_assets · join_actors · merge_actors · replace_mesh_on_selected · replace_mesh_on_specified · replace_mtl_on_selected · replace_mtl_on_specified · replace_selected_with_bp

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

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

add_rig_bone · add_rig_null · add_unit_node · create_control_rig · get_control_rig_info · recompile_control_rig

add_actor_to_layer · create_layer · delete_layer · get_actors_in_layer · list_layers · remove_actor_from_layer

add_retarget_chain · auto_map_chains · batch_retarget · create_ik_rig · create_retargeter · get_ik_rig_info

add_input_action · add_input_mapping · set_game_mode

get_texture_info · set_texture_compression · set_texture_srgb

capture_actors · capture_from · capture_viewport

Troubleshooting

ProblemSolution
MCP server not startingVerify Python 3.11+ and uv are installed
Path errorsCheck the absolute path in your client config
Plugin not visibleRestart UE and confirm both plugins are enabled
Tools not showingRestart your MCP client and verify the config
An action errors on paramsCall { "action": "list_actions" } on that domain to see exact parameter names

Contributing

Issues, feature requests, and pull requests are welcome on GitHub. See CLAUDE.md for the architecture and the workflow for adding new actions.

License

Apache-2.0

Ver o original no GitHub

Bom para

Relacionados