UnrealEngine Bridge

Claude Code, working inside your Unreal editor. This bridge gives Claude the abilities Epic's own MCP doesn't ship: run real editor Python, see the viewport continuously, light scenes with one command, reason about space with surface normals, and stay honest about every result.

58 MCP tools · 20 mounted by default · 635 tests · Changelog · Security

The one-paragraph story

UE 5.8 ships Epic's official Unreal MCP — 830 tools once you enable AllToolsets. That's the commodity control plane: spawn, transform, materials, Blueprints, Sequencer. So this bridge stopped competing and specialized. We live-probed Epic's entire surface, wrote the verdict for every one of our tools into EPIC_MCP_MATRIX.md, and flipped the default: you get our differentiated core out of the box, Epic handles the basics, and the 36 overlapping tools stay one env var away.

Related MCP server: unreal-ai-connection

How it works

Two MCP servers, one editor. Claude uses both.

graph LR
    subgraph Claude Code
        A[MCP Client]
    end

    subgraph B1["This bridge — Python"]
        B[MCP Server<br/><i>FastMCP · stdio</i>]
        B --> C[Tiered Registry<br/><i>core: 20 · full: 56</i>]
        C --> D[Remote Control Bridge<br/><i>httpx · circuit breaker</i>]
    end

    subgraph Unreal Editor
        E[Remote Control API<br/><i>localhost:30010</i>]
        E --> F[Editor Runtime]
        G[ViewportPerception<br/><i>localhost:30011</i>]
        G --> F
        H[Epic Unreal MCP<br/><i>localhost:8000 · UE 5.8</i>]
        H --> F
    end

    A -- stdio --> B
    A -. HTTP /mcp .-> H
    D -- HTTP --> E
    C -. viewport capture .-> G

    style A fill:#5CFFDB,color:#05050D
    style B fill:#5CFFDB,color:#05050D
    style C fill:#5CFFDB,color:#05050D
    style D fill:#12121F,color:#fff
    style E fill:#FFCC33,color:#05050D
    style F fill:#12121F,color:#fff
    style G fill:#FFCC33,color:#05050D
    style H fill:#FFCC33,color:#05050D

Who does what:

Quick start

You need: UE 5.7 or 5.8 · Python 3.11+ · the Remote Control API plugin enabled (ships with the engine).

1 — Install

git clone https://github.com/JosephOIbrahim/UnrealEngine_Bridge.git
cd UnrealEngine_Bridge
pip install -e .

2 — Open the project

Open UnrealEngine_Bridge.uproject. Check the Output Log for "Remote Control Web Server started" — that's localhost:30010 up.

