# CLI reference

Complete unreal-mcp-cli command reference - install the Unreal MCP plugin, sign in, configure AI agents, open the editor, run tools and Python.

_Last updated: 2026-11-04_

`unreal-mcp-cli` is the command-line tool for Unreal MCP. It installs and updates the plugin, signs you in to ai-game.dev, writes MCP configs for AI agents, launches the Unreal Editor with the right connection settings, and calls tools from scripts and CI. It runs on Windows, macOS and Linux. This page covers version 0.26.2.

## Install the CLI

Requires Node.js `^20.19.0` or `>=22.12.0`.

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

Or run a single command without installing:

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

Run `unreal-mcp-cli <command> --help` for the built-in help of any command. The global `-v, --verbose` flag prints extra diagnostics.

**Note:** Commands that take the project as `[path]` accept it as a positional argument. Commands without `[path]` take it with `-p, --path <dir>`. Both default to the current folder. Passing a positional path to a `--path` command fails with "too many arguments".

## Command overview

| Command | Purpose |
| --- | --- |
| `create-project <path>` | Scaffold a minimal Unreal Engine C++ project |
| `install-plugin [path]` | Install the UnrealMCP plugin into `<project>/Plugins` |
| `update [path]` | Update the installed plugin |
| `remove-plugin [path]` | Remove the plugin |
| `install-extension <id> [path]` | Install an Unreal MCP extension |
| `login` | Sign in to ai-game.dev (device-code flow) |
| `configure` | Write `UNREAL_MCP_*` values into `<project>/.env` |
| `setup-mcp [agent]` | Write an MCP config for an AI agent |
| `setup-skills` | Write a Claude Code skill for the project |
| `open [path]` | Launch the Unreal Editor with connection settings |
| `close [path]` | Close the editor running the project |
| `exec [code]` | Run Python in the editor |
| `status` | Show package, project, plugin and connection state |
| `wait-for-ready` | Wait until the project's MCP server answers |
| `run-tool <tool>` | Call an MCP tool over HTTP |
| `run-system-tool <tool>` | Call a system tool over HTTP |
| `bootstrap-local [path]` | Build the bridge from source |
| `install-engine [version]` | Detect installed engines, link to the Epic launcher |

## Project setup commands

### create-project

Scaffolds a minimal C++ project. Options: `--name <name>` (project and module name; letters, digits and underscores, no hyphens), `--engine <version>` (the `EngineAssociation`, for example `5.7`), `--force` (allow a non-empty folder).

```bash
unreal-mcp-cli create-project ./MyGame --engine 5.7
```

### install-plugin

Installs the plugin. Without a local source it downloads the plugin source that matches the CLI version from the GitHub release and verifies its signature first.

| Flag | Meaning |
| --- | --- |
| `--version <v>` | Plugin release to download (default: the CLI version) |
| `--plugin-source <dir>` | Use a local plugin folder (offline, CI, development) |
| `--junction` | Link instead of copy (Windows, for plugin development) |
| `--with-server` | Also download the checksum-verified `gamedev-mcp-server` |
| `--server-version <v>`, `--server-source <path-or-url>` | Server version, or a local or custom source, for `--with-server` |
| `--enroll <code>`, `--enroll-stdin` | Redeem an agent enrollment code instead of a browser sign-in |
| `--base-url <url>` | Auth base URL for `--enroll` |
| `-y, --yes` | Confirm switching the machine to another account |

### update

Re-syncs the installed plugin. On a version change it removes the stale `Intermediate/` and C++ `Binaries/` so Unreal rebuilds cleanly, keeping the bundled bridge. Flags: `--version <v>`, `--plugin-source <dir>`, `--force` (re-install the same version), `--no-clean` (keep the build cache).

### remove-plugin

Removes `Plugins/UnrealMCP` from the project. No options.

### install-extension

