uefn-mcp

Python 3.10+ UEFN MCP

A two-process MCP bridge for Unreal Editor for Fortnite that lets Claude Code, Cursor, and other MCP clients drive a live UEFN editor safely.

MCP client (Claude Code / Cursor / custom host)
    │
    │ stdio
    ▼
server/main.py  ── FastMCP host process
    │
    │ HTTP 127.0.0.1:8765-8770
    ▼
Content/Python/uefn_tools/tools/mcp_bridge.py
    │
    │ queue + Slate tick callback
    ▼
UEFN editor main thread -> unreal.* -> 354 registered uefn_tools actions

Quick setup

git clone https://github.com/quangdang46/uefn-verse-mcp.git
cd uefn-verse-mcp
python -m pip install -r requirements.txt
python deploy.py --project "MyIsland"

There is no packaged one-line installer yet. The supported path today is source checkout plus local deploy into a UEFN project.

TL;DR

The Problem

UEFN's Python layer is powerful, but it is a bad place to host a modern MCP server directly:

• unreal.* calls must run on the editor main thread.

• Blocking Python code can freeze the editor.

• The MCP SDK belongs in a normal host Python runtime, not inside the editor sandbox.

The Solution

uefn-mcp splits the system in two:

• server/main.py runs externally as a FastMCP stdio server.

• Content/Python/uefn_tools/tools/mcp_bridge.py runs inside UEFN as a local HTTP listener.

• Commands are queued and drained on Slate ticks so editor API calls stay on the main thread.

Why Use uefn-mcp?

The live inventory is tracked in FEATURES.md, and deeper engine constraints are documented in docs/UEFN_QUIRKS.md.

Origins and Credits

This repo sits on top of two upstream lines:

• UEFN Toolbelt — broad in-editor uefn_tools registry and tooling: UEFN-TOOLBELT (Ocean Bennett).

• External MCP + in-editor listener — architecture and code lineage from KirChuvakov’s MIT-licensed projects (commonly referenced as uefn-mcp-server or uefn-verse-server).

This fork keeps both ideas, but reshapes them into an MCP-first repo:

• external FastMCP host process in server/

• in-editor HTTP bridge in Content/Python/uefn_tools/tools/mcp_bridge.py

• curated direct MCP surface plus a registry escape hatch

License

Licensing is documented in LICENSE. In short:

• Combined distribution: This repository is offered under GNU AGPL v3.0 with UEFN Toolbelt’s additional visible-attribution term (copyleft; network use triggers source-sharing obligations — see the license file and the AGPL-3.0 text).

• Upstream MIT components: Portions derived from KirChuvakov’s work were originally under the MIT License; their copyright and permission notice must stay intact in copies of this project (also reproduced in LICENSE).

