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)

• 22 tools: actors, assets, levels, viewport, 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

1. Enable Python in UEFN

1. Open your project in UEFN
2. Go to Edit > Project Settings
3. Search for Python and check the boxes for Python Editor Script Plugin, Editor Scripting Utilities, and Python Developer Mode

2. Start the listener inside UEFN

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

In the Output Log you should see:

[MCP] Listener started on http://127.0.0.1:8765
[MCP] Registered 22 command handlers

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 22 UEFN tools available.

6. 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 | | Actors | get_all_actors, get_selected_actors, spawn_actor, delete_actors, set_actor_transform, get_actor_properties | | Assets | list_assets, get_asset_info, get_selected_assets, rename_asset, delete_asset, duplicate_asset, does_asset_exist, save_asset, search_assets | | 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
# Assign to `result` to return a value

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

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 22 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