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

unity-mcp-cli 是 Unity MCP 的命令行工具。它可以安装 Unity 和插件、让你登录 ai-game.dev、写入 AI 代理配置、打开和关闭编辑器，以及从终端或 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 会自动禁用加载动画和颜色。大多数接受项目路径的命令既可以用位置参数传入路径，也可以用 --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 作用域注册表和 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。请参阅扩展。

参数 / 选项	说明
`[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 代理命令

通过浏览器 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 客户端。

选项	说明
`[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 模式）。

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 秒后退出。

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。

安装和快速上手。
配置，了解 open 设置的环境变量。
桌面应用自带的 CLI gamedev：应用 CLI。

安装#

典型会话#

项目设置命令#

install-unity#

create-project#

install-plugin#

install-extension#

remove-plugin#

configure#

bootstrap-local#

登录和 AI 代理命令#

login#

setup-mcp#

setup-skills#

Editor 命令#

open#

close#

wait-for-ready#

status#

工具命令#

run-tool#

run-system-tool#

exec#

维护#

update#

作为库使用#

相关页面#

安装