Unreal AI Connection

Authoring high-quality assets: see docs/ASSET-PIPELINE-BLENDER.md.

Install (one paste, any client)

Every route below only wires the stdio bridge. You must separately install the UE 5.7 plugin into your project's Plugins/ folder and launch the editor (it binds 127.0.0.1:18888). See docs/setup/README.md for the prerequisite, and docs/DISTRIBUTION.md for how this is published.

Claude Code — paste the owner/repo, no clone needed:

/plugin marketplace add NAJEMWEHBE/unreal-ai-connection
/plugin install unreal-ai-connection@unreal-ai-connection

Cursor — one-click deeplink. Base64-encode your machine's bridge path into this template:

cursor://anysphere.cursor-deeplink/mcp/install?name=unreal-ai-connection&config=<BASE64>

where <BASE64> is base64 of {"command":"python3","args":["/ABSOLUTE/PATH/TO/bridge/unreal_ai_connection_bridge.py"]} (on Windows use "command":"py" if python3 is not on PATH). Manual fallback — .cursor/mcp.json:

{ "mcpServers": { "unreal-ai-connection": { "command": "python3", "args": ["/ABSOLUTE/PATH/TO/bridge/unreal_ai_connection_bridge.py"] } } }

VS Code — install deeplink (URL-encode the JSON for your path):

vscode:mcp/install?<URL-ENCODED {"name":"unreal-ai-connection","command":"python3","args":["/ABSOLUTE/PATH/.../bridge/unreal_ai_connection_bridge.py"]}>

Windows: all snippets use python3; if that's not on PATH use the py launcher instead ("command": "py"). The .claude-plugin/mcp-config.json marketplace path uses python3 for cross-platform consistency — Windows users without python3 should use the manual per-client recipe in docs/setup/ with py.

Every other client — copy-paste recipe per client:

Also discoverable in the official MCP Registry as io.github.najemwehbe/unreal-ai-connection (feeds the VS Code MCP gallery, mcp.so, PulseMCP) and submittable to the Cline marketplace via llms-install.md.

Jump to

• How it fits together — architecture diagram + per-call sequence
• Why it exists — the UE 5.7 Python dead-ends this plugin sidesteps
• Why MCP specifically — one protocol, every conforming client
• Tools — 105 tools grouped into 14 expandable categories
• Quick start — copy-paste path to a running editor with the plugin live
• What's in the box — directory tree
• Status — release / test / build state
• Contributing — house rules + how to add a tool
• License

How it fits together

graph LR
    A[Any MCP client] -->|stdio MCP| B[Python Bridge]
    B -->|TCP 127.0.0.1:18888| C[UnrealClaudeMCP plugin<br/>UE editor module]
    C -->|native C++ API| D[Unreal Editor 5.7]

sequenceDiagram
    participant User
    participant Client as MCP client<br/>(e.g. Claude Code)
    participant Bridge as Python bridge
    participant Plugin as UE plugin module
    participant Editor as Unreal Editor 5.7

    User->>Client: "Spawn a Cube at origin"
    Client->>Bridge: stdio MCP — tools/call spawn_actor
    Bridge->>Plugin: TCP 127.0.0.1:18888<br/>JSON-RPC framed
    Plugin->>Editor: GEditor->SpawnActor()
    Editor-->>Plugin: success + actor ref
    Plugin-->>Bridge: JSON-RPC result
    Bridge-->>Client: MCP envelope
    Client-->>User: rendered confirmation<br/>(~50ms total)

You ask Claude Code: "Take a screenshot of my level and tell me what's there." — Claude resolves the request to a tool call, the bridge forwards it as JSON-RPC to the running editor, the plugin captures the viewport, and Claude renders the image inline. Same flow works for spawning actors, inspecting Blueprints, mutating Widget Trees, executing arbitrary unreal.* Python, listing actors, focusing the viewport, loading levels, taking high-res screenshots.

The plugin binds to 127.0.0.1 only — your running editor is never reachable across the network.

Why it exists

UE 5.7's Python reflection has known dead-ends. Most painfully: EditorUtilityWidgetBlueprint.WidgetTree is a UPROPERTY() without EditAnywhere, so neither get_editor_property nor direct attribute access can reach it. This blocks "let an LLM build me an editor utility panel" workflows entirely.

The plugin sidesteps these limits by calling UE's native C++ APIs directly inside the editor process. It's also dramatically faster than driving UE's GUI with screenshot pixel-clicks — ~50ms round-trip vs. minutes of GUI fiddling.

Why MCP specifically

MCP (Model Context Protocol) is a vendor-neutral I/O protocol designed for LLM tool-use. Because this plugin speaks MCP rather than baking in any one client, every conforming client gets all 105 tools for free: Claude Code, Codex CLI, Cursor, Gemini CLI, Continue, Zed, Cline, and any future entrant. Switch clients without changing the plugin or the bridge.

The wire format is stdio MCP between client and bridge, then a tight length-prefixed JSON-RPC over TCP 127.0.0.1:18888 between bridge and the running UE editor. Either side can be reimplemented in another language; the contract is the JSON.

Tools

