# CLI 参考 — Unreal Engine · AI Game Developer Wiki

完整的 unreal-mcp-cli 命令参考 - 安装 Unreal MCP 插件、登录、配置 AI 代理、打开编辑器、运行工具和 Python。

本页由英文机器翻译而成。[阅读英文原文](https://ai-game.dev/docs/wiki/unreal/cli)。

`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`。

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

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

```bash
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`（允许使用非空文件夹）。

```bash
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

安装[扩展](https://ai-game.dev/zh-hans/docs/wiki/unreal/extensions)，并在 `.uproject` 中启用该扩展及其引擎插件。标志：`--version <x.y.z>`、`--source <dir>`、`--build`（立即编译）、`--engine-root <dir>`（用于 `--build` 的引擎）、`--force`。

```bash
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 代理命令

### login

使用 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 客户端](https://ai-game.dev/zh-hans/docs/wiki/unreal/connecting-ai-clients#setup-mcp)。

| 标志 | 含义 |
| --- | --- |
| `-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。它复用正在运行的编辑器，或启动一个离屏渲染的无窗口编辑器（因此截图仍可正常工作），并在一段时间没有工具调用后退出。

```bash
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 服务器调用一个工具：

```bash
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 应用](https://ai-game.dev/zh-hans/docs/wiki/app)使用。

---

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

Machine-translated (zh-Hans) from the English page: https://ai-game.dev/docs/wiki/unreal/cli