• Forks and derivatives: If you ship something built on this codebase or its architecture, include the visible Toolbelt credit required in LICENSE (for example in README, docs, store page, or an in-editor credits panel):

  Built on UEFN Toolbelt by Ocean Bennett
  (https://github.com/undergroundrap/UEFN-TOOLBELT)

  …or an equivalent that names Ocean Bennett and links to that repository.

This is not legal advice; read LICENSE for full terms.

Quick Example

The fastest end-to-end workflow is:

git clone https://github.com/quangdang46/uefn-verse-mcp.git
cd uefn-verse-mcp
python -m pip install -r requirements.txt
python deploy.py --project "MyIsland"

# In the UEFN Python console
import uefn_tools as ut; ut.register(); ut.run("mcp_start")

// In your MCP client config (.mcp.json)
{
  "mcpServers": {
    "uefn": {
      "command": "python",
      "args": ["C:\\path\\to\\uefn-verse-mcp\\server\\main.py"]
    }
  }
}

Once the client reconnects, the typical first calls look like this:

ping()
get_project_info()
get_all_actors()
spawn_actor(class_path="/Game/Blueprints/BP_Cube.BP_Cube_C", location=[0, 0, 200])
set_viewport_camera(location=[-800, 0, 400], rotation=[-15, 0, 0])
list_tools(category="Materials")
describe_tool("material_gradient_painter")
run_tool("arena_generate", kwargs={"size": "large", "teams": True})
run_tool("smoke_test")

Examples above use conceptual MCP call syntax. The tool names and parameters match the real FastMCP surface exported by server/main.py.

Design Philosophy

1. Keep the MCP SDK outside UEFN

The host process uses ordinary Python and mcp>=1.2.0. UEFN only needs the local listener and the tool registry.

2. Never call unreal.* from the wrong thread

The HTTP server runs on a daemon thread, but every editor action is queued and drained on the Slate post-tick callback. That is the safety boundary that keeps automation from fighting the editor event loop.

3. Curate the common path, keep the full escape hatch

The direct MCP surface covers the most common actor, asset, level, and viewport workflows. run_tool, list_tools, and describe_tool expose the deeper registry when you need specialized behavior.

4. Make deploys boring

The intended setup is:

1. Copy uefn_tools/ and init_unreal.py into the target project.

2. Start the bridge in the editor.

3. Point the MCP client at server/main.py.

No editor-side package installation and no IDE-specific glue should be required beyond that.

Comparison

Prerequisites

• UEFN on Windows, with the Python Editor Script Plugin enabled

• Host Python 3.10 or newer for server/main.py, deploy.py, and the MCP dependency

• A local UEFN project you can copy Content/Python/ files into

Installation

Option 1: deploy.py (recommended)

deploy.py is the clean MCP-first path.

python -m pip install -r requirements.txt
python deploy.py --project "MyIsland"

You can also deploy by full path:

python deploy.py --path "D:\\Projects\\MyIsland"

If you omit both flags, deploy.py will prompt you interactively.

Link mode (opt-in, local dev only)

For fast local iteration you can link uefn_tools/ instead of copying it. Edits in the repo checkout are then immediately visible to UEFN without redeploying.

python deploy.py --project "MyIsland" --link-kind junction
python deploy.py --path "D:\\Projects\\MyIsland" --link-kind symlink

init_unreal.py is always copied as a real file regardless of link mode.

Note: Link mode is a local development convenience. Do not use it for shared or team projects — use the default copy mode instead.

What it installs:

• Content/Python/uefn_tools/

• Content/Python/init_unreal.py

• .urcignore entry for Content/Python/*

Option 2: deploy.bat (Windows interactive helper)

If you prefer a Windows batch workflow:

deploy.bat

This is still present as a helper, but the repo's documented MCP-first path is deploy.py.

Option 3: Manual install

If you need full control:

1. Copy Content/Python/uefn_tools/ into your project at Content/Python/uefn_tools/.

2. Copy init_unreal.py into your project at Content/Python/init_unreal.py.

3. Install host dependencies:

python -m pip install -r requirements.txt

1. Ensure the project root .urcignore includes:

Content/Python/*

Not Recommended: install.py

install.py still contains older Toolbelt/UI-era behavior. Use deploy.py for the current MCP-first workflow.

Quick Start

1. Clone the repo.

git clone https://github.com/quangdang46/uefn-verse-mcp.git
cd uefn-verse-mcp

1. Install the host dependency into the same Python interpreter your MCP client will use.

python -m pip install -r requirements.txt

1. Deploy the UEFN-side package.

python deploy.py --project "MyIsland"

1. Start the listener inside UEFN.

import uefn_tools as ut
ut.register()
ut.run("mcp_start")

1. Add the server to your MCP client config.

{
  "mcpServers": {
    "uefn": {
      "command": "python",
      "args": ["C:\\path\\to\\uefn-verse-mcp\\server\\main.py"]
    }
  }
}

1. Verify the connection.

ping()
get_status()
run_tool("smoke_test")

1. Start editing the level from your MCP client.

get_all_actors()
search_assets(class_name="StaticMesh", directory="/Game", recursive=True)
spawn_actor(class_path="/Game/Blueprints/BP_Cube.BP_Cube_C", location=[0, 0, 100])

Command Reference

System

Actors

Assets

Project / Level

Viewport

Escape Hatch

Working With the Full Registry

The direct MCP surface is intentionally small. The deeper workflows are meant to be discovered dynamically:

list_tools()
list_tools(category="Verse Helpers")
describe_tool("device_call_method")
run_tool("device_call_method", kwargs={"class_filter": "TimerObjective", "method": "blueprint_pause"})

The full generated inventory lives in FEATURES.md.

Configuration

.mcp.json

Use the same Python interpreter here that you used for python -m pip install -r requirements.txt.

{
  "mcpServers": {
    "uefn": {
      "command": "python",
      "args": ["C:\\dev\\uefn-verse-mcp\\server\\main.py"]
    }
  }
}

Environment Variables

Port Behavior

• The in-editor listener binds to the first available port in 8765-8770.

• The host discovers the active port by probing http://127.0.0.1:<port>/.

• If the cached port stops responding, the host rescans automatically.

UEFN Loader Contract

init_unreal.py is intentionally generic:

• it adds Content/Python/ to sys.path

• it discovers packages with __init__.py

• it calls register() when available

That means uefn_tools is only one possible package. The loader is reusable for other editor-side Python packages in the same project.

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│ MCP client                                                          │
│ Claude Code / Cursor / custom FastMCP host                          │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                │ stdio
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│ server/main.py                                                      │
│ - FastMCP server                                                    │
│ - 31 direct tools                                                   │
│ - run_tool / list_tools / describe_tool                             │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                │ HTTP JSON POST
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│ Content/Python/uefn_tools/tools/mcp_bridge.py                       │
│ - Local HTTP listener inside the UEFN process                       │
│ - Queue-based handoff from HTTP thread to editor main thread        │
│ - Bridge commands: system, actors, assets, viewport, escape hatch   │
└──────────────────────────────────────────────────────────────────────┘
                                │
                                │ Slate post-tick callback
                                ▼
┌──────────────────────────────────────────────────────────────────────┐
│ UEFN editor main thread                                             │
│ - Executes unreal.* calls safely                                    │
│ - Reads and writes level / assets / viewport                        │
│ - Invokes 354 registered uefn_tools actions                         │
└──────────────────────────────────────────────────────────────────────┘

Important files:

For a shorter architecture note, see ARCHITECTURE.md.

Troubleshooting

Limitations

• This repo does not make UEFN headless. You still need a live local editor session.

• The direct MCP surface is curated; deeper workflows rely on run_tool.

• The 354-tool registry is broad, but not every entry has been verified in every environment yet. See the status column in FEATURES.md.

• UEFN Python has engine-specific quirks and unsafe APIs. Some operations that are fine in full Unreal Engine are limited or crash-prone in UEFN.

• The documented install path is source-based. There is no PyPI, Homebrew, winget, or standalone installer release flow documented here today.

FAQ

Do I need to install anything inside UEFN's embedded Python?

No for the MCP server itself. The mcp dependency belongs in the external host Python that runs server/main.py.

Why not run the MCP SDK directly inside the editor?

Because the editor runtime is the wrong place for a long-lived stdio server and blocking automation. The two-process split is the safety boundary.

What should I call first after connecting?

ping(), then get_status(), then either get_project_info() or run_tool("smoke_test").

How do I access the specialized tools?

Use list_tools() to discover categories, describe_tool() to inspect parameters, and run_tool() to execute the chosen action.

Can I use this without Claude Code?

Yes. Any MCP client that can launch a stdio server can point at server/main.py.

Do I have to restart UEFN after every change?

No. Most package changes can be reloaded with ut.register(). Changes to startup loader behavior in init_unreal.py are the ones most likely to require a restart.

Where should I look if UEFN behavior seems weird?

Start with docs/UEFN_QUIRKS.md. That file captures the non-obvious engine behavior this repo is already compensating for.