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

unity-mcp-cli 指令參考：安裝 Unity MCP、登入、寫入 AI agent 設定、以 headless 模式開啟 Unity，並從終端機執行工具與 C#。

本頁面由英文機器翻譯而成。[閱讀英文原文](https://ai-game.dev/docs/wiki/unity/cli)。

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

## 安裝

```bash
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` 指定，預設為目前資料夾。

## 典型工作流程

```bash
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`。請參閱[擴充套件](https://ai-game.dev/zh-hant/docs/wiki/unity/extensions)。

| 參數 / 選項 | 說明 |
| --- | --- |
| `[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 指令

### login

使用瀏覽器 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](https://ai-game.dev/zh-hant/docs/wiki/unity/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 模式）。

```bash
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` 秒後結束。

```bash
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](https://www.npmjs.com/package/unity-mcp-cli)。

## 相關頁面

- [安裝](https://ai-game.dev/zh-hant/docs/wiki/unity/installation)與[快速開始](https://ai-game.dev/zh-hant/docs/wiki/unity/getting-started)。
- 關於 `open` 所設定的環境變數，請參閱[設定](https://ai-game.dev/zh-hant/docs/wiki/unity/configuration#overrides)。
- 桌面應用程式本身的 CLI，`gamedev`：[應用程式 CLI](https://ai-game.dev/zh-hant/docs/wiki/app/cli)。

---

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

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