Skip to main content
Glama
unreal-engine-mcp

unreal-engine-mcp

by harn3ss

unreal-engine-mcp

A Model Context Protocol (MCP) server that gives AI agents (Claude Desktop/Code, Cursor, any MCP client) broad control over Unreal Engine 5.7 — spawning and editing actors, managing assets and levels, creating Blueprints and materials, capturing screenshots, running headless builds and automation tests, and executing arbitrary editor Python.

It is designed to reach the whole engine, not a fixed menu of features: a small set of typed tools cover the common operations, and search_unreal_classes

  • introspect_unreal_class + execute_python let an agent discover and drive anything else the unreal Python module exposes — including features added by enabled plugins (Niagara, PCG, Landscape, Sequencer, Gameplay Ability System, Chaos, MetaHuman, …).

Status: functional reference implementation. The host-side code is tested and the server boots and registers all tools. The live-editor paths require a running UE 5.7 editor with the bridge installed — see docs/SETUP.md. No interactive editor was available in the authoring environment, so live calls have not been smoke-tested end to end; treat the engine-side behaviour as "implemented against the documented API" rather than "verified on a running editor".

Why this design

Unreal exposes three external control surfaces; this server uses all three:

Surface

What it is

Used for

Remote Control API (HTTP :30010)

Built-in plugin: REST routes to read/write properties and call UFunctions, including the Python library CDO.

Live editor control + the Python channel.

Python (unreal module)

Reflects ~everything exposed to Blueprints; grows as you enable plugins.

The universal capability layer, reached through Remote Control.

UnrealEditor-Cmd (headless)

Commandlets / automation in a short-lived process.

Builds, cooks, packaging, automation tests.

The key idea: instead of compiling a bespoke C++ plugin, we drive the editor's own Python interpreter over the Remote Control HTTP API, and ship a tiny UE-side Python bridge (ue_mcp_bridge, pure .py) that returns structured JSON so round-trips are reliable. No C++ compilation required — only built-in plugins.

See docs/ARCHITECTURE.md for the full picture and docs/CAPABILITIES.md for the complete map of what's reachable.

Related MCP server: Hayba

Quick start

  1. In Unreal (5.7): enable the Remote Control API and Python Editor Script Plugin plugins, then restart the editor.

  2. Install the bridge: copy unreal_plugin/Content/Python/ into your project's Content/Python/ folder (so init_unreal.py and ue_mcp_bridge/ sit directly under it). Restart the editor; the Output Log should show [ue_mcp_bridge] ready.

  3. Install the server:

    pip install -e .          # or: pip install -r requirements.txt
    cp .env.example .env      # then edit paths/ports
  4. Register with your MCP client. For Claude Desktop, add to claude_desktop_config.json:

    {
      "mcpServers": {
        "unreal": {
          "command": "unreal-mcp",
          "env": {
            "UE_PROJECT_PATH": "/path/to/MyProject/MyProject.uproject",
            "UE_ENGINE_PATH": "/path/to/UE_5.7"
          }
        }
      }
    }

    (Claude Code: claude mcp add unreal -- unreal-mcp.)

  5. Ask your agent: "Call editor_state" to confirm the connection, then "Spawn a cube at the origin and take a screenshot."

Tool catalogue (35 tools)

Editor & connection — editor_state, run_console_command, save_all Actors — list_actors, get_actor, spawn_actor, spawn_static_mesh, set_actor_transform, set_actor_property, destroy_actor Assets — list_assets, asset_exists, asset_info, import_asset, duplicate_asset, rename_asset, save_asset, delete_asset Levels — new_level, load_level, save_current_level Materials / Blueprints — create_material, create_blueprint, compile_blueprint Rendering — take_screenshot, build_lighting Universal — execute_python, search_unreal_classes, introspect_unreal_class Headless pipeline — run_automation_tests, run_python_file, cook_content Raw Remote Control — rc_get_property, rc_set_property, rc_call_function

Safety

  • .env (and credential files / keys) are gitignored; never commit secrets.

  • UE_MCP_ALLOW_WRITE=false puts the server in read-only mode — mutating tools refuse to run. Useful for exploration or untrusted sessions.

  • execute_python runs arbitrary code in your editor. Only connect MCP clients you trust.

