unity-mcp-cli 參考 — Unity · AI Game Developer Wiki

unity-mcp-cli 是 Unity MCP 的命令列工具。它會安裝 Unity 與外掛、讓你登入 ai-game.dev、寫入 AI agent 設定、開啟與關閉編輯器，並可從終端機或 CI 指令碼呼叫 MCP 工具或在編輯器中執行 C#。本頁列出 1.6.2 版的所有指令與旗標。

安裝

npm install -g unity-mcp-cli

或者不安裝，直接執行任何指令：npx unity-mcp-cli <command>。它需要 Node.js ^20.19.0 或 >=22.12.0，可在 Windows、macOS 與 Linux 上運作。管理編輯器的指令會使用 Unity Hub CLI；若缺少 Unity Hub，CLI 會自動安裝。

全域選項，所有指令皆可使用：

選項	說明
`-v, --verbose`	詳細的診斷輸出
`-V, --version`	顯示 CLI 版本
`--help`	該指令的說明

在非互動式終端機（CI）中，CLI 會自動停用 spinner 與顏色。大多數需要專案路徑的指令，都接受以位置參數或 --path 指定，預設為目前資料夾。

典型工作流程

unity-mcp-cli install-plugin ./MyGame
unity-mcp-cli login
unity-mcp-cli setup-mcp claude-code ./MyGame
unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'
unity-mcp-cli close ./MyGame

專案設定指令

install-unity

透過 Unity Hub 安裝 Unity 編輯器。不加參數時會安裝最新的穩定版本。

參數 / 選項	說明
`[version]`	編輯器版本，例如 `6000.3.1f1`
`--path <path>`	從既有專案讀取所需的版本

create-project

使用編輯器建立新的 Unity 專案：unity-mcp-cli create-project ./MyGame --unity 6000.3.1f1。

參數 / 選項	說明
`[path]`	專案建立位置（必填，或改用 `--path`）
`--unity <version>`	編輯器版本（預設：已安裝的最高版本）

install-plugin

將 OpenUPM scoped registry 與 com.ivanmurzak.unity.mcp 加入 Packages/manifest.json。絕不會降級已安裝的較高版本。該資料夾必須是 Unity 專案。

選項	說明
`[path]`	Unity 專案（預設：目前資料夾）
`--plugin-version <version>`	要安裝的版本（預設：OpenUPM 上的最新版）
`--with-server`	同時把這台機器的 `gamedev-mcp-server` 執行檔下載到 CLI 自己的資料夾
`--server-version <version>`	`--with-server` 使用的伺服器版本
`--server-source <path-or-url>`	從本機 zip 或 URL 安裝伺服器（離線或 CI 使用；會跳過 checksum 驗證）
`--enroll <code>`	兌換團隊註冊碼，取得綁定到此專案的外掛憑證
`--enroll-stdin`	從 stdin 讀取註冊碼，避免留在 shell 歷程記錄中
`--yes`	自動確認提示，例如 `--enroll` 期間的帳號切換

install-extension

將官方擴充套件安裝到 Packages/manifest.json。請參閱擴充套件。

參數 / 選項	說明
`[id]`	目錄名稱（`Tilemap`）或套件 id（`com.ivanmurzak.unity.mcp.tilemap`）
`[path]`	Unity 專案（預設：目前資料夾）
`--extension-version <version>`	要安裝的版本（預設：OpenUPM 上的最新版）
`--list`	列出可安裝的擴充套件後結束（不需要專案或網路）

remove-plugin

從 Packages/manifest.json 移除 com.ivanmurzak.unity.mcp，並保留 scoped registries。需要 [path]（必填，或改用 --path）。

configure

在 UserSettings/AI-Game-Developer-Config.json 中顯示或隱藏工具、提示與資源。隱藏的項目在以名稱呼叫時仍會執行。

選項	說明
`[path]`	Unity 專案（必填，或改用 `--path`）
`--list`	印出目前設定後結束
`--enable-tools <names>`、`--disable-tools <names>`	顯示或隱藏特定工具（以逗號分隔）
`--enable-all-tools`、`--disable-all-tools`	顯示或隱藏所有工具
`--enable-prompts <names>`、`--disable-prompts <names>`	提示的部分亦同
`--enable-all-prompts`、`--disable-all-prompts`	所有提示
`--enable-resources <names>`、`--disable-resources <names>`	資源的部分亦同
`--enable-all-resources`、`--disable-all-resources`	所有資源
`--agent <id>`	改為透過受管理伺服器的設定工具寫入 AI agent 設定
`--url <url>`	與 `--agent` 一起傳入的伺服器 URL

