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.

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.