CLI 参考 — Unreal Engine · AI Game Developer Wiki

unreal-mcp-cli 是 Unreal MCP 的命令行工具。它安装并更新插件、让你登录 ai-game.dev、为 AI 代理写入 MCP 配置、以正确的连接设置启动 Unreal Editor，并从脚本和 CI 中调用工具。它可在 Windows、macOS 和 Linux 上运行。本页介绍 0.26.2 版本。

安装 CLI

需要 Node.js ^20.19.0 或 >=22.12.0。

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

或者不安装，直接运行单条命令：

npx unreal-mcp-cli@latest status

运行 unreal-mcp-cli <command> --help 查看任意命令的内置帮助。全局 -v, --verbose 标志会打印额外的诊断信息。

注意： 以 [path] 接收项目路径的命令将该参数作为位置参数接受。不带 [path] 的命令则通过 -p, --path <dir> 接收。两者默认都使用当前文件夹。向使用 --path 的命令传入位置路径会报错“too many arguments”。

命令总览

命令	用途
`create-project <path>`	创建一个最小的 Unreal Engine C++ 项目脚手架
`install-plugin [path]`	将 UnrealMCP 插件安装到 `<project>/Plugins`
`update [path]`	更新已安装的插件
`remove-plugin [path]`	移除插件
`install-extension <id> [path]`	安装 Unreal MCP 扩展
`login`	登录 ai-game.dev（设备码流程）
`configure`	将 `UNREAL_MCP_*` 值写入 `<project>/.env`
`setup-mcp [agent]`	为 AI 代理写入 MCP 配置
`setup-skills`	为项目写入 Claude Code 技能
`open [path]`	以连接设置启动 Unreal Editor
`close [path]`	关闭正在运行该项目的编辑器
`exec [code]`	在编辑器中运行 Python
`status`	显示包、项目、插件和连接状态
`wait-for-ready`	等待项目的 MCP 服务器响应
`run-tool <tool>`	通过 HTTP 调用 MCP 工具
`run-system-tool <tool>`	通过 HTTP 调用系统工具
`bootstrap-local [path]`	从源码构建桥接程序
`install-engine [version]`	检测已安装的引擎，给出 Epic 启动器链接

项目设置命令

create-project

创建最小的 C++ 项目脚手架。选项：--name <name>（项目和模块名称；仅限字母、数字和下划线，不能有连字符）、--engine <version>（即 EngineAssociation，例如 5.7）、--force（允许使用非空文件夹）。

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

install-plugin

安装插件。在没有本地源的情况下，它会从 GitHub release 下载与 CLI 版本匹配的插件源码，并先校验其签名。

标志	含义
`--version <v>`	要下载的插件发布版本（默认：CLI 版本）
`--plugin-source <dir>`	使用本地插件文件夹（离线、CI、开发）
`--junction`	链接而非复制（Windows，用于插件开发）
`--with-server`	同时下载经过校验和验证的 `gamedev-mcp-server`
`--server-version <v>`、`--server-source <path-or-url>`	用于 `--with-server` 的服务器版本，或本地/自定义源
`--enroll <code>`、`--enroll-stdin`	使用代理注册码兑换，而不是浏览器登录
`--base-url <url>`	用于 `--enroll` 的认证基础 URL
`-y, --yes`	确认将本机切换到另一个账号

update

重新同步已安装的插件。版本变化时，它会删除过期的 Intermediate/ 和 C++ Binaries/，以便 Unreal 干净地重新构建，同时保留内置的桥接程序。标志：--version <v>、--plugin-source <dir>、--force（重新安装同一版本）、--no-clean（保留构建缓存）。

remove-plugin

从项目中移除 Plugins/UnrealMCP。无选项。

install-extension

安装扩展，并在 .uproject 中启用该扩展及其引擎插件。标志：--version <x.y.z>、--source <dir>、--build（立即编译）、--engine-root <dir>（用于 --build 的引擎）、--force。

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

bootstrap-local

为源码检出从源码构建桥接程序到 <project>/Intermediate/UnrealMCP/；需要 .NET 9 SDK。标志：--repo-root <dir>、--plan（仅打印构建计划）。

install-engine

列出已安装的引擎，或检查某个版本。它从不下载引擎；对于缺失的版本，它会给出 Epic Games Launcher 链接。标志：--manifest <path>（显式指定 LauncherInstalled.dat）、--install、--yes。

登录与 AI 代理命令

使用 OAuth 设备码流程登录，并将凭据保存到 ~/.ai-game-dev/credentials.json，由本机所有 AI Game Dev 工具共享。