bootstrap-local

將專案設定固定為 Custom（本機）模式，並使用指定的伺服器 URL 與 token。可重複執行（idempotent）。

選項	說明
`[path]`	Unity 專案（預設：目前資料夾）
`--url <url>`	本機 MCP 伺服器 URL（必填）
`--token <token>`	本機 bearer token（必填）
`--dry-run`	只回報將會變更的內容，不實際寫入

登入與 AI agent 指令

使用瀏覽器 OAuth 裝置流程登入 ai-game.dev，並將憑證儲存在 ~/.ai-game-dev/credentials.json。Editor 外掛與桌面應用程式共用同一份憑證。若您已登入，則會提早結束。

選項	說明
`--project <path>`	將憑證存放於 `<path>/.ai-game-dev/`，而非整台機器的存放區
`--force`	即使已有憑證也重新登入
`--tools-only`	僅授權引擎工具，供 CI 執行器使用；不會儲存 agent 憑證
`--yes`	不需提示即確認切換帳號

setup-mcp

寫入 AI agent 的 MCP 設定，輸出與 Editor 視窗中的 Configure 相同。預設會將 URL 固定到此專案（https://ai-game.dev/mcp/p/<pin>），而 Cloud HTTP 設定在您已登入時會帶上此專案的 key。請參閱 Connecting AI clients。

選項	說明
`[agent-id]`	要設定的 agent，例如 `claude-code`、`cursor`、`codex`
`[path]`	Unity 專案（預設：目前資料夾）
`--transport <transport>`	`http`（預設）或 `stdio`
`--url <url>`	覆寫 `http` 使用的伺服器 URL
`--token <token>`	改用此 Personal Access Token 而非專案 key 寫入
`--oauth`	只寫入 URL 設定；由 agent 以自己的 OAuth 登入
`--regenerate-key`	產生新的專案 key、重寫設定並撤銷舊 key
`--no-pin`	使用未固定的 `https://ai-game.dev/mcp` 端點
`--list`	列出 agent id 及其設定路徑

setup-skills

透過執行中的 Editor 產生 agent 的技能檔案。Unity 必須開啟且外掛已連線。

選項	說明
`[agent-id]`	要為其產生技能檔案的 agent
`[path]`	Unity 專案（預設：目前資料夾）
`--url <url>`、`--token <token>`	覆寫伺服器 URL 與 token
`--timeout <ms>`	請求逾時（預設 60000）
`--list`	列出 agent 以及其是否支援技能

Editor 指令

open

在 Unity Editor 中開啟專案，並依指定選項設定外掛的連線環境變數。Editor 會以分離模式啟動。

選項	說明
`[path]`	Unity 專案（預設：目前資料夾）
`--unity <version>`	Editor 版本（預設：專案版本，其次為已安裝的最高版本）
`--editor-path <path>`	明確指定 Editor 執行檔；略過 Unity Hub 探索
`--no-connect`	開啟時不設定 MCP 連線變數
`--url <url>`	伺服器 URL（設定 `UNITY_MCP_HOST`，即 `UNITY_MCP_CLOUD_URL` 的別名）
`--keep-connected`	強制開啟連線
`--token <token>`	本機伺服器 token（設定 `UNITY_MCP_TOKEN`）
`--auth <option>`	授權模式（設定 `UNITY_MCP_AUTH_OPTION`）；此版本接受 `none` 或 `required`
`--tools <names>`	要顯示的工具，以逗號分隔（設定 `UNITY_MCP_TOOLS`）
`--transport <method>`	`streamableHttp` 或 `stdio`
`--start-server <value>`	本機伺服器是否自動啟動，`true` 或 `false`
`--headless`	以無視窗模式啟動（`-batchmode`，保留圖形）並等待 MCP 伺服器回應
`--idle-timeout <seconds>`	若經過這麼多秒都沒有工具呼叫就結束，並先儲存已變更的場景與資源
`--ready-timeout <ms>`	搭配 `--headless` 時要等待多久（預設 300000）
`--no-auto-dismiss-launch-errors`	不要自動點擊 Unity「啟動時編譯錯誤」對話框上的 Ignore
`--launch-dismiss-timeout-ms <ms>`	監看該對話框的總時間（預設 30000）
`--launch-dismiss-poll-interval-ms <ms>`	該對話框的輪詢間隔（預設 1500）

