# Installation

Install the Unreal MCP plugin for Unreal Engine 5.5+ with the AI Game Dev app or unreal-mcp-cli. Requirements, updates, removal and Fab status.

_Last updated: 2026-11-04_

This page shows how to install Unreal MCP, the AI Game Developer plugin for Unreal Engine, into a project. Pick one install path, follow its steps, then continue with [Getting started](https://ai-game.dev/docs/wiki/unreal/getting-started).

## Requirements

| Requirement | Details |
| --- | --- |
| Unreal Engine | 5.5 or newer. Release builds are validated against 5.5, 5.6, 5.7 and 5.8. |
| Project type | A **C++ Unreal project**. The plugin contains editor modules that are compiled for your project, so the project must be able to build C++. |
| C++ toolchain | The compiler toolchain your Unreal Engine version needs on your platform (for example Visual Studio on Windows, Xcode on macOS). |
| Operating system | Windows (x64), macOS (Apple silicon and Intel) and Linux (x64). The release ships a bridge build for each of these. |
| Node.js | Only for `unreal-mcp-cli`: `^20.19.0` or `>=22.12.0`. The desktop app does not need it. |
| .NET 9 SDK | Only if you build the bridge from source. Packaged installs bundle it. |

The plugin does not pin an exact engine version in its descriptor, so the same plugin loads on newer engine releases.

**Note:** A Blueprint-only project needs a C++ module before it can build plugins. In the Unreal Editor, add any C++ class (Tools, New C++ Class) to turn it into a C++ project, or create a fresh C++ project with `unreal-mcp-cli create-project`.

## Option 1: the AI Game Dev desktop app

The desktop app is the simplest path. It bundles the install logic, so you do not need Node.js, npm or a terminal.

1. Install AI Game Dev from the [download page](https://ai-game.dev/download). The [app installation guide](https://ai-game.dev/docs/wiki/app/installation) walks through it.
2. Sign in with your ai-game.dev account.
3. Choose **Open folder…** and pick your Unreal project folder (the folder that contains the `.uproject` file). The app detects it as an Unreal project. Or use **Create new project** to make a new one; the plugin is then installed automatically.
4. Click **Install Package** in the sidebar. The app installs the newest released Unreal MCP version and verifies the download first. If the installed plugin is already newer, the app keeps it.
5. Click **Open Editor** to launch the Unreal Editor with your signed-in session, so the plugin connects through ai-game.dev without a manual token.

In the app's CLI the same actions are the `/install-plugin` and `/open` commands. The app can also install the optional [extensions](https://ai-game.dev/docs/wiki/unreal/extensions). Details are in [Projects and engines](https://ai-game.dev/docs/wiki/app/projects-and-engines).

## Option 2: unreal-mcp-cli

`unreal-mcp-cli` is published on npm and works on Windows, macOS and Linux. It needs no clone of the repository and no build step of its own.

Install the CLI globally:

```bash
npm install -g unreal-mcp-cli
```

Or run any command once without installing it:

```bash
npx unreal-mcp-cli@latest status
```

Then install the plugin, sign in and open the editor:

```bash
# 1. Install the UnrealMCP plugin into <project>/Plugins/UnrealMCP
unreal-mcp-cli install-plugin ./YourProject

# 2. Sign in to ai-game.dev once per machine (device-code flow in your browser)
unreal-mcp-cli login

# 3. Open the Unreal Editor for the project
unreal-mcp-cli open ./YourProject
```

What these commands do:

- `install-plugin` downloads the plugin source that matches the CLI version (`unreal-mcp-plugin-source-<version>.zip` from the GitHub release) and checks its signature before extracting it. A tampered or unsigned download is refused. The bridge for your platform comes inside that package.
- `login` stores your credential in the machine-wide store (`~/.ai-game-dev/credentials.json`), shared with the app and the other engine CLIs.
- `open` finds the right engine from the project's `EngineAssociation`, builds the native editor modules first when they need compiling, and dismisses the known Unreal start-up prompts (such as "Missing Modules") if they still appear.

**Tip:** Close the Unreal Editor before you install or update the plugin. Unreal cannot replace a plugin that a running editor has loaded.

## Option 3: manual install from source

Manual install is meant for contributors and plugin development.

1. Copy the `UnrealMCP/` folder from the [Unreal-MCP repository](https://github.com/IvanMurzak/Unreal-MCP) into `<YourProject>/Plugins/UnrealMCP/`.
2. A source checkout has no bundled bridge. Build one with `unreal-mcp-cli bootstrap-local ./YourProject` (needs the .NET 9 SDK), or point `UNREAL_MCP_BRIDGE_PATH` at a bridge you built.
3. Open the project. Unreal compiles the plugin's modules on first launch.

For live development, `unreal-mcp-cli install-plugin --junction` links the plugin folder instead of copying it (Windows).

## Fab / Epic Marketplace

A Fab listing is planned but **not live yet**. Until it is published there is nothing to install from Fab; use the app or the CLI.

## Check the install

When the editor starts, the Output Log prints:

```text
[Unreal-MCP] plugin loaded
```

You can also run `unreal-mcp-cli status --path ./YourProject` to see the package, project, plugin and connection state.

The plugin then appears under the editor's **Tools** menu as **AI Game Developer**. Continue with [Getting started](https://ai-game.dev/docs/wiki/unreal/getting-started).

## Update the plugin

- **App:** the sidebar shows **Update Package** when a newer plugin release exists.
- **CLI:** run `unreal-mcp-cli update ./YourProject`. On a version change it deletes the installed plugin's `Intermediate/` folder and its compiled C++ `Binaries/` so Unreal does a clean rebuild, and it keeps the bundled bridge. Add `--force` to re-install the same version, or `--no-clean` to keep the build cache.
- **Manual copy:** close the editor, delete `Plugins/UnrealMCP/Intermediate/` and the C++ `Binaries/` (keep `Binaries/ThirdParty/`), then reopen the project.

A stale build cache is the most common reason an update seems to have no effect. See [Troubleshooting](https://ai-game.dev/docs/wiki/unreal/troubleshooting#stale-build).

## Remove the plugin

```bash
unreal-mcp-cli remove-plugin ./YourProject
```

Or delete `<YourProject>/Plugins/UnrealMCP/` with the editor closed.

## Keep the plugin out of packaged games

If you use Unreal MCP only for AI help in the editor, exclude it from packaged builds in **your project's** `.uproject` plugin entry:

```json
{
  "Name": "UnrealMCP",
  "Enabled": true,
  "TargetDenyList": ["Game", "Client", "Server"]
}
```

The plugin then stays active in the editor but nothing of it, including the bridge, is compiled or staged into a packaged game. Do not add any `UnrealMcp*` module to your game module's `Build.cs` dependencies: a direct dependency overrides the deny list. To use AI tools inside a running game instead, see [in-game tools](https://ai-game.dev/docs/wiki/unreal/custom-tools#runtime).

---

Source (HTML): https://ai-game.dev/docs/wiki/unreal/installation