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

unity-mcp-cli 命令参考——安装 Unity MCP、登录、写入 AI 代理配置、无界面打开 Unity、从终端运行工具和 C#。

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

`unity-mcp-cli` 是 Unity MCP 的命令行工具。它可以安装 Unity 和插件、让你登录 ai-game.dev、写入 AI 代理配置、打开和关闭编辑器，以及从终端或 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 会自动禁用加载动画和颜色。大多数接受项目路径的命令既可以用位置参数传入路径，也可以用 `--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 作用域注册表和 `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 场景；跳过校验和验证） |
| `--enroll <code>` | 兑换团队注册码，获得绑定到该项目的插件凭据 |
| `--enroll-stdin` | 从 stdin 读取注册码，避免它出现在 shell 历史记录中 |
| `--yes` | 自动确认提示，例如 `--enroll` 过程中的账号切换 |

### install-extension

将官方扩展安装到 `Packages/manifest.json`。请参阅[扩展](https://ai-game.dev/zh-hans/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`，并保留作用域注册表。接受 `[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 代理配置 |
| `--url <url>` | 与 `--agent` 一同传递的服务端 URL |

### bootstrap-local

将项目的配置固定为 Custom（本地）模式，并指定服务端 URL 和令牌。幂等操作。

| 选项 | 说明 |
| --- | --- |
| `[path]` | Unity 项目（默认：当前文件夹） |
| `--url <url>` | 本地 MCP 服务端 URL（必填） |
| `--token <token>` | 本地 bearer 令牌（必填） |
| `--dry-run` | 仅报告将要发生的更改而不写入 |

## 登录和 AI 代理命令

### 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。参见 [连接 AI 客户端](https://ai-game.dev/zh-hans/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 中打开该项目，并根据所给选项设置插件的连接环境变量。编辑器以分离方式启动。

| 选项 | 说明 |
| --- | --- |
| `[path]` | Unity 项目（默认：当前文件夹） |
| `--unity <version>` | 编辑器版本（默认：项目所用的版本，其次是已安装的最高版本） |
| `--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` 在 Editor 中运行 C# 并打印结果。如果已有打开的 Editor 就使用它；否则启动一个无头 Editor，该 Editor 会保持热启动以供后续调用，并在 `--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` | 启动带窗口的 Editor，而非无头模式 |
| `--idle <seconds>` | 由 `exec` 启动的 Editor 退出前的空闲时间（默认 300，0 表示永不退出） |
| `--ready-timeout <ms>` | 等待 Editor 就绪（默认 300000） |
| `--timeout <ms>` | 工具调用超时 |
| `--raw` | 原始工具响应 JSON |
| `--url <url>`、`--token <token>` | 覆盖项 |

编译错误会以退出码 1 结束，并指出出错的行。

## 维护

### update

将 CLI 更新到最新的 npm 版本。`--check` 仅做检查，若有可用更新则以退出码 2 结束。在 `npx` 下无需更新。

## 作为库使用

该包还导出了一个带类型的 Node.js API（`installPlugin`、`removePlugin`、`configure`、`setupMcp`、`installExtension` 等），它返回结果对象而不是打印输出。请参阅该包的 [npm 上的 README](https://www.npmjs.com/package/unity-mcp-cli)。

## 相关页面

- [安装](https://ai-game.dev/zh-hans/docs/wiki/unity/installation) 和 [快速上手](https://ai-game.dev/zh-hans/docs/wiki/unity/getting-started)。
- [配置](https://ai-game.dev/zh-hans/docs/wiki/unity/configuration#overrides)，了解 `open` 设置的环境变量。
- 桌面应用自带的 CLI `gamedev`：[应用 CLI](https://ai-game.dev/zh-hans/docs/wiki/app/cli)。

---

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

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