要關閉啟動錯誤對話框，在 macOS 上需為終端機開啟「輔助使用」權限，在 Linux X11 上則需要 xdotool（不支援 Wayland）。

close

以正常方式關閉專案的 Editor：unity-mcp-cli close ./MyGame --timeout 60 --force。關閉未在執行的 Editor 也會成功。

選項	說明
`[path]`	Unity 專案（預設：目前資料夾）
`--timeout <seconds>`	等待正常結束的時間（預設 30）
`--force`	若屆時仍未結束則強制終止 Editor
`--owned-only`	僅關閉由 CLI 啟動的 Editor（`exec`、`open --headless`）

wait-for-ready

輪詢直到 Editor 與 MCP 伺服器可接受工具呼叫。選項：[path]、--url、--token、--timeout <ms>（預設 120000）與 --interval <ms>（預設 3000）。

status

顯示 Unity 是否執行中、本機 MCP 伺服器是否有回應，以及設定的伺服器（例如雲端）是否可連線。選項：[path]、--url、--token、--timeout <ms>（預設 5000）。

工具指令

run-tool

透過伺服器的 HTTP API 呼叫 MCP 工具。除非另行覆寫，URL 與 token 會取自專案設定（Custom 或 Cloud 模式）。

unity-mcp-cli run-tool rql-query ./MyGame --input '{"query":"objects | where name == \"Player\" | select path name active"}'
unity-mcp-cli run-tool unity-tool-list ./MyGame --raw

選項	說明
`<tool-name>`	要呼叫的工具
`[path]`	Unity 專案，用於讀取設定與偵測連接埠
`--url <url>`、`--token <token>`	可略過設定檔的覆寫選項
`--input <json>`、`--input-file <file>`	工具引數（預設 `{}`）
`--raw`	原始 JSON 輸出
`--timeout <ms>`	請求逾時（預設 60000）

run-system-tool

選項與 run-tool 相同，用於未暴露給 MCP 客戶端的系統工具（例如技能產生與工作階段控制）。

exec

透過 script-execute 在編輯器中執行 C# 並印出結果。若有已開啟的編輯器就直接使用；否則會啟動一個無介面的編輯器，讓它保持待命以供後續呼叫，並在 --idle 秒後結束。

unity-mcp-cli exec 'GameObject.FindObjectsOfType<Camera>().Length'
echo 'Application.unityVersion' | unity-mcp-cli exec

選項	說明
`[code]`	C# 陳述式；最後一個運算式即為結果（或使用 `-f` 或 stdin）
`--path <path>`	Unity 專案（預設：目前資料夾）
`-f, --file <file>`	從檔案讀取程式碼（`-` 代表 stdin）
`--using <namespace>`	額外的命名空間，可重複指定
`--include <path>`	`.ai-game-dev/snippets` 下的輔助 `.cs` 檔案或資料夾，可重複指定
`--window`	以視窗模式啟動編輯器，而非無介面模式
`--idle <seconds>`	由 `exec` 啟動的編輯器在閒置多久後結束（預設 300，0 表示永不結束）
`--ready-timeout <ms>`	等待編輯器的時間（預設 300000）
`--timeout <ms>`	工具呼叫逾時
`--raw`	原始工具回應 JSON
`--url <url>`、`--token <token>`	覆寫

編譯錯誤會以代碼 1 結束，並指出發生錯誤的行數。

維護

update

將 CLI 更新到最新的 npm 版本。--check 只會檢查，若有可用更新則以代碼 2 結束。在 npx 下沒有東西需要更新。

程式庫用法

此套件也匯出型別化的 Node.js API（installPlugin、removePlugin、configure、setupMcp、installExtension 等），會回傳結果物件而非直接印出。請參閱套件的 README on npm。

安裝與快速開始。
關於 open 所設定的環境變數，請參閱設定。
桌面應用程式本身的 CLI，gamedev：應用程式 CLI。

安裝#

典型工作流程#

專案設定指令#

install-unity#

create-project#

install-plugin#

install-extension#

remove-plugin#

configure#

bootstrap-local#

登入與 AI agent 指令#

login#

setup-mcp#

setup-skills#

Editor 指令#

open#

close#

wait-for-ready#

status#

工具指令#

run-tool#

run-system-tool#

exec#

維護#

update#

程式庫用法#

相關頁面#

安裝