# unreal-mcp

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

It speaks Epic's own [Python Remote Execution](https://dev.epicgames.com/documentation/en-us/unreal-engine/scripting-the-unreal-editor-using-python) 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`](https://docs.astral.sh/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

```bash
cd unreal-mcp
uv sync
```

### 3. Register with Claude

Add to `claude_desktop_config.json`:

```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`:

```json
"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.