unreal-mcp

An MCP server that drives a running Unreal Engine editor from Claude.

It speaks Epic's own Python Remote Execution protocol: UDP multicast on 239.0.0.1:6766 to discover editor instances, then a TCP channel to run Python inside the editor.

Claude  ──stdio──▶  unreal-mcp  ──UDP discovery + TCP──▶  Unreal Editor (PythonScriptPlugin)

The client half of the protocol is not vendored. The server locates Epic's remote_execution.py inside your engine install at runtime, so it keeps working across engine versions.

Requirements

• Unreal Engine 5.x (developed against 5.6)
• Python 3.10+ and uv

Setup

1. Enable remote execution in Unreal — this is the step everyone misses

Remote execution is OFF by default. Without it the editor is invisible to discovery and every tool will fail.

1. Edit > Plugins → enable Python Editor Script Plugin → restart.
2. Edit > Project Settings > Plugins > Python → tick Enable Remote Execution.
3. Restart the editor.

2. Install

cd unreal-mcp
uv sync

3. Register with Claude

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "unreal": {
      "command": "uv",
      "args": ["--directory", "E:\\Maya\\unreal-mcp", "run", "unreal-mcp"]
    }
  }
}

Then start a new conversation — servers added mid-session are not picked up by a chat that is already running.

If your engine is somewhere non-standard, set UNREAL_ENGINE_ROOT:

"env": { "UNREAL_ENGINE_ROOT": "D:\\Epic\\UE_5.6" }

Tools

Tool	Read-only	What it does
unreal_get_status	✅	Is an editor reachable? Which project, level, actor count. Start here when anything fails.
unreal_list_assets	✅	Browse the content browser, filtered and paginated
unreal_list_actors	✅	Actors in the open level with their transforms
unreal_import_asset		Import FBX / OBJ / textures via the automated pipeline
unreal_spawn_actor		Place a content asset into the level
unreal_set_actor_transform		Move / rotate / scale a placed actor
unreal_delete_actor		Destructive — destroys an actor
unreal_set_viewport_camera		Aim the editor viewport
unreal_take_screenshot		High-res PNG of the viewport
unreal_save_all		Save modified assets and the level
unreal_execute_python		Escape hatch: arbitrary Python in the editor

Listing tools paginate with limit / offset and return has_more plus next_offset.

How results come back

Tool bodies are shipped to the editor wrapped in a harness that assigns to a result variable and prints it as JSON between sentinels. That keeps a stray print() or an Unreal log line from corrupting the payload, and turns an exception inside the editor into a structured error instead of a traceback buried in stdout.

Security note

unreal_execute_python runs unsandboxed code in the editor's interpreter with full unreal module access. It can modify or delete project content. Treat it with the same care as a Python console in the editor itself.

Troubleshooting

"No running Unreal Editor was discovered" — almost always the Enable Remote Execution setting above. Confirm with unreal_get_status.

"Lost the connection ... while running a command" — the editor was closed or is blocked in a modal dialog. Dismiss the dialog and retry; the session re-discovers automatically.

Multiple editors open — the first discovered node wins. unreal_get_status lists them all so you can tell which is which.