CLI 參考
完整的 unreal-mcp-cli 命令參考：安裝 Unreal MCP 外掛、登入、設定 AI 代理程式、開啟編輯器、執行工具與 Python。
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.7install-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 --buildbootstrap-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 用戶端。
| 旗標 | 說明 |
|---|---|
-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。它會重複使用執行中的編輯器,或啟動一個離屏渲染的無頭編輯器(因此螢幕擷取仍可運作),並在一段時間沒有工具呼叫後結束。
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 伺服器呼叫單一工具:
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 應用程式 使用。