# 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-hant/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 runner 建立僅含工具的認證（應用程式無法使用） |
| `-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

為單一 agent 寫入一筆 MCP 設定。agent 清單請見[連接 AI 用戶端](https://ai-game.dev/zh-hant/docs/wiki/unreal/connecting-ai-clients#setup-mcp)。

| 旗標 | 說明 |
| --- | --- |
| `-p, --path <dir>` | 專案資料夾 |
| `--transport <t>` | `http`(預設)或 `stdio`(會下載本機伺服器) |
| `--url <url>` | 明確指定的伺服器 URL |
| `--token <token>` | 明確指定的 bearer token;優先於專案金鑰 |
| `--oauth` | Cloud:僅含 URL 的設定,由 agent 自行登入 |
| `--regenerate-key` | Cloud:建立新的專案金鑰並撤銷舊金鑰 |
| `--no-pin` | 使用單純的 `/mcp` URL,而非釘選到專案的 `/mcp/p/<pin>` |
| `--dry-run` | 只印出設定片段,不實際寫入 |
| `--list` | 列出支援的 agent 與設定檔路徑 |

### 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 ms;`--interval`,預設 2000 ms)。兩者都接受 `-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-hant/docs/wiki/app) 使用。

---

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

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