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.
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.
npm install -g unreal-mcp-cli
unreal-mcp-cli --versionOr run a single command without installing:
npx unreal-mcp-cli@latest statusRun 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).
unreal-mcp-cli create-project ./MyGame --engine 5.7install-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, 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.
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --buildbootstrap-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 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.
unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGameFlags: -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:
unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGameFlags: -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.