Installs an [extension](https://ai-game.dev/docs/wiki/unreal/extensions), enables it and its engine plugin in the `.uproject`. Flags: `--version <x.y.z>`, `--source <dir>`, `--build` (compile now), `--engine-root <dir>` (engine for `--build`), `--force`.

```bash
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --build
```

### bootstrap-local

Builds the bridge from source into `<project>/Intermediate/UnrealMCP/` for source checkouts; needs the .NET 9 SDK. Flags: `--repo-root <dir>`, `--plan` (print the build plan only).

### install-engine

Lists installed engines, or checks for one version. It never downloads an engine; for a missing version it gives you an Epic Games Launcher link. Flags: `--manifest <path>` (explicit `LauncherInstalled.dat`), `--install`, `--yes`.

## Sign-in and AI agent commands

### login

Signs in with the OAuth device-code flow and saves the credential to `~/.ai-game-dev/credentials.json`, shared by every AI Game Dev tool on the machine.

| Flag | Meaning |
| --- | --- |
| `-p, --path <dir>` | Save the credential to that project's `.env` instead of the machine store |
| `--tools-only` | Create a tools-only credential for CI runners (the app cannot use it) |
| `-y, --yes` | Confirm switching the machine to another account |
| `--base-url <url>` | Auth base URL (default `https://ai-game.dev`) |
| `--timeout <ms>` | Overall polling timeout |

### configure

Writes `UNREAL_MCP_*` values into `<project>/.env` and gitignores `.env`. Flags: `-p, --path`, `--mode <Cloud|Custom>`, `--host <url>`, `--cloud-url <url>`, `--token <token>`, `--auth <option>`, `--keep-connected`, `--tools <list>`, `--start-server`, `--transport <stdio|http>`, `--log-level <level>`, `--no-gitignore`.

With `--agent <id>` it instead asks the managed `gamedev-mcp-server` to write a pinned client config; related flags are `--url`, `--server-version` and `--server-source`.

### setup-mcp

Writes an MCP config entry for one agent. See [Connecting AI clients](https://ai-game.dev/docs/wiki/unreal/connecting-ai-clients#setup-mcp) for the agent list.

| Flag | Meaning |
| --- | --- |
| `-p, --path <dir>` | Project folder |
| `--transport <t>` | `http` (default) or `stdio` (downloads the local server) |
| `--url <url>` | Explicit server URL |
| `--token <token>` | Explicit bearer token; wins over the project key |
| `--oauth` | Cloud: URL-only config, the agent signs in itself |
| `--regenerate-key` | Cloud: create a new project key and revoke the old one |
| `--no-pin` | Plain `/mcp` URL instead of the project-pinned `/mcp/p/<pin>` |
| `--dry-run` | Print the snippet without writing it |
| `--list` | List supported agents and config paths |

### setup-skills

Writes `.claude/skills/unreal-mcp/SKILL.md`. Flags: `-p, --path`, `--url`, `--token`, `--force` (overwrite).

## Editor commands

### open

Launches the Unreal Editor and passes the connection settings as `UNREAL_MCP_*` environment variables. The engine comes from the project's `EngineAssociation`; a source-built engine needs `--engine-root`.

| Flag | Meaning |
| --- | --- |
| `--connection-mode <mode>` | `Custom` or `Cloud`; `--host` alone implies Custom |
| `--host`, `--token`, `--auth`, `--tools`, `--transport` | Set the matching `UNREAL_MCP_*` variable |
| `--keep-connected`, `--start-server` | Set the matching variable to true |
| `--no-connect` | Pass no `UNREAL_MCP_*` variables |
| `--headless` | Start a windowless editor owned by the CLI and wait until it is ready |
| `--idle <seconds>`, `--url <url>` | Idle shutdown and server URL for a CLI-owned editor |
| `--engine-root <dir>` | Engine folder for source builds |
| `--no-build` | Skip the pre-launch build of native modules |
| `--no-auto-dismiss-startup-dialogs` | Leave Unreal's start-up prompts alone |
| `--startup-dismiss-timeout-ms`, `--startup-dismiss-poll-interval-ms` | Tune prompt dismissal (defaults 12000 and 1000) |
| `--no-cache` | Rediscover the engine path |

On Linux, dismissing start-up prompts works on X11 only.

### close

Closes the editor running the project. With `--owned-only` it closes only an editor the CLI started (via `exec` or `open --headless`), which saves and quits; an editor you opened is never touched. `--force` kills a CLI-owned editor that does not quit in time; `--token` overrides the bearer token.

### exec

Runs Python in the editor through `python-execute`. It reuses a running editor, or starts a headless one that renders off-screen (so screenshots still work) and quits after a period without tool calls.

```bash
unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGame
```

Flags: `-p, --path`, `-f, --file <file>` (`-` for stdin), `--include <path>` (helpers from `.ai-game-dev/snippets`, repeatable), `--window`, `--idle <seconds>` (default 300, 0 = never), `--ready-timeout <ms>`, `--timeout <ms>`, `--raw` (print the JSON response), `--url`, `--token`, `--engine-root`, `--no-build`. Results print on stdout; `print()` and log lines on stderr.

## Tool and status commands

### status and wait-for-ready

`status` reports the CLI, project, plugin and connection, with a live reachability probe (`--no-probe` skips it). `wait-for-ready` blocks until the server answers a ping (`--timeout`, default 120000 ms; `--interval`, default 2000 ms). Both accept `-p, --path`, `--url` and `--token`.

### run-tool and run-system-tool

Call one tool over the project's local MCP server:

```bash
unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGame
```

Flags: `-p, --path`, `--url`, `--token`, `--input <json>`, `--input-file <file>` (`-` for stdin), `--timeout <ms>` (default 60000).

The same logic is available as a typed library (`import { openProject, runTool } from 'unreal-mcp-cli'`), used by the [AI Game Dev app](https://ai-game.dev/docs/wiki/app).

---

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