unreal-ai-connection
This server lets you drive Unreal Engine 5.7 programmatically from any MCP-compliant AI client over a local TCP socket, exposing 146 tools for inspecting, authoring, and automating virtually every aspect of the Unreal Editor.
Python Execution
Run arbitrary
unreal.*Python, execute.pyfiles, maintain persistent sessions, and run scripts against the current editor selection.
Asset Management
Query, inspect, move, rename, duplicate, and delete assets; fix redirectors; find unused assets; walk dependency/reference graphs; create DataTables and DataAssets; bulk inspect/delete/move/rename/duplicate.
Blueprint & UI Widgets
Inspect, compile, and audit Blueprints; create Blueprints and add variables, functions, and K2 graph nodes; connect pins and set defaults. Inspect and mutate Widget Trees (including Editor Utility Widgets that UE Python cannot access).
Materials & Textures
Create material instances, set scalar/vector/texture parameters, add/connect material expression nodes, inspect materials and material functions. Import textures from disk and configure compression, sRGB, and LOD groups.
Level & Actor Authoring
Spawn, move, rotate, scale, delete, duplicate, and rename actors; set any UPROPERTY (bulk supported); attach components; set World Outliner folder paths; load/create levels; build static lighting; find actors by class.
Niagara VFX
Spawn Niagara systems at a location or attached to an actor, inspect emitter/parameter structure, and set user-exposed parameters on placed components.
Level Sequences & Cinematics
Create/inspect Level Sequences, bind actors, set playback range, add camera cut/audio/visibility tracks, add transform keyframes, and render via Movie Render Queue (async with task polling).
Viewport & Screenshots
Capture the active viewport as base64 PNG, take high-res screenshots, render off-screen camera views, focus and screenshot individual or multiple actors in batch, and get/set the editor viewport camera transform.
Console, CVars & Logs
Execute console commands, get/set/search console variables (bulk set with optional rollback), and read Output Log entries with category/verbosity filters.
Editor State & Settings
Undo/redo transactions; start/stop/query Play-In-Editor sessions; save dirty assets and levels; inspect project settings for any
UDeveloperSettingssubclass; inspect legacy and Enhanced Input mappings; get project summary and engine version.
Animation & Audio Introspection
Inspect Anim Blueprints, Montages, Skeletal Meshes, Static Meshes, Physics Assets, and Curves. Inspect SoundCue, SoundWave, SoundAttenuation, SoundClass, SoundSubmix, AudioBus, and MetaSound assets.
Long-Running Tasks & Events
Start, poll, and cancel background tasks (e.g., MRQ renders). Poll or subscribe to filtered editor event streams (actor spawn/delete, asset changes, level save, map change).
Mod / PAK Development
Compile UE mod plugins to
.pakfiles via RunUAT or direct UnrealPak invocation.
Miscellaneous
Compare assets (symmetric diff), inspect landscapes, convert HDRI to cubemap, import meshes, auto-remap materials, batch-spawn actors from CSV, and list all registered MCP tools (self-introspection).
Provides tools for controlling Unreal Engine 5.7 from MCP clients, enabling spawning actors, taking screenshots, executing Python code, loading levels, inspecting blueprints, and more via native C++ handlers and a TCP bridge.
Unreal AI Connection
Drive Unreal Engine 5.7 from any MCP-compliant client over a local TCP socket.
146 tools total. Zero pixel-clicking. ~50ms round-trip.
Live capture — an MCP client builds the scene, places Niagara FX (spawn_niagara_at_location), and orbits a camera, entirely over the local TCP socket. Reproduce with scripts/capture_demo_gif.py.
Native C++ handlers — not Python Remote Execution. ~50 ms round-trips across 146 tools · 580 tests · MIT · works with any MCP-compliant client (Claude Code, Cursor, Cline, Codex, Gemini, Continue, Windsurf, Zed, …).
The suite now spans inspection and authoring — read existing assets and create them: actors, levels, data tables/assets, Blueprints (incl. K2 graph nodes), material graphs, Niagara FX, Level Sequence cinematics (camera cuts, audio, visibility), and Movie Render Queue renders — all over the same socket.
⭐ If this saves you time, a star helps other devs find it.
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 binds127.0.0.1:18888). Seedocs/setup/README.mdfor the prerequisite, anddocs/DISTRIBUTION.mdfor 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-connectionCursor — 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 thepylauncher instead ("command": "py"). The.claude-plugin/mcp-config.jsonmarketplace path usespython3for cross-platform consistency — Windows users withoutpython3should use the manual per-client recipe indocs/setup/withpy.
Every other client — copy-paste recipe per client:
Client | Route | Recipe |
Claude Code |
| |
Claude Desktop | edit | |
Cursor | deeplink / | |
Codex CLI |
| |
Windsurf |
| |
Continue |
| |
Cline | MCP Marketplace tab / settings | |
Zed |
| |
Gemini CLI |
| |
VS Code Copilot |
|
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 — 146 tools grouped into 15 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
How it fits together
graph LR
A[Any MCP client] -->|stdio MCP| B[Python Bridge]
B -->|TCP 127.0.0.1:18888| C[UnrealAIConnection 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 146 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
146 tools total. 109 are native C++ handlers registered by the plugin at editor startup; 37 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, import_mesh, material_auto_remap, batch_capture_cameras, batch_spawn_from_csv) 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)
Tool | Purpose |
| Universal escape hatch — run arbitrary |
| Execute a |
| Run a Python snippet with the editor's current selection bound as |
| Persistent Python session — variables defined in one call survive into the next. |
| Wipe the persistent session's globals. |
Project / asset registry (10 tools)
Tool | Purpose |
| Project name, engine version, enabled plugins, asset count. |
| Query the asset registry by class + path + name. |
| Class, tags, dependencies, referencers, on-disk size. |
| Move an asset to a different folder; UE creates a redirector at the source path. |
| Change an asset's leaf name in place; UE creates a redirector at the old name. |
| Copy an asset to a new path. |
| Delete an asset; refuses if referenced by other packages unless |
| Resolve all object redirectors under a folder. |
| Create a new |
| Create a new |
Blueprint / widget / animation — introspection + authoring (20 tools)
Tool | Purpose |
| Variables, function/event graphs, parent class of any Blueprint asset. |
| Recompile a Blueprint asset and report errors. |
| Read the widget hierarchy of a |
| Widget-BP-specific surface: animations, delegate bindings, palette category, inherited named slots, property-binding count, blueprint compile status. Pairs with |
| Mutate the tree: |
| Read variables and state machines of an Animation Blueprint. |
| Read sections, slots, and notify tracks of an |
| LODs, materials, collision, bounds for a |
| LODs, materials, sockets, skeleton info for a |
| Body setups (one per simulated bone), constraint setups (joints between bodies), bounds-bodies subset, named physical-animation + constraint profiles. Cross-links to |
| Emitters and exposed user parameters of a Niagara system. |
| Components, layers, and material info for a landscape actor. |
| RowStruct identity, sorted row names, per-property name+type for every |
| UCurveBase channel layout (1ch UCurveFloat / 4ch UCurveLinearColor / 3ch UCurveVector), per-channel name + key count + per-channel + global time/value range. |
| Create a new |
| Add a typed member variable (bool/int/float/string/name/vector/rotator/transform/object) to an existing |
| Add a new empty function graph to an existing |
| Add a K2 node ( |
| Wire two pins (exec or data) between nodes by GUID + pin name, via the schema-validated |
| Set a literal or object default on an input pin (verified by read-back). |
Materials (6 tools)
Tool | Purpose |
| Create a |
| Override a scalar/vector/texture parameter on a material instance. Type discriminator picks value shape. |
| List parameter names declared by a |
| Read a material instance's parent + currently-overridden parameter values. |
| Create a |
| Wire an expression's output to a material property input ( |
Textures (3 tools)
Tool | Purpose |
| Bring an image file (PNG / JPG / EXR / TGA / BMP / HDR) from disk into the project as a |
| Adjust SRGB / compression / LOD group / filter on an existing texture asset. |
| Texture class, surface dimensions, sRGB, compression, filter, LOD group, mip-gen, virtual-texture / never-stream flags, composite-texture cross-link. UTexture2D-specific size / mips / pixel format / imported source dimensions emitted conditionally. |
Level Sequences (9 tools)
Tool | Purpose |
| Read structure of a Level Sequence: tracks, sections, bindings, frame rate, playback range. |
| Create a new empty Level Sequence asset with a configured display rate and playback range. |
| Add a level actor as a possessable binding to a Level Sequence. |
| Set a Level Sequence's playback start/end (display-rate frames). |
| Spawn an |
| Add (or reuse) the camera-cut track and bind a camera over a |
| Add a master audio track + sound section to a Level Sequence. |
| Add an actor-visibility track that keys an actor shown/hidden over time (inverted |
| Async-render a Level Sequence (optional map override) to PNG / JPG / BMP / EXR via Movie Render Queue; returns a |
Level / actor authoring (24 tools)
Tool | Purpose |
| Name / class / transform of every actor; optional case-insensitive substring filter. |
| Create an actor at a location with optional rotation, label, and initial properties. Class path supports built-ins and Blueprints. |
| Move / rotate / scale an existing actor by name. Absolute or relative mode. |
| Remove an actor by name. Force flag overrides children-attached safety check. |
| Mutate any UPROPERTY on an actor. Supports primitives, FName/FText, vectors, rotators, colors, enums, and TSoftObjectPtr. |
| Attach a component (UActorComponent / USceneComponent subclass) to an existing actor at runtime, optionally socketed. |
| Clone an existing level actor (label or FName), optionally offset and relabel. Undoable (single Ctrl+Z). |
| Set an actor's World Outliner folder path (e.g. |
| Change an actor's World Outliner display label ( |
| Select an actor by label and frame the viewport on it. |
| Open a level by package path. |
| Create a new empty level ( |
| Invoke a static-lighting build on the active editor world. Non-interactive; may take time on large levels. |
| Place a Niagara system in the level ( |
| Attach a Niagara system component to an existing actor, optionally socketed. Undoable. |
| Set a user-exposed Niagara parameter (float / vec3 / linear-color / bool) on a placed Niagara component, with type-match validation. Undoable. |
| Filter the active level's actors by class. Composes |
| Frame the viewport on each actor in a sequence, optionally screenshotting each one. Composes |
| Focus + screenshot each actor in a sequence. Composes |
| Apply many |
| Symmetric diff between two assets' |
| Set many CVars in one call with optional atomic rollback. Composes |
| BFS the asset dependency graph (down by default, optional bidirectional sweep). Composes |
| Resolve redirectors across many content folders in one call. Composes |
Viewport / screenshots (3 tools)
Tool | Purpose |
| Active viewport as a base64 PNG, returned inline. |
| Trigger UE's |
| Force a synchronous render of the level-editor viewport (or an off-screen SceneCapture2D at arbitrary resolution) and write a PNG — works headless where deferred screenshots fail. |
Console / logs (5 tools)
Tool | Purpose |
| Read recent UE Output Log entries from the in-process ring buffer. Filter by category and minimum verbosity. |
| Run a UE console command (e.g. |
| Read a single console variable's current value. |
| Write a value to a console variable. |
| Enumerate console variables matching a name pattern. |
Long-running tasks (4 tools)
Tool | Purpose |
| Reference long-running task — sleeps for N seconds. Used to exercise the task pattern from clients. |
| Read a task's current state / result. |
| Cancel an in-flight task by id. |
| Enumerate all tracked tasks and their states. |
Event push / subscriptions (5 tools)
Tool | Purpose |
| Drain queued editor events (actor spawn/delete, asset add/remove/rename/import, level save, map change) from the in-process EventBus. |
| Bridge-side synthetic tool — block until matching events arrive or |
| Open a per-client subscription channel for a filtered event stream. |
| Drain queued events from a specific subscription. |
| Close a subscription. |
Audio (3 tools — introspection trio)
Tool | Purpose |
| USoundCue duration, multipliers, attenuation cross-link, root sound-node class, full graph node list (sorted, with class taxonomy). |
| USoundWave sample rate, channels, frame count, duration, compression type + runtime format + compressed-data size, sound group, looping/streaming flags, loading behavior, subtitle + cue-point + loop-region counts. Editor-only LUFS / sample-peak / comment fields conditional. |
| USoundAttenuation 3D-playback rules: distance algorithm + shape, spatialization, air-absorption LPF/HPF, listener focus, occlusion tracing, reverb send, priority attenuation, plus assorted feature flags. Each major feature is gated by its master bitfield; sub-objects collapse to |
Camera (3 tools — bridge-side synthetic)
Tool | Purpose |
| Read the level-editor viewport camera's location + rotation. Composes |
| Set the level-editor viewport camera's location and/or rotation. Single |
| Frame the viewport on a specific actor and capture a focused PNG. Composes |
Editor state / undo (2 tools)
Tool | Purpose |
| Step the editor undo stack backward — the programmatic Ctrl+Z. Each mutating MCP edit (spawn/delete/transform/property/component) is one transaction, so this reverts the last such edit (or the last N via |
| Step the editor undo stack forward — the programmatic Ctrl+Y. Re-applies transactions previously reverted by |
Self-introspection (1 tool)
Tool | Purpose |
| Names of every registered method (for autodiscovery). |
Adding the next 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)
Drop the plugin in. Copy
UnrealAIConnection/into<YourProject>/Plugins/.Regenerate project files. Right-click
<YourProject>.uproject→ Generate Visual Studio project files.Build the editor. Open the .sln, build Development Editor | Win64. First build takes ~5–15 min.
Launch. Open the .uproject. The MCP server auto-starts on
127.0.0.1:18888. Look for these lines in the Output Log:[LogUnrealAIConnection] Module started LogUCMCPHandler: Registered handler 'execute_unreal_python' ... (85 more handler lines) [LogUCMCP] Listening on 127.0.0.1:18888Wire your MCP client. Copy
examples/.mcp.json.exampleto your project root as.mcp.json, edit the path to point atbridge/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 — seedocs/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.pyYou'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
UnrealAIConnection/ The Unreal Engine plugin (drop into <Project>/Plugins/)
Source/UnrealAIConnection/ C++ editor module
Resources/ MCP manifest JSON
UnrealAIConnection.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
skills/
driving-unreal/ Bundled know-how skill — which tools to chain for common UE workflows (auto-discovered by MCP clients)
tests/ Pytest suite for the bridge (no UE required)
.github/workflows/ CI runs the bridge tests on every push & PRStatus
Latest release | v0.9.1 — 2026-05-23 (plus |
Tools | 146 live — 109 native C++ handlers (one MCP method per |
Tested on | UE 5.7.4 / Windows 11 / Visual Studio Build Tools 2022 / MSVC 14.44 / NETFXSDK 4.8.1 |
Build status | Plugin compiles + loads against UE 5.7.4 host on Windows 11; 109 handlers register, TCP server binds |
Bridge tests | 580 pytest cases, ~99% coverage |
CI | GitHub Actions on every push and PR |
Development workflow | Multi-agent ensemble — Opus orchestrates, Codex authors C++, Sonnet handles Python + recon, NVIDIA cloud + local OSS LLMs run pre-PR diff review, Copilot CLI gives a second opinion, Gemini auto-review fires on every PR open. No single model gates a merge. |
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.
Prebuilt 5.6 binaries available (Win64). Host-verified build (MSVC 14.38) + live smoke pass (all suites green) on a real 5.6 editor. Skip the source build: download the packaged plugin from the
v0.9.1-ue5.6release and drop it intoYourProject/Plugins/. Load note: enable the engine'sDMXEngine+DMXProtocolplugins (the DMX handlers link against them) or the module fails to load.
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:
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.
Each new MCP handler is one
Handler_*.cppfile inSource/UnrealAIConnection/Private/MCP/Handlers/, plus oneexterndeclaration and oneReg.Register(Make_Handler_*())line inUnrealAIConnectionModule.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).
Maintenance
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/NAJEMWEHBE/unreal-ai-connection'
If you have feedback or need assistance with the MCP directory API, please join our Discord server