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

1. Open your project in UEFN
2. Go to Project > Project Settings
3. 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

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:

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.

Documentation

Requirements

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

License

MIT