PythonMCP-UEFN

Drive Unreal Editor for Fortnite from any MCP client over a local Python bridge.

This is a Model Context Protocol server that exposes the UEFN editor to an AI assistant. With it, an assistant can spawn and move actors, browse and validate assets, read and write device options, run arbitrary editor Python, trigger a Verse build and read the compile result, all without anyone touching the mouse.

It ships 39 tools. The interesting part is the device bridge: it reads and writes the @editable Verse properties that the standard unreal Python API refuses to surface by name. More on that below.

How it works

There are two halves. A listener that runs inside UEFN, and an MCP server that runs on your machine and talks to it.

  MCP client  (Claude Code, or any MCP host)
       |
       |  stdio
       v
  mcp_server.py        host process, this repo
       |
       |  HTTP POST  ->  127.0.0.1:8765
       v
  uefn_listener.py     runs inside the UEFN editor
       |
       |  game thread  (slate post-tick callback)
       v
  unreal.*             editor scripting API

The listener is a ThreadingHTTPServer bound to 127.0.0.1:8765. The HTTP thread only enqueues work. A slate post tick callback drains that queue on the game thread, because the unreal API is not thread safe and will crash if you call it from anywhere else. A watchdog re-arms the tick and the accept loop after a world or map change, and on a full project reopen the init_unreal hook re-runs the module. The whole listener is one self-contained file so you can paste it straight into Execute Python Script.

On the host side, transport.py adds retry with backoff, per-tool timeouts, and error classification. When something goes wrong it tells you whether the listener is down (socket refused) or wedged (reachable but the game thread stopped draining), so the failure message points at the actual fix.

Related MCP server: unreal-engine-mcp

Requirements

Host:

• Python 3.11

• The mcp package (pip install -r requirements.txt)

Editor:

• UEFN with Python editor scripting enabled (experimental, UEFN 40.40 or newer)

The listener itself has no third party dependencies. It uses only the standard library plus the unreal module that UEFN provides.

Setup

1. Install the host dependencies

pip install -r requirements.txt

2. Register the server with your MCP client

For Claude Code:

claude mcp add uefn --scope user -- python /absolute/path/to/PythonMCP-UEFN/mcp_server.py

For any other MCP host, point it at the same command. The server speaks stdio.

{
  "mcpServers": {
    "uefn": {
      "command": "python",
      "args": ["/absolute/path/to/PythonMCP-UEFN/mcp_server.py"]
    }
  }
}

3. Start the listener inside UEFN

Open your project, then Tools > Execute Python Script and pick uefn_listener.py. It binds the port and starts serving.

To confirm it is up, call the ping tool from your assistant (it returns {pong, uefn, tools}), or open http://127.0.0.1:8765/health in a browser.

4. Optional: start the listener automatically

Running the script by hand every session gets old. Install an autostart hook into your project:

python install_autostart.py "C:\path\to\YourProject"

That writes Content/Python/init_unreal.py into the project, so the listener comes up on its own whenever you open it.

Usage

Once the server is registered and the listener is running, ask your assistant to work in the level. A request like "spawn a cube at the origin and frame the camera on it" turns into:

spawn_static_mesh   mesh_path=/Engine/BasicShapes/Cube   location={x:0,y:0,z:0}
focus_on_actor      actor=<the new actor>

Reading and writing a device option works the same way:

device_list_options   label="My Trigger"
device_set_option     label="My Trigger"  option="EnabledAtGameStart"  value=false

When you need something no tool covers, execute_python runs arbitrary code in the editor with the unreal module already in scope. Assign your return value to _result.

Tools

Session and level

Actors

Viewport

Assets

Devices

Verse build

Python and autostart

The device bridge

A Fortnite device places its author written @editable Verse fields on a BlueprintGeneratedClass. The friendly name you wrote in Verse does not exist as a settable property. The fields live under mangled internal names of the form __verse_0x<hash>_<name>, and that hash changes on every recompile, so you cannot hardcode it.

The bridge recovers the mapping by dumping the placed device to T3D and matching the mangled names with a regex, then caches the result in _device_options_cache.json next to the listener. After that, the device_* tools let you read and write those fields by their real names. Native Epic devices expose clean properties and need no scan. Custom Verse devices need device_scan run once with the device configured, so the dump has values to recover.

The full background, including the editor Python limitations that made this necessary, is written up in docs/UEFN_Python_API_gaps.md.

Limitations

• Editor only. Python here cannot run gameplay. Runtime logic stays in Verse.

• One editor instance. The port 8765 is fixed.

• Do not issue tool calls while a Launch Session is starting. A racing call can abort the socket and trip asset validation with a false failure.

• The device introspection surface in the editor Python API is thin. The bridge works around it rather than relying on official support, so expect rough edges as UEFN changes.

Project layout

mcp_server.py             host MCP server, tool schemas, routing
transport.py              host HTTP client, retry, timeouts, error classification
uefn_listener.py          listener that runs inside UEFN, self-contained
install_autostart.py      writes the project autostart hook
init_unreal_template.py   template for Content/Python/init_unreal.py
tests/                    transport tests, no UEFN needed
docs/                     UEFN Python API gaps report

Development

The transport layer runs without UEFN, so its tests run anywhere:

python -m unittest discover tests

The listener and the server import unreal and mcp, so a full end to end run needs UEFN open with the listener started.

License

MIT. See LICENSE.