UnrealMCP

A self-owned Model Context Protocol server that drives the Unreal Engine 5.7 editor for AI-assisted development and deterministic cinematic production — designed to be controlled by Claude Code (or any MCP client).

It speaks MCP over stdio on one side and the Unreal Editor's built-in Python Remote Execution on the other, so it needs no compiled C++ plugin — which keeps it portable across engine builds.

Why

It replaces a two-server setup (a C++ in-editor HTTP plugin + a separate Python bridge) with one server you own end to end, and fixes two hard-won bugs by construction:

• Level saves write .umap, never .uasset. A duplicate .uasset sharing a level's package name causes non-deterministic stale-level loads; the one save tool routes worlds through the level-save API and refuses to save a World as an asset.
• Mutations actually persist — every edit does Modify(True) + dirties the package and saves through the real editor path, so spawned/edited actors survive a reload.

And it adds a deterministic film / illustration pipeline: render your real, canon-consistent 3D assets through Sequencer + Movie Render Queue instead of fighting generative-AI character drift.

Tools (35)

• Editor & level: get_status, get_level_actors, run_console_command, open_level, save_level (.umap-guarded), get_output_log, restart_editor (clean quit + relaunch), execute_python (arbitrary editor Python — the escape hatch).
• Actors: spawn_actor, set_property, move_actor, delete_actors.
• Assets: asset_search, asset_save, asset_edit (CRUD), asset_dependencies, asset_referencers, asset_import, material_instance.
• Eyes (anti-stale SceneCapture2D, returns images): eyes_mirror, eyes_focus, eyes_look, eyes_overview (top-down orthographic floor plan).
• Camera / DoF: set_camera (aperture, focal length, focus method + distance).
• Cinematic / film authoring (Sequencer): create_sequence, animate_actor, play_animation (skeletal), add_camera_cut, add_audio, add_fade, set_actor_visibility_track, add_shot (master / sub-sequence), sequence_inspect.
• Render (Movie Render Queue, async request → poll): render_sequence, render_status.

Architecture

Claude Code  ⇄  (stdio MCP / FastMCP)  ⇄  this bridge  ⇄  (UE Python Remote Execution,
                                                            multicast 239.0.0.1:6766 / TCP 6776)  ⇄  Unreal Editor

The bridge sends short Python snippets that run on the editor's game thread; each prints a UMCP_RESULT:<json> line the bridge parses back. Images (eyes_* and render previews) are written to disk by the editor and returned as MCP image content. The bridge lives outside the editor, so it survives editor restarts and auto-reconnects.

Requirements

• Windows + Unreal Engine 5.7 (tested), Python 3.11.
• In your UE project: enable the Python Editor Script Plugin, and Project Settings → Plugins → Python → Enable Remote Execution (defaults: multicast 239.0.0.1:6766, bind 127.0.0.1). Allow your python.exe through the firewall on first run.

Setup

# 1) install
py -3.11 -m venv .venv
.venv\Scripts\pip install -e .

# 2) vendor Epic's Remote Execution client.
#    It is NOT redistributed in this repo (Copyright Epic Games, All Rights Reserved) — copy it from
#    your own engine install:
Copy-Item "C:\Program Files\Epic Games\UE_5.7\Engine\Plugins\Experimental\PythonScriptPlugin\Content\Python\remote_execution.py" `
          "src\unreal_mcp\vendor\remote_execution.py"

Use with Claude Code

Copy .mcp.json.example to .mcp.json (in this repo, or in your UE project), fix the paths, then run /mcp to connect:

{
  "mcpServers": {
    "unrealmcp": {
      "command": "C:/Projects/UnrealMCP/.venv/Scripts/python.exe",
      "args": ["-m", "unreal_mcp"],
      "env": { "UNREAL_PROJECT_DIR": "C:/Path/To/YourUEProject" }
    }
  }
}

Launch the editor on your project, /mcp connect, and the tools appear.

Notes

• restart_editor requests a clean editor quit (never a force-kill) and relaunches it detached.
• Tested against vanilla UE 5.7. A deferred ARK Survival Ascended DevKit layer (additive, same architecture) is planned.
• This server intentionally has no generic "save asset on a World" path — worlds save as .umap only.