# Unity MCP

Canonical: https://cqbase.net/zh/entry/unity-mcp
Chinese: https://cqbase.net/zh/entry/unity-mcp
English: https://cqbase.net/en/entry/unity-mcp

> 在 AI 助手和 Unity 编辑器之间搭桥，让模型能够管理资源和操作场景。

CoplayDev/unity-mcp 用 MIT 许可，在 AI 助手和 Unity 编辑器之间提供 MCP 桥梁，让模型可以管理资源、控制场景。它操作的是正在运行的编辑器，而不只是仓库里的文本文件。

先在一个可以丢弃的工程里试用，并保存场景副本。代理一旦能改场景和资源，就可能破坏项目结构。不要对未备份的发行分支直接打开写入。

推荐来源：

- [@HermesWatcher](https://x.com/HermesWatcher/status/2115081092118032871) 在 2026 年 10 月 27 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：1149 次喜欢，126 次转发）。
- [@skizzyy2](https://x.com/skizzyy2/status/2120856666451083515) 在 2026 年 11 月 12 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：20 次喜欢，0 次转发）。

## 解决什么问题

Unity MCP（仓库 `CoplayDev/unity-mcp`，文档里也称 MCP for Unity）在 MCP 客户端和正在运行的 Unity 编辑器之间搭桥。代理因此可以管理资源、操作场景、编辑脚本、跑测试，而不只是改仓库里的文本文件。

官方文档把它分成三层：MCP 客户端、中间的 Python 服务器，以及编辑器里的 C# 插件。客户端并不直接跟 Unity 进程对话。工具数量在官方材料里并不完全一致：仓库 README 写「48 focused MCP tool entrypoints」，文档站首页写「50 tools」。本文不擅自统一。

## 适合谁

适合已经在用 Unity 2021.3 LTS 到 6.x，并希望用 Claude Desktop、Claude Code、Cursor、VS Code 等 MCP 客户端操作编辑器的人。它使用 MIT 许可，官方说明这是免费开源工具，与 Unity Technologies 没有隶属关系。

它会改正在运行的编辑器里的场景和资源。请先在一个可以丢弃的工程里试用，并保存场景副本。不要对未备份的发行分支直接打开写入。

## 怎么装

核验日期为 2026-11-15（Asia/Shanghai）。步骤来自仓库 [README](https://github.com/CoplayDev/unity-mcp) 和官方 [Install](https://coplaydev.github.io/unity-mcp/getting-started/install) 页。

前置要求是 Unity 2021.3 LTS 或更新版本、Python 3.10 或更新版本，以及 `uv`。安装向导在缺少后两项时会引导你安装。

在 Unity 中打开 Window → Package Manager，点 `+`，选择 Add package from git URL...，粘贴：

```text
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
```

这条路径需要系统 `PATH` 里有 `git`。也可以用 OpenUPM：

```bash
openupm add com.coplaydev.unity-mcp
```

官方还提供 Unity Asset Store 安装路径。导入后会出现安装向导：确认 Python 和 `uv` 已就绪，再选择要配置的 MCP 客户端，点击 Configure Selected。之后可随时通过 Window → MCP for Unity 启动或停止服务器、切换 HTTP 与 stdio，并查看状态是否为 Connected。

**Claude Desktop**

官方写明 Claude Desktop 只支持 stdio。即使你在别处选择了 HTTP，MCP for Unity 也会为它静默写成 stdio。自动配置之后，一般会在下次启动时连接。若需手动配置，官方给出的 macOS / Linux 示例如下：

```json
{
  "mcpServers": {
    "unityMCP": {
      "command": "uvx",
      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
    }
  }
}
```

Windows 上，官方示例把 `command` 写成 `uvx` 的完整路径，例如 `C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe`，参数相同。

**Cursor**

向导可以自动写入配置，但官方强调：自动配置之后，仍要在 Cursor 自己的 Settings → MCP 里打开 `unityMCP` 开关。HTTP 是这类 IDE 客户端的默认传输，手动配置时可写：

```json
{
  "mcpServers": {
    "unityMCP": {
      "url": "http://localhost:8080/mcp"
    }
  }
}
```

**Claude Code 与 VS Code**

官方写明，配置完成后 Claude Code、VS Code、Windsurf、Cline 和若干 CLI 客户端会自动连接。HTTP 默认地址是 `http://localhost:8080/mcp`。VS Code 的手动配置写在 `servers` 下，而不是 `mcpServers`，并需声明 `"type": "http"`。

## 一个实际例子

下面的提示词来自官方 Install 页的 First prompt，用作核验，而不是保证可复现的结果。本次没有在 Unity 里实跑，因此不编造场景里出现了哪些对象。

1. 在一个可丢弃的工程中完成安装，确认 Window → MCP for Unity 显示 Connected，且客户端已启用 `unityMCP`。
2. 先保存当前场景副本，再发送：`Create a red, a blue, and a yellow cube in the current scene.`
3. 回到编辑器，检查是否出现三个立方体、颜色是否符合请求，以及场景是否被意外改动。若结果不对，先用你保存的副本恢复，再排障。

## 常见坑

- 用 Git URL 安装时提示无法执行 git。官方要求 `git` 在 Package Manager 能找到的 `PATH` 里。安装文档把这类错误指向排障说明。
- 状态面板显示找不到 `uv`，或服务器没有启动。请在终端确认 `uv --version`。macOS 上从 Finder 启动的 Unity 往往继承不到 shell 的 `PATH`，官方建议在 MCP 窗口里手动指定 `uv` 的位置，见 [Install or Repair uv + Python](https://coplaydev.github.io/unity-mcp/guides/uv-setup)。
- Cursor 里看起来已经配置好，但工具不可用。官方写明 Cursor 在自动配置之后仍需打开自己的 MCP 开关。
- 切换 HTTP 与 stdio 之后，客户端提示找不到 Unity 实例。官方 uv 排障页建议重启客户端，让它重新读取配置。
- 在 Windows 上，安装向导报告找不到 Python，但终端里 `python --version` 正常。[issue #1324](https://github.com/CoplayDev/unity-mcp/issues/1324) 记录过 Microsoft Store 的执行别名抢在真实解释器前面的情况（该 issue 已于 2026-10-02 关闭；若你仍遇到，对照当前版本和那次讨论）。

## FAQ

### 需要 Unity 或 MCP 的付费账号吗？

MCP for Unity 本身以 MIT 许可免费提供。你需要符合文档要求的 Unity 版本、Python、`uv`，以及一个 MCP 客户端。客户端（例如 Claude Code）可能另有自己的账号要求。同一批维护者还提供付费的 Aura 助手，那是另一个产品，不要和这个开源桥接器混为一谈。

### Claude Desktop 可以用 HTTP 吗？

官方说不可以。Claude Desktop 只支持 stdio，插件会为它按 stdio 配置，即使你在 MCP for Unity 窗口里选择了 HTTP。

### 默认的 HTTP 地址是什么？

官方 Install 页把默认地址写成 `http://localhost:8080/mcp`。若客户端连不上，先在 Window → MCP for Unity 确认服务器已启动，并检查配置里的 URL 是否一致。

### 可以同时开多个 Unity 编辑器吗？

官方提供多实例路由说明，见 [Multi-Instance Routing](https://coplaydev.github.io/unity-mcp/guides/multi-instance)。本文没有实跑多实例，具体切换方式以那份指南为准。

### 自动配置失败怎么办？

按 Install 页的「Manual MCP client configuration」把 HTTP 或 stdio 片段写进客户端配置。Claude Desktop 用 stdio；Cursor、VS Code 等默认用 HTTP。Windows 的 stdio 示例需要 `uvx` 的完整路径。

## 来源与许可

仓库 [CoplayDev/unity-mcp](https://github.com/CoplayDev/unity-mcp) 使用 MIT 许可。本文依据 2026-11-15 查阅的 README、[Install](https://coplaydev.github.io/unity-mcp/getting-started/install)、[Choosing an MCP Client](https://coplaydev.github.io/unity-mcp/getting-started/clients) 和 [uv 排障](https://coplaydev.github.io/unity-mcp/guides/uv-setup)，用自己的话写成，供 CQBase 上下文库使用。若安装 URL、传输方式或客户端开关有变，以这些官方材料为准。

## 收录信息

- 作者: CoplayDev
- 许可证: MIT
- 来源: https://github.com/CoplayDev/unity-mcp
- 收录: 2026-11-15
- GitHub 星标: 15978（采集 2026-11-15）

