快速开始

June 8, 2026 · View on GitHub

Unity MCP — CLI

npm Node.js License Stand With Ukraine

AI Game Developer

Claude   Codex   Cursor   GitHub Copilot   Gemini   Antigravity   VS Code   Rider   Visual Studio   Open Code   Cline   Kilo Code

中文 | 日本語 | Español

跨平台 CLI 工具，适用于 Unity MCP — 创建项目、安装插件、配置 MCP 工具，以及启动带有活跃 MCP 连接的 Unity。所有操作只需一行命令。

AI Game Developer — Unity SKILLS and MCP

  • :white_check_mark: 创建项目 — 通过 Unity 编辑器搭建新的 Unity 项目
  • :white_check_mark: 安装编辑器 — 从命令行安装任意版本的 Unity 编辑器
  • :white_check_mark: 安装插件 — 将 Unity-MCP 插件连同所有必需的作用域注册表添加到 manifest.json
  • :white_check_mark: 移除插件 — 从 manifest.json 中移除 Unity-MCP 插件
  • :white_check_mark: 配置 — 启用/禁用 MCP 工具、提示和资源
  • :white_check_mark: 状态检查 — 一目了然查看 Unity 进程、本地服务器和云服务器的连接状态
  • :white_check_mark: 运行工具 — 直接从命令行执行 MCP 工具
  • :white_check_mark: 设置 MCP — 为 14 个受支持的 AI 代理中的任何一个编写 MCP 配置文件
  • :white_check_mark: 设置技能 — 通过 MCP 服务器为 AI 代理生成技能文件
  • :white_check_mark: 等待就绪 — 轮询直到 Unity 编辑器和 MCP 服务器已连接并可接受工具调用
  • :white_check_mark: 打开并连接 — 启动 Unity，可选设置 MCP 环境变量以实现自动服务器连接
  • :white_check_mark: 跨平台 — 支持 Windows、macOS 和 Linux
  • :white_check_mark: CI 友好 — 自动检测非交互式终端并禁用加载动画/颜色
  • :white_check_mark: 详细模式 — 在任何命令中使用 --verbose 获取详细的诊断输出
  • :white_check_mark: 版本感知 — 绝不降级插件版本，从 OpenUPM 解析最新版本

AI Game Developer — Unity SKILLS and MCP

快速开始

全局安装并运行：

# 1.1 Install unity-mcp-cli                                #  ┌────────────────────┐
npm install -g unity-mcp-cli                               #  │ Available AI agent │
                                                           #  ├────────────────────┤
# 1.2 (Optional) Install Unity                             #  │ antigravity        │
unity-mcp-cli install-unity                                #  │ claude-code        │
                                                           #  │ claude-desktop     │
# 1.3 (Optional) Create Unity project                      #  │ cline              │
unity-mcp-cli create-project ./MyUnityProject              #  │ codex              │
                                                           #  │ cursor             │
# 2. Install "AI Game Developer" in Unity project          #  │ gemini             │
unity-mcp-cli install-plugin ./MyUnityProject              #  │ github-copilot-cli │
                                                           #  │ kilo-code          │
# 3. Login to cloud server                                 #  │ open-code          │
unity-mcp-cli login ./MyUnityProject                       #  │ rider-junie        │
                                                           #  │ unity-ai           │
# 4. Open Unity project (auto-connects and generates skills)  │ vs-copilot         │
unity-mcp-cli open ./MyUnityProject                        #  │ vscode-copilot     │
                                                           #  └────────────────────┘
# 5. Wait for Unity Editor to be ready
unity-mcp-cli wait-for-ready ./MyUnityProject

或使用 npx 即时运行任何命令 — 无需全局安装：

npx unity-mcp-cli install-plugin /path/to/unity/project

系统要求： Node.js ^20.19.0 || >=22.12.0。如果未找到 Unity Hub，将自动安装。

AI Game Developer — Unity SKILLS and MCP

目录

AI Game Developer — Unity SKILLS and MCP

命令

configure

在 UserSettings/AI-Game-Developer-Config.json 中配置 MCP 工具、提示和资源。

