README-zh.md

English 简体中文    |    Discord Wiki

由 Aura 荣誉赞助并维护 —— 面向 Unreal 与 Unity 的 AI 助手。

别错过 Godot AI 🤖，MCP for Unity 团队推出的全新开源项目！

MCP for Unity 通过 Model Context Protocol 把 Claude、Cursor、VS Code、本地大模型等 AI 助手接入 Unity 编辑器，让它们直接帮你管理资源、搭场景、写脚本、跑测试，把开发流程里的重复活儿都包了。

---

最近更新

• v10.0.0（2026-06-30）
• v9.7.3（2026-06-15）
• v9.7.1（2026-05-24）
• v9.7.0（2026-05-22）
• v9.6.8（2026-04-27）

完整更新历史见 发布说明。

---

它能做什么

用自然语言从任意 MCP 客户端操作 Unity 编辑器：搭场景、建 GameObject、写改 C# 脚本、调材质和着色器、跑测试、看性能、出包。47 个 MCP 工具入口，任意客户端可用，免费、MIT 开源。

查看完整工具目录 →

---

快速开始

环境要求： Unity 2021.3 LTS → 6.x · Python 3.10+（用 uv 管理）。兼容任意 MCP 客户端——Claude Desktop 与 Claude Code、Cursor、VS Code、Windsurf、Cline、Gemini CLI 等等。

1. 安装 —— 在 Unity 里打开 Package Manager，从 git URL 添加： https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main  （如需固定本次发布，可用 #v10.0.0；也可以用 openupm add com.coplaydev.unity-mcp）
2. 配置客户端 —— Window → MCP for Unity → Configure All Detected Clients，一键搞定所有检测到的客户端。
3. 发个提示试试 —— "在原点放一个立方体，加个 Rigidbody。" 立方体几秒就出现在场景里了。

手动配置

如果自动配置不生效，把下面的内容加到你的 MCP 客户端配置文件里：

HTTP（默认 —— 适用于 Claude Desktop、Cursor、Windsurf）：

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

VS Code：

{
  "servers": {
    "unityMCP": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Stdio 配置（uvx）

macOS/Linux：

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

Windows：

{
  "mcpServers": {
    "unityMCP": {
      "command": "C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe",
      "args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
    }
  }
}

---

多个 Unity 实例

MCP for Unity 支持同时开多个 Unity 编辑器实例。想把操作定向到某个实例：

1. 让大模型读一下 unity_instances 资源
2. 用 set_active_instance 传入 Name@hash（比如 MyProject@abc123）
3. 之后所有工具调用都会走这个实例

Roslyn 脚本验证（进阶）

想用能查出未定义命名空间、类型和方法的 Strict 验证：

1. 装 NuGetForUnity
2. Window > NuGet Package Manager → 安装 Microsoft.CodeAnalysis v5.0
3. 再装 SQLitePCLRaw.core 和 SQLitePCLRaw.bundle_e_sqlite3 v3.0.2
4. 在 Player Settings > Scripting Define Symbols 里加上 USE_ROSLYN
5. 重启 Unity

手动安装 DLL（NuGetForUnity 用不了时）

1. 从 NuGet 下载 Microsoft.CodeAnalysis.CSharp.dll 及其依赖
2. 把 DLL 放进 Assets/Plugins/
3. 确认 .NET 兼容性设置正确
4. 在 Scripting Define Symbols 里加上 USE_ROSLYN
5. 重启 Unity

故障排除

• Unity Bridge 连不上： 看一下 Window > MCP for Unity 的状态，重启 Unity
• 服务器起不来： 确认 uv --version 能跑，并看看终端报错
• 客户端连不上： 确认 HTTP 服务在运行，且 URL 和你的配置一致

详细配置指南：

• Fix Unity MCP and Cursor, VSCode & Windsurf —— uv/Python 安装、PATH 问题
• Fix Unity MCP and Claude Code —— Claude CLI 安装
• Common Setup Problems —— macOS dyld 错误、常见问题

还是搞不定？提个 Issue 或者 来 Discord 问

参与贡献

开发环境配置见 README-DEV.md，自定义工具见 CUSTOM_TOOLS.md。

1. Fork → 开 issue → 建分支（feature/your-idea）→ 改 → 提 PR

遥测与隐私

匿名、注重隐私的遥测（不收集代码、项目名或任何个人数据），用 DISABLE_TELEMETRY=true 就能关掉。详见 TELEMETRY.md。

---

许可证： MIT —— 见 LICENSE | 需要帮助？ Discord | Issues

---

Star 历史

论文引用

如果 MCP for Unity 对你的研究有帮助，欢迎引用我们！

@inproceedings{10.1145/3757376.3771417,
author = {Wu, Shutong and Barnett, Justin P.},
title = {MCP-Unity: Protocol-Driven Framework for Interactive 3D Authoring},
year = {2025},
isbn = {9798400721366},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
url = {https://doi.org/10.1145/3757376.3771417},
doi = {10.1145/3757376.3771417},
series = {SA Technical Communications '25}
}

Aura 的 Unity AI 工具

Aura 出品两款 Unity AI 工具：

• MCP for Unity —— MIT 许可证，免费开源。
• Aura for Unity —— 面向游戏开发者的高级 Unity/Unreal AI 助手。

免责声明

本项目是一个免费开源的 Unity 编辑器工具，与 Unity Technologies 无关。