`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](https://github.com/IvanMurzak/Unity-MCP) and [Godot-MCP](https://github.com/IvanMurzak/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](https://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](https://github.com/IvanMurzak/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 **27 built-in tools across 7 families** (plus 3 system tools) — the editor data layer is one query language, [RQL](docs/rql.md) 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](https://discord.gg/cfbdMZX99G)** — 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
- ✔️ **RQL data layer** — query and change actors, components, assets, levels and editor state with one language ([`rql-query` / `rql-mutate` / `rql-schema`](#tools))
- ✔️ **27 built-in Tools** — [MCP Tools](#tools) across **7 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](https://github.com/IvanMurzak/GameDev-MCP-Server)
- ✔️ **Per-tool visibility** — Choose which tools are listed in `tools/list` from the **MCP Tools** window (a hidden tool still runs when called by name)
# Table of contents
> First-party extensions now use independent component releases and an online CLI index.
> See [the monorepo test/release guide](docs/EXTENSION-MONOREPO.md); it supersedes legacy per-repository release instructions below.
- [Requirements](#requirements)
- [Install](#install)
- [Updating the plugin](#updating-the-plugin)
- [First run](#first-run)
- [Tools](#tools) — all 7 families, 27 tools (+ 3 system tools)
- [Install Additional Skills and Tools](#install-additional-skills-and-tools)
- [Per-tool visibility](#per-tool-visibility)
- [`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](https://github.com/IvanMurzak/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](https://www.fab.com/) (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.
Fab accepts no executables, so the Fab package does not bundle the `unreal-mcp-bridge` sidecar. On first launch the editor downloads it (~32 MB) for its own plugin version from this repository's GitHub Release, checks it against the SHA-256 shipped inside the plugin, and caches it per user (`%LOCALAPPDATA%\UnrealMCP\bridge` on Windows). This needs internet once; while it runs the AI Game Developer window shows "Downloading the MCP bridge…", and a failure (offline, firewall) is shown there with a retry via **Restart bridge**. For an offline machine use Option B, which bundles the sidecar.
## 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**. By default `install-plugin` / `update` use a local `UnrealMCP/` checkout when one is present; otherwise they download the dedicated `unreal-mcp-plugin-source-