unity-mcp-cli configure ./MyGame --list
选项必需描述
[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否禁用所有资源

示例 — 启用指定工具并禁用所有提示：

unity-mcp-cli configure ./MyGame \
  --enable-tools gameobject-create,gameobject-find \
  --disable-all-prompts

示例 — 启用全部：

unity-mcp-cli configure ./MyGame \
  --enable-all-tools \
  --enable-all-prompts \
  --enable-all-resources

AI Game Developer — Unity SKILLS and MCP

create-project

使用 Unity 编辑器创建新的 Unity 项目。

unity-mcp-cli create-project /path/to/new/project
选项必需描述
[path]是项目创建路径（位置参数或 --path）
--unity <version>否使用的 Unity 编辑器版本（默认为已安装的最高版本）

示例 — 使用指定编辑器版本创建项目：

unity-mcp-cli create-project ./MyGame --unity 2022.3.62f1

AI Game Developer — Unity SKILLS and MCP

install-plugin

将 Unity-MCP 插件安装到 Unity 项目的 Packages/manifest.json 中。

unity-mcp-cli install-plugin ./MyGame
选项必需描述
[path]是Unity 项目路径（位置参数或 --path）
--plugin-version <version>否要安装的插件版本（默认为 OpenUPM 上的最新版本）

该命令将：

  1. 添加 OpenUPM 作用域注册表及所有必需的作用域
  2. 将 com.ivanmurzak.unity.mcp 添加到 dependencies
  3. 绝不降级 — 如果已安装更高版本，将保留现有版本

示例 — 安装指定的插件版本：

unity-mcp-cli install-plugin ./MyGame --plugin-version 0.51.6

运行此命令后，请在 Unity 编辑器中打开项目以完成包安装。

AI Game Developer — Unity SKILLS and MCP

install-unity

通过 Unity Hub CLI 安装 Unity 编辑器版本。

unity-mcp-cli install-unity 6000.3.1f1
参数 / 选项必需描述
[version]否要安装的 Unity 编辑器版本（例如 6000.3.1f1）
--path <path>否从现有项目中读取所需版本

如果既未提供参数也未提供选项，该命令将从 Unity Hub 的发行列表中安装最新的稳定版本。

示例 — 安装项目所需的编辑器版本：

unity-mcp-cli install-unity --path ./MyGame

AI Game Developer — Unity SKILLS and MCP

open

在 Unity 编辑器中打开 Unity 项目。默认情况下，如果提供了连接选项，将设置 MCP 连接环境变量。使用 --no-connect 可在不建立 MCP 连接的情况下打开。

unity-mcp-cli open ./MyGame
选项环境变量必需描述
[path]—是Unity 项目路径（位置参数或 --path）
--unity <version>—否使用指定的 Unity 编辑器版本（默认为项目设置中的版本，回退到已安装的最高版本）
--no-connect—否不设置 MCP 连接环境变量直接打开
--url <url>UNITY_MCP_HOST否要连接的 MCP 服务器 URL
--keep-connectedUNITY_MCP_KEEP_CONNECTED否强制保持连接活跃
--token <token>UNITY_MCP_TOKEN否认证令牌
--auth <option>UNITY_MCP_AUTH_OPTION否认证模式：none 或 required
--tools <names>UNITY_MCP_TOOLS否要启用的工具列表（逗号分隔）
--transport <method>UNITY_MCP_TRANSPORT否传输方式：streamableHttp 或 stdio
--start-server <value>UNITY_MCP_START_SERVER否设置为 true 或 false 以控制 MCP 服务器自动启动

编辑器进程以分离模式启动 — CLI 将立即返回。

示例 — 使用 MCP 连接打开：

unity-mcp-cli open ./MyGame \
  --url http://localhost:8080 \
  --keep-connected

示例 — 不使用 MCP 连接打开（简单打开）：

unity-mcp-cli open ./MyGame --no-connect

示例 — 使用认证和指定工具打开：

unity-mcp-cli open ./MyGame \
  --url http://my-server:8080 \
  --token my-secret-token \
  --auth required \
  --tools gameobject-create,gameobject-find

AI Game Developer — Unity SKILLS and MCP

run-tool

通过 HTTP API 直接执行 MCP 工具。服务器 URL 和授权令牌会根据当前连接模式（自定义或云端）从项目的配置文件（UserSettings/AI-Game-Developer-Config.json）中自动解析。

unity-mcp-cli run-tool gameobject-create ./MyGame --input '{"name":"Cube"}'
选项必需描述
<tool-name>是要执行的 MCP 工具名称
[path]否Unity 项目路径（位置参数或 --path）— 用于读取配置和检测端口
--url <url>否直接覆盖服务器 URL（绕过配置）
--token <token>否覆盖 Bearer 令牌（绕过配置）
--input <json>否工具参数的 JSON 字符串（默认为 {}）
--input-file <file>否从文件读取 JSON 参数
--raw否输出原始 JSON（无格式化、无加载动画）
--timeout <ms>否请求超时时间（毫秒）（默认：60000）

URL 解析优先级：

  1. --url → 直接使用
  2. 配置文件 → host（自定义模式）或硬编码的云端端点（云端模式）
  3. 根据项目路径生成的确定性端口

授权信息会自动从项目配置中读取（自定义模式下为 token，云端模式下为 cloudToken）。使用 --token 可显式覆盖从配置中获取的令牌。

示例 — 调用工具（URL 和认证来自配置）：

unity-mcp-cli run-tool gameobject-find ./MyGame --input '{"query":"Player"}'

示例 — 显式覆盖 URL：

unity-mcp-cli run-tool scene-save --url http://localhost:8080

示例 — 管道输出原始 JSON：

unity-mcp-cli run-tool assets-list ./MyGame --raw | jq '.results'

AI Game Developer — Unity SKILLS and MCP

wait-for-ready

等待 Unity 编辑器和 MCP 服务器连接就绪并可接受工具调用。以可配置的间隔轮询服务器，直到成功响应或达到超时时间。适用于自动化脚本和 AI 代理编排场景，其中 open 启动 Unity 后代理需要知道何时可以开始调用工具。

unity-mcp-cli wait-for-ready ./MyGame
选项必需描述
[path]否Unity 项目路径（位置参数或 --path）— 用于读取配置和检测端口
--url <url>否直接覆盖服务器 URL（绕过配置）
--token <token>否覆盖 Bearer 令牌（绕过配置）
--timeout <ms>否最大等待时间（毫秒）（默认：120000）
--interval <ms>否轮询间隔（毫秒）（默认：3000）

示例 — 使用默认超时（120秒）等待：

unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'

示例 — CI 环境使用更短的超时：

unity-mcp-cli wait-for-ready ./MyGame --timeout 60000 --interval 2000

示例 — 显式指定服务器 URL：

unity-mcp-cli wait-for-ready --url http://localhost:8080 --timeout 30000

AI Game Developer — Unity SKILLS and MCP

setup-mcp

为 AI 代理编写 MCP 配置文件，支持无界面/CI 环境设置，无需 Unity 编辑器 UI。支持全部 14 个代理（Claude Code、Cursor、Gemini、Codex 等）。

unity-mcp-cli setup-mcp claude-code ./MyGame
选项必需描述
[agent-id]是要配置的代理（使用 --list 查看全部）
[path]否Unity 项目路径（默认为当前目录）
--transport <transport>否传输方式：stdio 或 http（默认：http）
--url <url>否覆盖服务器 URL（用于 http 传输）
--token <token>否覆盖认证令牌
--list否列出所有可用的代理 ID

示例 — 列出所有支持的代理：

unity-mcp-cli setup-mcp --list

示例 — 使用 stdio 传输配置 Cursor：

unity-mcp-cli setup-mcp cursor ./MyGame --transport stdio

AI Game Developer — Unity SKILLS and MCP

setup-skills

通过调用 MCP 服务器的系统工具 API 为 AI 代理生成技能文件。需要 Unity 编辑器正在运行且已安装 MCP 插件。

unity-mcp-cli setup-skills claude-code ./MyGame
选项必需描述
[agent-id]是要生成技能的代理（使用 --list 查看全部）
[path]否Unity 项目路径（默认为当前目录）
--url <url>否覆盖服务器 URL
--token <token>否覆盖认证令牌
--list否列出所有代理及其技能支持状态
--timeout <ms>否请求超时时间（毫秒）（默认：60000）

示例 — 列出支持技能的代理：

unity-mcp-cli setup-skills --list

AI Game Developer — Unity SKILLS and MCP

remove-plugin

从 Unity 项目的 Packages/manifest.json 中移除 Unity-MCP 插件。

unity-mcp-cli remove-plugin ./MyGame
选项必需描述
[path]是Unity 项目路径（位置参数或 --path）

该命令将：

  1. 从 dependencies 中移除 com.ivanmurzak.unity.mcp
  2. 保留作用域注册表和作用域 — 其他包可能依赖它们
  3. 如果插件未安装则不执行任何操作

运行此命令后，请在 Unity 编辑器中打开项目以应用更改。

AI Game Developer — Unity SKILLS and MCP

status

检查 Unity 编辑器和 MCP 服务器的连接状态。显示 Unity 是否正在运行、本地 MCP 服务器是否可达、以及配置的服务器（例如云端）是否可达。

unity-mcp-cli status ./MyGame
选项必需描述
[path]否Unity 项目路径（位置参数或 --path）
--url <url>否直接覆盖服务器 URL（绕过配置）
--token <token>否覆盖 Bearer 令牌（绕过配置）
--timeout <ms>否探测超时时间（毫秒）（默认：5000）

AI Game Developer — Unity SKILLS and MCP

全局选项

以下选项适用于所有命令：

选项描述
-v, --verbose启用详细的诊断输出以进行故障排查
--version显示 CLI 版本
--help显示命令帮助信息

示例 — 以详细模式运行任何命令：

unity-mcp-cli install-plugin ./MyGame --verbose

AI Game Developer — Unity SKILLS and MCP

完整自动化示例

使用一个脚本从零开始搭建完整的 Unity MCP 项目：

# 1. Create a new Unity project
unity-mcp-cli create-project ./MyAIGame --unity 6000.3.1f1

# 2. Install the Unity-MCP plugin
unity-mcp-cli install-plugin ./MyAIGame

# 3. Enable all MCP tools
unity-mcp-cli configure ./MyAIGame --enable-all-tools

# 4. Login to cloud server (authenticates and saves token)
unity-mcp-cli login ./MyAIGame

# 5. Open the project (auto-connects and generates skills for claude-code)
unity-mcp-cli open ./MyAIGame

# 6. Wait for Unity Editor and MCP server to be ready
unity-mcp-cli wait-for-ready ./MyAIGame

# 7. Run tests to verify everything works
unity-mcp-cli run-tool tests-run ./MyAIGame --input '{"testMode":"EditMode"}'

AI Game Developer — Unity SKILLS and MCP

工作原理

确定性端口

CLI 根据 Unity 项目的目录路径生成确定性端口（SHA256 哈希映射到端口范围 20000-29999）。这与 Unity 插件中的端口生成方式一致，确保服务器和插件自动使用相同的端口，无需手动配置。

插件安装

install-plugin 命令直接修改 Packages/manifest.json：

  • 添加 OpenUPM 作用域注册表（package.openupm.com）
  • 注册所有必需的作用域（com.ivanmurzak、extensions.unity）
  • 添加 com.ivanmurzak.unity.mcp 依赖项，支持版本感知更新（绝不降级）

配置文件

configure 命令读写 UserSettings/AI-Game-Developer-Config.json，该文件控制：

  • 工具 — 可供 AI 代理使用的 MCP 工具
  • 提示 — 注入 LLM 对话中的预定义提示
  • 资源 — 向 AI 代理公开的只读数据
  • 连接设置 — 主机 URL、认证令牌、传输方式、超时时间

Unity Hub 集成

管理编辑器或创建项目的命令使用 Unity Hub CLI（--headless 模式）。如果未安装 Unity Hub，CLI 将自动下载并安装：

  • Windows — 通过 UnityHubSetup.exe /S 静默安装（可能需要管理员权限）
  • macOS — 下载 DMG，挂载后将 Unity Hub.app 复制到 /Applications
  • Linux — 将 UnityHub.AppImage 下载到 ~/Applications/

如需完整的 Unity-MCP 项目文档，请参阅主 README。

AI Game Developer — Unity SKILLS and MCP