cqbase.net · 中英双语

CQBase 上下文库

Context & Query Base

MCP

Unity MCP

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

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

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

推荐来源:

  • @HermesWatcher 在 2026 年 10 月 27 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:1149 次喜欢,126 次转发)。
  • @skizzyy2 在 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 和官方 Install 页。

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

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

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

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

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 示例如下:

{
  "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 客户端的默认传输,手动配置时可写:

{
  "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。
  • Cursor 里看起来已经配置好,但工具不可用。官方写明 Cursor 在自动配置之后仍需打开自己的 MCP 开关。
  • 切换 HTTP 与 stdio 之后,客户端提示找不到 Unity 实例。官方 uv 排障页建议重启客户端,让它重新读取配置。
  • 在 Windows 上,安装向导报告找不到 Python,但终端里 python --version 正常。issue #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。本文没有实跑多实例,具体切换方式以那份指南为准。

自动配置失败怎么办?

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

来源与许可

仓库 CoplayDev/unity-mcp 使用 MIT 许可。本文依据 2026-11-15 查阅的 README、Install、Choosing an MCP Client 和 uv 排障,用自己的话写成,供 CQBase 上下文库使用。若安装 URL、传输方式或客户端开关有变,以这些官方材料为准。

订阅 CQBase 周刊

每周一封,介绍本周新收录的公开 AI 技能、提示词、MCP 和用法。可随时退订。我们不会把邮箱交给第三方作其营销之用。