UEFN MCP Server

Control UEFN (Unreal Editor for Fortnite) from Claude Code via the Model Context Protocol.

Claude Code  <--stdio-->  MCP Server (mcp_server.py)  <--HTTP-->  Listener (uefn_listener.py, inside UEFN)

28 tools: actors, assets, levels, viewport, project info, editor log, and arbitrary Python execution
Zero C++ compilation — pure Python, works across UEFN versions
Main-thread safe — all unreal.* calls dispatched via editor tick callback

Quick Start

0. Let Claude do the setup

Open Claude Code and ask: "Help me set up UEFN MCP server" — it will install dependencies, create config files, and walk you through the rest.

If you prefer to do it manually, follow steps 1-5 below.

1. Enable Python in UEFN

Open your project in UEFN
Go to Project > Project Settings
Search for Python and check the box for Python Editor Script Plugin

2. Start the listener inside UEFN

Use Tools > Execute Python Script in the UEFN menu bar, then select the uefn_listener.py file.

A status window will appear showing:

Listener status — green when running, red when stopped
MCP Server status — green when Claude Code is connected (heartbeat every 10s)
Port — editable when listener is stopped
Metrics — uptime, request count, errors, last command, avg response time
Controls — Stop / Start / Restart buttons

You can safely close this window — the listener continues running in the background.

3. Install MCP SDK

On your system (not inside UEFN):

pip install mcp

4. Configure Claude Code

Create .mcp.json in your project root (or add to ~/.claude/settings.json):

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

5. Restart Claude Code

Claude Code picks up .mcp.json on startup. After restart, you'll have 28 UEFN tools available.

Try it

Ask Claude Code:

"List all actors in the level"
"Spawn a cube at position 100, 200, 300"
"What assets are in /Game/Materials/?"
"Move the viewport camera to look at the origin"

Auto-start (optional)

To start the listener automatically when UEFN opens your project:

# Copy both files to your UEFN project's Content/Python/ directory
cp uefn_listener.py  <YourUEFNProject>/Content/Python/uefn_listener.py
cp init_unreal.py     <YourUEFNProject>/Content/Python/init_unreal.py

UEFN automatically executes init_unreal.py on project open.

Tools

| Category | Tools | |----------|-------| | System | ping, execute_python, get_log, get_editor_log, shutdown | | Actors | get_all_actors, get_selected_actors, spawn_actor, delete_actors, set_actor_transform, get_actor_properties, set_actor_properties, select_actors, focus_selected | | Assets | list_assets, get_asset_info, get_selected_assets, rename_asset, delete_asset, duplicate_asset, does_asset_exist, save_asset, search_assets | | Project | get_project_info | | Level | save_current_level, get_level_info | | Viewport | get_viewport_camera, set_viewport_camera |

The execute_python tool is the most powerful — it runs arbitrary Python code inside the editor with full access to the unreal module:

# Pre-populated variables: unreal, actor_sub, asset_sub, level_sub, tk, get_tk_root
# Assign to `result` to return a value

actors = actor_sub.get_all_level_actors()
result = [a.get_actor_label() for a in actors]

Tkinter note: When creating UI windows via execute_python, use get_tk_root() + tk.Toplevel(root). Never call tk.Tk() — multiple instances crash the editor.

Architecture

The system uses two independently running Python processes:

| Component | File | Runs in | Python | Dependencies | |-----------|------|---------|--------|--------------| | Listener | uefn_listener.py | UEFN editor process | 3.11+ (embedded) | stdlib only | | MCP Server | mcp_server.py | External process | 3.10+ (system) | mcp SDK |

Why two processes?

All unreal.* calls must happen on the editor's main thread (tick callback)
The MCP SDK needs pip-installable packages that can't be added to UEFN's embedded Python
Each component can restart independently

See docs/architecture.md for details.

Configuration

Custom port

{
  "mcpServers": {
    "uefn": {
      "command": "python",
      "args": ["path/to/mcp_server.py", "--port", "8766"]
    }
  }
}

Or via environment variable:

{
  "mcpServers": {
    "uefn": {
      "command": "python",
      "args": ["path/to/mcp_server.py"],
      "env": { "UEFN_MCP_PORT": "8766" }
    }
  }
}

Bonus Tools

Scripts that run inside the UEFN editor to introspect the Python API. Run via Tools > Execute Python Script in the UEFN menu bar.

| Script | Description | |--------|-------------| | tools/dump_uefn_api.py | Dump all classes, enums, structs, functions to JSON | | tools/generate_uefn_stub.py | Generate .pyi type stub for IDE autocomplete (37K+ types) | | tests/test_feasibility.py | Verify UEFN sandbox supports HTTP/threading for MCP |

Documentation

| Document | Description | |----------|-------------| | Setup Guide | Detailed installation and configuration | | Tools Reference | All 28 tools with parameters, examples, and responses | | Architecture | How the two-component system works internally | | Troubleshooting | Common issues and solutions | | UEFN Python Capabilities | Full API capabilities map — 37K types across 30 domains |

Requirements

UEFN editor with Python scripting enabled (Project Settings)
Python 3.10+ on host system
pip install mcp
Claude Code CLI

License

MIT

MCP Servers