Installation

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.

Requirements#

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. The app installation guide 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. Details are in 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:

npm install -g unreal-mcp-cli

Or run any command once without installing it:

npx unreal-mcp-cli@latest status

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

# 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 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:

[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.

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.

Remove the plugin#

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:

{
  "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.