On UE 5.8, the ModelContextProtocol and AllToolsets plugins self-enable (they're staged Optional in the project). Start Epic's server from the console: ModelContextProtocol.StartServer.

3 — Connect Claude Code

The repo ships a ready .mcp.json — open the repo folder in Claude Code and both servers are configured. For other projects, copy it and fix the path.

4 — Try it

"Set golden hour and snap the crates to the terrain."

Claude uses ue_apply_mood_preset and ue_snap_to_ground — two things no other UE MCP can do.

Want the commodity tools from this bridge instead of Epic's? Set the env var and restart the server:

"unreal": { "command": "python", "args": ["-m", "ue_mcp.mcp_server"], "env": { "UE_MCP_PROFILE": "full" } }

What's mounted by default (the core 20)

These are the tools Epic's MCP does not have — verified against all 830 of theirs (the matrix).

🐍 Editor Python & console (2)

👁 Perception (4)

🌅 Lighting & atmosphere (5)

📐 Spatial reasoning (4)

🧩 Scene gaps Epic left open (3)

❤️ Bridge health (2)

The commodity tier (36 tools, UE_MCP_PROFILE=full)

Epic's MCP covers these — the matrix cites the exact equivalent for every row. They stay in the codebase, tested and honest, for UE 5.7 or as a fallback:

Experimental tier (UE_MCP_PROFILE=all): ue_undo / ue_redo — honest not-implemented slots. The UE Python API has no scriptable editor-transaction route; these say so instead of pretending.

🧊 UE ↔ X3D round-trip harness (new in v0.3.0)

Hand Claude a level as open X3D it can read, edit, and validate — then write it back losslessly. A thin, fully-tested slice: no live editor needed to prove an edit is safe.

The one invariant it defends:

deserialize( serialize( level ) )  ==  level

Lossless round trip, plus malformed edits rejected on paper before any mutation. If both hold, the bridge is trustworthy — if either fails, nothing else matters.

from x3d_bridge import Actor, serialize, deserialize, validate

x3d = serialize([Actor(guid="Rock_01", mesh="/Game/Meshes/SM_Rock",
                       t=(420.0, 0.0, 155.0))])
ok, errors = validate(x3d)     # the paper boundary
level = deserialize(x3d)       # lossless

Status — honest, per the house rule:

• ✅ 55 tests — round-trip · validation battery · apply-op sequence — all green

• ✅ Basis B independently re-derived and confirmed three ways

• ⏳ B is analytic — not yet calibrated against a live glTF export (round-trip is basis-agnostic, so this is fidelity-only, never correctness)

• ⏳ A library today — not yet exposed as MCP tools

Why trust the results? Honesty as architecture

This bridge's tools cannot silently lie — that's enforced, not promised:

• Exec-simulated codegen tests. Every generated editor script is compiled and executed against a strict fake unreal module in CI. Phantom APIs raise. Dropped arguments fail a sentinel gate. Hard-coded success prints fail honesty contracts.

• Read-back verification. Writes that UE can silently ignore (cloner layout names) are read back before being reported "applied".

• Honest statuses. The viewport fallback reports capture_status: timeout instead of an empty image with success: true. Not-implemented tools say "not implemented".

• 635 tests, including scripted-failure contracts for every historical lying-tool bug.

graph TB
    subgraph Python layer
        MCP["MCP Server<br/><code>ue_mcp/mcp_server.py</code>"]
        Reg["Tiered Registry<br/><i>core / full / all</i>"]
        Tools["Tool Modules (14)<br/><code>ue_mcp/tools/</code>"]
        Val["Validation & AST Sandbox<br/><code>_validation.py</code>"]
        RC["Remote Control Bridge<br/><code>remote_control/</code>"]
        Met["Metrics & Circuit Breaker"]
    end

    subgraph Test layer
        Sim["Exec-Sim Harness<br/><i>strict fake unreal · honesty contracts</i>"]
    end

    subgraph Unreal Editor
        RCAPI["Remote Control API<br/><i>REST · :30010</i>"]
        VP["ViewportPerception plugin<br/><i>GPU readback · :30011</i>"]
        EPIC["Epic Unreal MCP<br/><i>HTTP+SSE · :8000 · UE 5.8</i>"]
    end

    MCP --> Reg --> Tools
    Tools --> Val
    Tools --> RC --> Met
    RC -- HTTP --> RCAPI
    Tools -. capture .-> VP
    Sim -. gates every generated script .-> Tools

    style MCP fill:#5CFFDB,color:#05050D
    style Reg fill:#5CFFDB,color:#05050D
    style Tools fill:#5CFFDB,color:#05050D
    style Sim fill:#12121F,color:#fff
    style RCAPI fill:#FFCC33,color:#05050D
    style VP fill:#FFCC33,color:#05050D
    style EPIC fill:#FFCC33,color:#05050D

Resilience

Network surface & trust model

Everything is localhost, single trusted operator: Remote Control (:30010), ViewportPerception (:30011, off by default), and — on 5.8 — Epic's MCP (:8000, no auth, serial on the game thread; Epic's EULA §6(e) governs what your LLM provider may do with transmitted data). Don't expose any of them to untrusted networks.

Full trust model and hardening guidance: SECURITY.md.

Project structure

UnrealEngine_Bridge/
├── ue_mcp/                        # MCP server package
│   ├── mcp_server.py              # FastMCP entry point (stdio) + health tools
│   ├── metrics.py                 # Telemetry + observability
│   ├── ue_logging.py              # Structured JSON logging
│   └── tools/                     # 14 modules · 56 tools · tiered registry in __init__.py
├── remote_control/                # UE5 HTTP bridge (circuit breaker, codegen, polling)
├── x3d_bridge/                    # UE↔X3D round-trip harness (coords · grammar · validate · apply)
├── usd_bridge/                    # USD file I/O package (parked, out of the ship path)
├── Plugins/
│   ├── UEBridge/                  # Editor panel, file watcher (C++)
│   └── ViewportPerception/        # GPU readback + HTTP endpoint (C++)
├── docs/
│   ├── EPIC_MCP_MATRIX.md         # Retirement contract-of-record (probe-grounded)
│   └── epic_mcp/                  # Raw probe captures of Epic's 830-tool surface
├── scripts/probe_epic_mcp.py      # Re-probe Epic's surface per engine version
├── tests/                         # 635 tests, incl. tests/exec_sim/ + tier gates
├── smoke_live.py                  # Live-editor smoke harness (on-demand)
└── .mcp.json                      # Two-server config: this bridge + Epic's MCP

Development

Run the tests

pip install -e ".[dev]"
python -m pytest -q                # 635 tests

Lint

ruff check ue_mcp/ remote_control/ tests/

Add a tool (each step is checked by CI)

1. Create ue_mcp/tools/your_module.py with a register(server, ue) function

2. Decorate tools with @server.tool(...); validate inputs via _validation.py

3. Wire the module into ue_mcp/tools/__init__.py — and classify the tool in TIERS (an unclassified tool fails CI)

4. Add a sentinel entry in tests/exec_sim/registry.py (a missing entry fails CI)

5. Add tests

License

Released under the MIT License — Copyright (c) 2026 Joseph Ibrahim.