标志	含义
`-p, --path <dir>`	将凭据保存到该项目的 `.env`，而不是本机存储
`--tools-only`	为 CI 运行器创建仅限工具的凭据（应用无法使用它）
`-y, --yes`	确认将本机切换到另一个账号
`--base-url <url>`	认证基础 URL（默认 `https://ai-game.dev`）
`--timeout <ms>`	轮询总超时时间

configure

将 UNREAL_MCP_* 值写入 <project>/.env，并将 .env 加入 gitignore。标志：-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。

使用 --agent <id> 时，它改为请求托管的 gamedev-mcp-server 写入固定版本的客户端配置；相关标志为 --url、--server-version 和 --server-source。

setup-mcp

为一个代理写入 MCP 配置条目。代理列表见连接 AI 客户端。

标志	含义
`-p, --path <dir>`	项目文件夹
`--transport <t>`	`http`（默认）或 `stdio`（下载本地服务器）
`--url <url>`	显式指定服务器 URL
`--token <token>`	显式指定 bearer token；优先于项目密钥
`--oauth`	云端：仅 URL 配置，由代理自行登录
`--regenerate-key`	云端：创建新的项目密钥并吊销旧密钥
`--no-pin`	使用普通的 `/mcp` URL，而不是固定到项目的 `/mcp/p/<pin>`
`--dry-run`	只打印片段而不写入
`--list`	列出受支持的代理和配置路径

setup-skills

写入 .claude/skills/unreal-mcp/SKILL.md。标志：-p, --path、--url、--token、--force（覆盖）。

编辑器命令

open

启动 Unreal Editor，并将连接设置作为 UNREAL_MCP_* 环境变量传入。引擎来自项目的 EngineAssociation；源码构建的引擎需要 --engine-root。

标志	含义
`--connection-mode <mode>`	`Custom` 或 `Cloud`；仅指定 `--host` 即隐含 Custom
`--host`、`--token`、`--auth`、`--tools`、`--transport`	设置对应的 `UNREAL_MCP_*` 变量
`--keep-connected`、`--start-server`	将对应变量设为 true
`--no-connect`	不传入任何 `UNREAL_MCP_*` 变量
`--headless`	启动由 CLI 拥有的无窗口编辑器，并等待其就绪
`--idle <seconds>`、`--url <url>`	CLI 拥有的编辑器的空闲关闭时间与服务器 URL
`--engine-root <dir>`	源码构建所用的引擎文件夹
`--no-build`	跳过启动前对原生模块的构建
`--no-auto-dismiss-startup-dialogs`	不自动处理 Unreal 的启动提示框
`--startup-dismiss-timeout-ms`、`--startup-dismiss-poll-interval-ms`	调整提示框关闭行为（默认 12000 和 1000）
`--no-cache`	重新发现引擎路径

在 Linux 上，关闭启动提示框仅适用于 X11。

close

关闭正在运行该项目的编辑器。使用 --owned-only 时只关闭由 CLI 启动的编辑器（通过 exec 或 open --headless），它会保存并退出；你自行打开的编辑器绝不会被触及。--force 会强制杀死未及时退出的 CLI 拥有的编辑器；--token 覆盖 bearer token。

exec

通过 python-execute 在编辑器中运行 Python。它复用正在运行的编辑器，或启动一个离屏渲染的无窗口编辑器（因此截图仍可正常工作），并在一段时间没有工具调用后退出。

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

标志：-p, --path、-f, --file <file>（- 表示 stdin）、--include <path>（来自 .ai-game-dev/snippets 的辅助片段，可重复）、--window、--idle <seconds>（默认 300，0 表示从不）、--ready-timeout <ms>、--timeout <ms>、--raw（打印 JSON 响应）、--url、--token、--engine-root、--no-build。结果打印到 stdout；print() 和日志行打印到 stderr。

工具与状态命令

status 与 wait-for-ready

status 报告 CLI、项目、插件和连接状态，并执行实时可达性探测（--no-probe 可跳过）。wait-for-ready 会阻塞直到服务器响应 ping（--timeout，默认 120000 毫秒；--interval，默认 2000 毫秒）。两者都接受 -p, --path、--url 和 --token。

run-tool 与 run-system-tool

通过项目的本地 MCP 服务器调用一个工具：

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

标志：-p, --path、--url、--token、--input <json>、--input-file <file>（- 表示 stdin）、--timeout <ms>（默认 60000）。

相同的逻辑也以带类型的库形式提供（import { openProject, runTool } from 'unreal-mcp-cli'），供 AI Game Dev 应用使用。

安装 CLI#

命令总览#

项目设置命令#

create-project#

install-plugin#

update#

remove-plugin#

install-extension#

bootstrap-local#

install-engine#

登录与 AI 代理命令#

login#

configure#

setup-mcp#

setup-skills#

编辑器命令#

open#

close#

exec#

工具与状态命令#

status 与 wait-for-ready#

run-tool 与 run-system-tool#