Unreal MCP

✨ AI Game Developer — Unreal MCP

[](https://modelcontextprotocol.io/introduction) [](https://www.unrealengine.com/) [](https://www.unrealengine.com/) [](https://www.unrealengine.com/) [](https://github.com/IvanMurzak/Unreal-MCP/actions/workflows/release.yml) [](https://discord.gg/cfbdMZX99G) [](https://github.com/IvanMurzak/Unreal-MCP/stargazers) [](https://hub.docker.com/r/aigamedeveloper/mcp-server) [](https://github.com/IvanMurzak/Unreal-MCP/blob/main/LICENSE) [](https://stand-with-ukraine.pp.ua)

                                

Unreal MCP is an AI-powered game development assistant for the Unreal Editor. Connect Claude, Cursor, Copilot, or any MCP-aware agent to Unreal Engine and let it inspect and drive your project — spawn actors, edit levels, author Blueprints, manage assets, edit and compile C++, capture screenshots, and more.

Unreal-MCP is the Unreal Engine counterpart of Unity-MCP and Godot-MCP: a C++ editor plugin that exposes Unreal Editor operations as AI Tools and connects them to an MCP server through the same hosted cloud backend (ai-game.dev) that powers Unity-MCP and Godot-MCP — or your own self-hosted server. The local server is the shared, engine-agnostic GameDev-MCP-Server (binary gamedev-mcp-server) — one server consumed by Unity-MCP, Godot-MCP, and Unreal-MCP; no server source lives in this repo.

Unlike Unity and Godot (C# engines that host the .NET McpPlugin in-process), Unreal's editor is C++ — so the .NET MCP host runs as an auto-managed sidecar process (unreal-mcp-bridge) that the plugin spawns and talks to over a localhost IPC channel. The full design lives in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) (see the §0 system-overview diagram).

> Status: beta. The plugin, the .NET sidecar, the unreal-mcp-cli, the AI Game Developer editor UI, and 62 built-in tools across 8 families have shipped and are exercised by CI. The unreal-mcp-cli is published on npm — install the plugin with it (Option B below); the Fab / Epic Marketplace listing for the precompiled plugin is coming soon (Option A). Pixel-capture (screenshot) tools need a GPU-backed editor; everything else runs headless.

> 💬 Join our Discord Server — Ask questions, showcase your work, and connect with other developers!

• ✔️ AI agents — Use the best agents from Anthropic, OpenAI, Google, or any other provider with no vendor lock-in
• ✔️ 62 built-in Tools — A wide range of [MCP Tools](#tools) across 8 families for operating the Unreal Editor
• ✔️ Blueprint authoring — Create, edit, and compile Blueprints with a structured error/warning feedback loop the AI can act on
• ✔️ C++ edit & compile — Read, scaffold, and edit project C++, then compile (Live Coding or UBT) with a structured error report
• ✔️ Visual feedback — Capture viewport, game-view, camera, and isolated-actor screenshots the LLM can inspect directly
• ✔️ Custom Tools, Prompts & Resources — Register your own AI Tools, prompt templates, and resources from any UE plugin with no fork — one public, modular-feature contract ([Customize Tools, Prompts & Resources](#customize-tools-prompts--resources))
• ✔️ Cloud or self-hosted — Connect to ai-game.dev out of the box, or point at your own GameDev-MCP-Server
• ✔️ Per-tool enable / disable — Flip any tool on or off from the MCP Tools window; the toggle is enforced at the execution boundary, not just hidden

Table of contents

• [Requirements](#requirements)
• [Install](#install)
• [Updating the plugin](#updating-the-plugin)
• [First run](#first-run)
• [Tools](#tools) — all 8 families, 62 tools
• [Per-tool enable / disable](#per-tool-enable--disable)
• [unreal-mcp-cli](#unreal-mcp-cli)
• [Customize Tools, Prompts & Resources](#customize-tools-prompts--resources)
• [Runtime usage (in-game)](#runtime-usage-in-game)
• [Editor-only — exclude Unreal-MCP from packaged games](#editor-only-exclude-from-packaged-games)
• [Configuration & environment variables](#configuration--environment-variables)
• [Troubleshooting](#troubleshooting)
• [How Unreal MCP Architecture Works](#how-unreal-mcp-architecture-works)
• [Repo layout](#repo-layout)
• [Links](#links)
• [License](#license)

Requirements

• Unreal Engine 5.5+ (developed and CI-tested against 5.7, and verified to build & run on 5.8). The plugin deliberately ships no EngineVersion pin — UE treats that field as an exact-build match, not a floor, and would refuse to load on newer engines.
• .NET 9 SDK to build the bridge sidecar from source. (End users of a packaged release do NOT need it — the self-contained sidecar is bundled inside the plugin and auto-spawned, ARCHITECTURE §6. The local MCP server is downloaded as a prebuilt GameDev-MCP-Server release binary, never built here.)
• Node.js ^20.19.0 || >=22.12.0 for the optional unreal-mcp-cli.
• A C++ Unreal project (the plugin builds an Editor module, so the host project must be able to compile C++).

Install

There are three ways to install the plugin, in order of preference. Fab / Epic Marketplace is the recommended channel for end users — it ships precompiled, per-engine binaries and the Epic Games Launcher keeps them up to date automatically, so there is zero compile and zero stale-build risk. Source / unreal-mcp-cli installs remain the current path for developers and early adopters until the Fab listing goes live.

Option A — Fab / Epic Marketplace (recommended; coming soon)

> Status: not yet live. The Fab listing is operator-gated and tracked separately; until it publishes, use Option B or C below. The framing here is what the end-user flow will be.

1. Install Unreal-MCP from Fab (the Epic Marketplace successor) into your engine via the Epic Games Launcher.
2. Enable the plugin for your project from Edit → Plugins.
3. Open the project — UE loads the precompiled plugin (no C++ build on your machine). On boot the Output Log prints [Unreal-MCP] plugin loaded.

Because Fab ships precompiled binaries and the Epic Launcher updates them in place, you never compile the plugin and never have to clear a stale build cache — the most robust path for non-developers.

Option B — unreal-mcp-cli (current / advanced)

The CLI is the recommended path today, until the Fab listing is live. Install it from npm — no repo clone, no build step. It copies (or, for dev, junctions) the plugin into your project and, on update, automatically clears the stale UE build cache so you always get a clean recompile of the new code (see [Updating the plugin](#updating-the-plugin)).

# 1. Install unreal-mcp-cli (or use `npx unreal-mcp-cli@latest ` for a one-off, no install)
npm install -g unreal-mcp-cli

# 2. Install the UnrealMCP plugin into your project
unreal-mcp-cli install-plugin ./YourProject

# 3. Authorize against the cloud server (ai-game.dev)
unreal-mcp-cli login ./YourProject

# 4. Open the Unreal Editor for the project (wires the MCP connection env vars)
unreal-mcp-cli open ./YourProject

See [cli/README.md](cli/README.md) for the full 16-command reference.

Option C — manual

1. Copy [UnrealMCP/](UnrealMCP/) into /Plugins/UnrealMCP/ (or create a directory junction / symlink to it for live development).
2. Open the project; UE compiles the UnrealMcpEditor module on first launch.
3. On editor boot the Output Log prints [Unreal-MCP] plugin loaded — that confirms the plugin and its game-thread dispatcher started.

The sidecar binary (unreal-mcp-bridge) is bundled inside the plugin in a packaged release: a prebuilt, self-contained binary for your platform ships under UnrealMCP/Binaries/ThirdParty/UnrealMcpBridge// and the editor auto-spawns it on startup with zero user action — no .NET install, no env var, no manual launch (ARCHITECTURE §6). The first Cloud OAuth device-code browser approval is the only remaining human step; after that, reconnect on later launches is zero-click (the cloud token is cached in Saved/Config/UnrealMcp/).

When you build the plugin from source (the only option until the first GitHub Release / Fab listing), the bundled binary is not present — the plugin then resolves the sidecar from the UNREAL_MCP_BRIDGE_PATH environment variable instead: point that at a locally built sidecar, or run unreal-mcp-cli bootstrap-local to build the bridge from source into /Intermediate/UnrealMCP/ and set the var to the result. With neither a bundled binary nor the env var resolved, the plugin's TCP listener still starts but logs [Unreal-MCP] no sidecar binary resolved for rid … and spawns nothing.

Updating the plugin

Updating in place must always leave you running the new code. The risk is UE's incremental compiler: if the plugin source changes (new .cpp files, a new module) but the old UnrealMCP/Intermediate/ build cache survives, UE can do a partial recompile against a stale module file-list and silently leave you on old/partial code. Each channel handles this differently:

• Fab / Epic Marketplace → automatic. The Epic Games Launcher replaces the precompiled binaries in place; nothing to compile, no cache to clear. This is why Fab is the recommended channel.
• unreal-mcp-cli update → automatic clean rebuild. update re-copies the plugin source and, by default, deletes the installed plugin's stale Intermediate/ and the C++ Binaries/ so UE performs a clean compile on the next editor launch — no manual steps. The bundled sidecar bridge under Binaries/ThirdParty/UnrealMcpBridge// is always preserved (only the C++ module outputs are cleared). Dev junction installs are never cleaned (that would wipe your live source tree's outputs). Pass --no-clean to opt out of the cache wipe.

``bash node bin/unreal-mcp-cli.js update # default: clean rebuild on version change node bin/unreal-mcp-cli.js update --force # re-copy even when versions match node bin/unreal-mcp-cli.js update --no-clean # keep the existing build cache ``

• Manual copy → clear the cache yourself. If you overwrite /Plugins/UnrealMCP/ by hand, close the editor first, delete /Plugins/UnrealMCP/Intermediate/ and the C++ Binaries/ (keep Binaries/ThirdParty/ if a bundled bridge is present), then relaunch so UE recompiles cleanly.

First run

1. Open the AI Game Developer main window from the editor's Tools menu (the tab is registered under the Tools menu category).
2. Choose a connection mode:

• Cloud (default) — connects to ai-game.dev. Click Authorize to start the OAuth device-code flow: the window shows a verification URL and a short user code; open the URL, enter the code, approve, and the editor finishes authorizing. Use Revoke to clear the stored cloud token.
• Custom — connects to a local gamedev-mcp-server you run (or any compatible server). Enter the server URL and point your AI client at it. (The plugin does not start the local server for you — run unreal-mcp-cli or your own process; see [Troubleshooting](#troubleshooting).)

1. The Connection section shows a status dot, a status label, and a Connect / Disconnect / Stop button; the bridge status reads Running (restarts: N) or Stopped. Use them to confirm the sidecar is live.
2. Point your AI client (Claude Code, Cursor, the AI Game Developer app, …) at the server. The AI agents section lists the agents currently connected; to write an MCP client config use unreal-mcp-cli setup-mcp.

Connection settings persist to /Saved/Config/UnrealMcp/ai-game-developer-config.json (Saved/ is gitignored by every UE template, so tokens never land in VCS by default).

> That's it. Ask your AI "Spawn three cubes in a row and a point light above them" and watch it happen. ✨

Tools

Unreal-MCP ships 62 built-in ("core") tools across 8 families. Tool ids are kebab-case (actor-create, blueprint-compile), matching the Unity/Godot naming convention. Extensions can add more (see [Customize Tools, Prompts & Resources](#customize-tools-prompts--resources)).

> This list is generated from the registration source (UnrealMCP/Source/UnrealMcpEditor/Private/Tools/UnrealMcp*Tools.cpp). Counts: actor 13, blueprint 11, asset 11, editor/reflection 9, level 7, source 6, screenshot 4, ping 1 = 62.

Actor & component family (13)

| Tool id | What it does | | --- | --- | | actor-create | Spawn an actor from a class path (native or Blueprint), with optional name/location/rotation/parent | | actor-destroy | Destroy an actor | | actor-duplicate | Duplicate an actor | | actor-find | Find actors, with scoped reads (paths/viewQuery) | | actor-modify | Write actor FProperty values (including transform) | | actor-set-parent | Attach an actor to a parent | | actor-component-add | Add a component to an actor | | actor-component-destroy | Destroy a component | | actor-component-get | Read a component's data | | actor-component-modify | Modify a component's properties | | actor-component-list-all | List available UActorComponent classes (paginated) | | object-get-data | Read any UObject by path | | object-modify | Modify any UObject by path |

Blueprint family (11) — Unreal's flagship surface

| Tool id | What it does | | --- | --- | | blueprint-create | Create a new Blueprint class from a parent UClass path | | blueprint-get | Graph summary for LLM inspection (variables, components, functions/events, parent chain) | | blueprint-add-component | Add a component via the Simple Construction Script | | blueprint-remove-component | Remove an SCS component | | blueprint-add-variable | Add a typed member variable | | blueprint-modify-variable | Modify a member variable | | blueprint-set-default | Edit a CDO (class-default) property | | blueprint-add-function | Add a function stub (entry/result nodes wired) | | blueprint-add-event | Add/bind an event stub (BeginPlay, Tick, input, …) | | blueprint-compile | Compile the Blueprint and return a structured error/warning list (the AI feedback loop) | | blueprint-spawn | Instance the Blueprint into the current level |

Asset / Content-Browser family (11)

| Tool id | What it does | | --- | --- | | asset-find | Search the AssetRegistry by name/class/path/tags | | asset-get-data | Read an asset's data (scoped reads supported) | | asset-create-folder | Create a Content folder | | asset-copy | Copy an asset | | asset-move | Move / rename an asset | | asset-delete | Delete an asset | | asset-refresh | Rescan asset paths | | asset-material-create | Create a Material Instance from a parent material | | asset-material-modify | Set scalar/vector/texture material-instance parameters | | asset-material-get-data | Read material graph/parameter info (the "shader" analog) | | asset-import | Import FBX/textures via AssetImportTask |

Editor / console / reflection family (9)

| Tool id | What it does | | --- | --- | | editor-application-get-state | Read editor application state (PIE, etc.) | | editor-application-set-state | Start / stop / pause Play-In-Editor | | editor-selection-get | Read the current editor selection | | editor-selection-set | Set the editor selection | | console-get-logs | Read recent editor logs from the LogCollector ring buffer | | console-clear-logs | Cle

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IvanMurzak
• Source: IvanMurzak/Unreal-MCP
• License: Apache-2.0
• Homepage: https://ai-game.dev

Install and usage instructions live in the source repository linked above.