105 tools total. 72 are native C++ handlers registered by the plugin at editor startup; 33 are bridge-side synthetic tools (wait_for_events, get_camera_transform, set_camera_transform, screenshot_actor, compile_mod_pak, compile_mod_pak_direct, bulk_delete_assets, bulk_move_assets, bulk_rename_assets, bulk_duplicate_assets, bulk_inspect_assets, inspect_data_asset, inspect_sound_class, inspect_sound_submix, inspect_audio_bus, inspect_material_function, inspect_metasound, find_unused_assets, get_reference_chain, bulk_compile_blueprints, audit_blueprint_compile_status, find_actors_by_class, bulk_focus_actors, bulk_screenshot_actors, bulk_set_actor_property, compare_assets, bulk_set_console_variables, inspect_dependency_graph, bulk_fix_redirectors, marketplace_search, marketplace_import, convert_hdri_to_cubemap, sequencer_add_transform_keyframe) that compose existing handlers without a dedicated UE round-trip (or, for compile_mod_pak and compile_mod_pak_direct, shell out to RunUAT or UnrealPak entirely outside the UE process) — see bridge/unreal_ai_connection_bridge.py's SYNTHETIC_TOOLS. Per-tool JSON schemas and examples live in docs/TOOLS.md. Grouped overview:

Python execution (5 tools)

Project / asset registry (8 tools)

Blueprint / widget / animation introspection (14 tools)

Materials (4 tools)

Textures (3 tools)

Level Sequences (3 tools)

Level / actor authoring (16 tools)

Viewport / screenshots (3 tools)

Console / logs (5 tools)

Long-running tasks (4 tools)

Event push / subscriptions (5 tools)

Audio (3 tools — introspection trio)

Camera (3 tools — bridge-side synthetic)

Self-introspection (1 tool)

Adding a 73rd C++ handler is one .cpp file plus one line of registration — see docs/ARCHITECTURE.md. New synthetic tools are an entry in SYNTHETIC_TOOLS plus a function in bridge/unreal_ai_connection_bridge.py.

Quick start

Engineers (you already build UE projects from source)

1. Drop the plugin in. Copy UnrealClaudeMCP/ into <YourProject>/Plugins/.
2. Regenerate project files. Right-click <YourProject>.uproject → Generate Visual Studio project files.
3. Build the editor. Open the .sln, build Development Editor | Win64. First build takes ~5–15 min.
4. Launch. Open the .uproject. The MCP server auto-starts on 127.0.0.1:18888. Look for these lines in the Output Log:

   [LogUnrealClaudeMCP] Module started
   LogUCMCPHandler: Registered handler 'execute_unreal_python'
     ... (64 lines)
   [LogUCMCP] Listening on 127.0.0.1:18888
   

5. Wire your MCP client. Copy examples/.mcp.json.example to your project root as .mcp.json, edit the path to point at bridge/unreal_ai_connection_bridge.py, restart your client, and approve the new MCP server. Same bridge works with Claude Code, Claude Desktop, Cursor, Codex CLI, Windsurf, Continue, Cline, Zed, Gemini CLI, and VS Code Copilot — see docs/setup/ for per-client copy-paste recipes.

Non-engineers / GUI-only users

See docs/INSTALLATION.md — step-by-step, screenshot-first.

Verify it works

The smoke test fires every default-on tool from a plain Python TCP client (not through Claude Code) — a fast way to confirm the plugin loaded and the server is alive:

python examples/smoke_test.py

You'll see structured JSON output for every default-on step (eleven banner-headed sections, plus a few unbannered checks for the asset registry, sequencer and materials handlers — the last two skip with a print if your project has no Level Sequences or Materials in /Game/). Last line: "Smoke test complete."

What's in the box

UnrealClaudeMCP/                The Unreal Engine plugin (drop into <Project>/Plugins/)
  Source/UnrealClaudeMCP/         C++ editor module
  Resources/                      MCP manifest JSON
  UnrealClaudeMCP.uplugin         Plugin manifest

bridge/
  unreal_ai_connection_bridge.py     Python stdio ↔ TCP bridge for any MCP client

examples/
  smoke_test.py                   Connects to the live server, fires the safe tools
  .mcp.json.example               Template Claude Code MCP config

docs/
  INSTALLATION.md                 Step-by-step install for a UE 5.7 project
  TOOLS.md                        What each tool does + JSON examples
  ARCHITECTURE.md                 How the pieces fit + UE 5.7 API gotchas

tests/                            Pytest suite for the bridge (no UE required)
.github/workflows/                CI runs the bridge tests on every push & PR

Status

Roadmap / status honesty

One in-flight item is stated plainly here so nothing is oversold:

• Officially built & tested on UE 5.7. Other UE versions are community / best-effort: the cross-engine compatibility scaffold lets you build from source for your engine version (uncertified, not actively maintained, contributions welcome). See ADR-0001 / docs/PHASE-H-COMPAT.md.

What this is NOT

• A general MCP server framework — this is bonded to UE's editor process.
• A live-broadcast tool — for that, look at vMix, OBS, NDI Studio Monitor.
• An Aximmetry / Pixotope / Disguise replacement — those have multi-engineer multi-year codebases.

Contributing

Issues and PRs welcome. Two house rules:

1. Verify UE API claims against UE 5.7 source. Past reviewer subagents have made specific UE API claims that turned out wrong; ground-truth the engine source before committing.
2. Each new MCP handler is one Handler_*.cpp file in Source/UnrealClaudeMCP/Private/MCP/Handlers/, plus one extern declaration and one Reg.Register(Make_Handler_*()) line in UnrealClaudeMCPModule.cpp. Don't grow the foundation — add handlers.

Running tests

Bridge unit tests run without UE in under a second:

pip install pytest pytest-cov
pytest tests/

CI runs the same suite on every push and PR (see .github/workflows/tests.yml). The live integration smoke test in examples/smoke_test.py requires a running UE editor — see tests/README.md.

License

MIT — see LICENSE. © 2026 HD Media (Kuwait).