Development

pip install -e ".[dev]"
PYTHONPATH=src python -m pytest tests/ -q     # host-side tests
PYTHONPATH=src python -c "from unreal_mcp.server import build_server; build_server()"

License

MIT — see LICENSE.

Available Tools

35 tools
asset_existsB

Check whether an asset exists at the given object path.

Inputs: asset_path (required). Returns: result

asset_infoB

Return class/package info for an asset.

Inputs: asset_path (required). Returns: result

build_lightingA

Build static lighting for the current level via console.

quality is one of Preview, Medium, High, Production.

Inputs: quality. Returns: result

compile_blueprintD

Compile a Blueprint asset by object path.

Inputs: asset_path (required). Returns: result

cook_contentC

Cook project content for a target platform (Windows, Linux, Mac, Android…).

Inputs: target_platform, timeout_seconds. Returns: result

create_blueprintA

Create a Blueprint asset deriving from parent_class.

parent_class may be an engine class name ('Actor', 'Pawn', 'Character', 'ActorComponent') or a class path. The generated class is available to spawn_actor as '._C'.

Inputs: package_path (required), name (required), parent_class. Returns: result

create_materialA

Create a new empty Material asset.

package_path is the destination folder (e.g. '/Game/Materials'); name is the asset name. Use execute_python for wiring up material expression graphs, which the unreal.MaterialEditingLibrary exposes.

Inputs: package_path (required), name (required). Returns: result

delete_assetA

Delete an asset. Destructive — fails if other assets still reference it.

Inputs: asset_path (required). Returns: result

destroy_actorB

Delete an actor from the level by label or name.

Inputs: name (required). Returns: result

duplicate_assetC

Duplicate an asset to a new object path.

Inputs: source_path (required), dest_path (required). Returns: result

editor_stateA

Return engine/project/level info and the live actor count.

Call this first to confirm the Remote Control connection is working.

Inputs: no named parameters. Returns: result

execute_pythonA

Run Python inside the running Unreal Editor.

With evaluate=False (default) code is run as statements and the captured log/print output is returned. With evaluate=True code must be a single expression and its value's repr is returned.

The unreal module is already imported in the editor's interpreter. Example (statements): import unreal for a in unreal.get_editor_subsystem(unreal.EditorActorSubsystem).get_all_level_actors(): unreal.log(a.get_actor_label()) Example (evaluate=True): len(unreal.get_editor_subsystem(unreal.EditorActorSubsystem).get_all_level_actors())

Inputs: code (required), evaluate. Returns: result

get_actorA

Get details (class, transform, path) for one actor by label or name.

Inputs: name (required). Returns: result

import_assetA

Import an external file (FBX/OBJ/glTF, PNG/EXR, WAV, …) into /Game.

source_file is an absolute path on the machine running the editor; destination_path is a content path like '/Game/Imported'.

Inputs: source_file (required), destination_path (required), replace_existing. Returns: result

introspect_unreal_classA

List methods and properties of an unreal class, with its docstring.

e.g. 'EditorActorSubsystem', 'NiagaraSystem', 'LandscapeProxy', 'MovieSceneSequence', 'StaticMeshEditorSubsystem'.

Inputs: class_name (required), max_items. Returns: result

list_actorsB

List actors in the current level.

name_filter matches the World Outliner label (case-insensitive substring); class_filter matches the actor class name.

Inputs: name_filter, class_filter, limit. Returns: result

list_assetsB

List asset object paths under a content path.

class_filter keeps only assets whose class name contains the filter (e.g. 'StaticMesh', 'Material', 'Texture').

Inputs: path, recursive, class_filter, limit. Returns: result

load_levelA

Open a level by content path, replacing the currently open level.

Inputs: asset_path (required). Returns: result

new_levelA

Create a new empty level asset at a content path (e.g. '/Game/Maps/Test').

Inputs: asset_path (required). Returns: result

rc_call_functionC

Call a UFunction on a UObject directly via Remote Control.

Inputs: object_path (required), function_name (required), parameters. Returns: result

rc_get_propertyA

Read a UObject property directly via Remote Control (no Python bridge).

object_path is a full object path, e.g. '/Game/Maps/Test.Test:PersistentLevel.PointLight_1.LightComponent0'.

Inputs: object_path (required), property_name (required). Returns: result

rc_set_propertyB

Write a UObject property directly via Remote Control (transacted/undoable).

Inputs: object_path (required), property_name (required), value (required). Returns: result

rename_assetB

Rename/move an asset to a new object path.

Inputs: source_path (required), dest_path (required). Returns: result

run_automation_testsA

Run Automation Framework tests headlessly.

test_filter matches test names (empty runs all). Requires UE_PROJECT_PATH and UE_ENGINE_PATH. Returns exit code and a tail of the log. This launches a short-lived headless editor — it does not use the live editor connection.

Inputs: test_filter, timeout_seconds. Returns: result

run_console_commandA

Execute an Unreal console command in the running editor.

Examples: 'stat fps', 'r.ScreenPercentage 50', 'ShowFlag.Bounds 1', 'Slomo 0.5', 'BuildPaths'. Anything you could type into the in-editor console works here.

Inputs: command (required). Returns: result

run_python_fileB

Execute a .py file headlessly via -ExecutePythonScript.

Useful for long batch jobs that shouldn't tie up the interactive editor.

Inputs: script_path (required), timeout_seconds. Returns: result

save_allA

Save all dirty levels and content under /Game.

Inputs: no named parameters. Returns: result

save_assetC

Save a single asset to disk.

Inputs: asset_path (required). Returns: result

save_current_levelB

Save the currently open level.

Inputs: no named parameters. Returns: result

search_unreal_classesA

Search names in the live unreal module (classes, enums, libraries).

e.g. 'Niagara', 'Landscape', 'Sequencer', 'PCG', 'AbilitySystem', 'Spline', 'Foliage', 'Chaos'. Use this to discover what's available (including from enabled plugins) before writing execute_python.

Inputs: query (required), limit. Returns: result

set_actor_propertyB

Set an editor property on an actor (e.g. 'mobility', 'hidden', a light's 'intensity'). value is passed through to Unreal as-is.

Inputs: name (required), property_name (required), value (required). Returns: result

set_actor_transformC

Move/rotate/scale an actor. Only the provided components change.

Inputs: name (required), location, rotation, scale. Returns: result

spawn_actorB

Spawn an actor from a class.

actor_class accepts a short engine class name ('StaticMeshActor', 'PointLight', 'CameraActor'), a full class path ('/Script/Engine.StaticMeshActor'), or a Blueprint generated-class path ('/Game/BP/MyActor.MyActor_C'). location/rotation/scale are [x,y,z] (rotation is [roll,pitch,yaw]).

Inputs: actor_class (required), location, rotation, scale, +1 more. Returns: result

spawn_static_meshB

Spawn a StaticMeshActor using a static mesh asset.

mesh_asset is a content path, e.g. '/Engine/BasicShapes/Cube.Cube' or '/Game/Meshes/Rock.Rock'.

Inputs: mesh_asset (required), location, rotation, scale, +1 more. Returns: result

take_screenshotB

Capture a high-resolution screenshot of the active editor viewport.

filename is an absolute path on the editor machine where the PNG is written. Useful for letting the agent visually verify scene changes.

Inputs: filename (required), width, height. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 35 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose, covering different aspects of Unreal Engine (assets, actors, levels, scripting, remote control, automation, etc.). No overlapping or ambiguous tool pairs.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case, e.g., asset_exists, create_blueprint, spawn_actor. Even the rc_ prefix group is consistent within itself.

    Tool Count5/5

    35 tools is well-scoped for the complex domain of Unreal Engine. Each tool covers a necessary operation without being overly granular or missing critical functionality.

    Completeness4/5

    The tool set covers most common workflows (CRUD for assets/actors, level management, scripting, automation). Minor gaps exist (e.g., no direct material editing UI tools, no sequencer controls) but Python execution can bridge these.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for controlling Unreal Engine 5 from AI agents, providing 120+ commands for spawning actors, editing Blueprints, managing assets, and more via CLI or MCP.
      81 PyPI
      216
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server enabling AI agents to author Unreal Engine 5 scenes directly, with tools for spawning actors, building PCG graphs, validating physics, generating terrain, and more through a single MCP connection.
      13
      MIT