Skip to content

Latest commit

 

History

History
265 lines (198 loc) · 11.7 KB

README-zh.md

File metadata and controls

265 lines (198 loc) · 11.7 KB

MCP for Unity

English 简体中文

由 Coplay 荣誉赞助并维护 —— Unity 最好的 AI 助手。

Discord Unity Asset Store python

用大语言模型创建你的 Unity 应用！ MCP for Unity 通过 Model Context Protocol 将 AI 助手（Claude、Cursor、VS Code 等）与你的 Unity Editor 连接起来。为你的大语言模型提供管理资源、控制场景、编辑脚本和自动化任务的工具。

MCP for Unity building a scene

最近更新
  • v9.5.4 (beta) — 新增 manage_packages 工具：安装、移除、搜索和管理 Unity 包及作用域注册表。包含输入验证、移除时依赖检查和 git URL 警告。
  • v9.5.3 — 新增 manage_graphics 工具（33个操作）：体积/后处理、光照烘焙、渲染统计、管线设置、URP渲染器特性。3个新资源：volumes、rendering_stats、renderer_features。
  • v9.5.2 — 新增 manage_camera 工具，支持 Cinemachine（预设、优先级、噪声、混合、扩展）、cameras 资源、通过 SerializedProperty 修复优先级持久化问题。
  • v9.4.8 — 新编辑器 UI、通过 manage_tools 实时切换工具、技能同步窗口、多视图截图、一键 Roslyn 安装器、支持 Qwen Code 与 Gemini CLI 客户端、通过 manage_probuilder 进行 ProBuilder 网格编辑。
更早的版本
  • v9.4.7 — 支持按调用路由 Unity 实例、修复 macOS pyenv PATH 问题、脚本工具的域重载稳定性提升。
  • v9.4.6 — 新增 manage_animation 工具、支持 Cline 客户端、失效连接检测、工具状态跨重载持久化。
  • v9.4.4 — 可配置 batch_execute 限制、按会话状态过滤工具、修复 IPv6/IPv4 回环问题。

快速开始

前置要求

1. 安装 Unity 包

在 Unity 中：Window > Package Manager > + > Add package from git URL...

Tip

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

想要最新的 beta 版本？ 使用 beta 分支：

https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#beta
其他安装方式（Asset Store、OpenUPM）

Unity Asset Store：

  1. 访问 Asset Store 上的 MCP for Unity
  2. 点击 Add to My Assets，然后通过 Window > Package Manager 导入

OpenUPM：

openupm add com.coplaydev.unity-mcp

2. 启动服务器并连接

  1. 在 Unity 中：Window > MCP for Unity
  2. 点击 Start Server（会在 localhost:8080 启动 HTTP 服务器）
  3. 从下拉菜单选择你的 MCP Client，然后点击 Configure
  4. 查找 🟢 "Connected ✓"
  5. 连接你的客户端： 一些客户端（Cursor、Windsurf、Antigravity）需要在设置里启用 MCP 开关；另一些（Claude Desktop、Claude Code）在配置后会自动连接。

就这些！ 试试这样的提示词："Create a red, blue and yellow cube" 或 "Build a simple player controller"

功能与工具

关键功能

  • 自然语言控制 — 指示你的大语言模型执行 Unity 任务
  • 强大工具 — 管理资源、场景、材质、脚本和编辑器功能
  • 自动化 — 自动化重复的 Unity 工作流程
  • 可扩展 — 可与多种 MCP Client 配合使用

可用工具

apply_text_edits • batch_execute • create_script • debug_request_context • delete_script • execute_custom_tool • execute_menu_item • find_gameobjects • find_in_file • get_sha • get_test_job • manage_animation • manage_asset • manage_camera • manage_components • manage_editor • manage_gameobject • manage_graphics • manage_material • manage_packages • manage_prefabs • manage_probuilder • manage_scene • manage_script • manage_script_capabilities • manage_scriptable_object • manage_shader • manage_texture • manage_tools • manage_ui • manage_vfx •read_console • refresh_unity • run_tests • script_apply_edits • set_active_instance • validate_script

可用资源

cameras • custom_tools • renderer_features • rendering_stats • volumes • editor_active_tool • editor_prefab_stage • editor_selection • editor_state • editor_windows • gameobject • gameobject_api • gameobject_component • gameobject_components • get_tests • get_tests_for_mode • menu_items • prefab_api • prefab_hierarchy • prefab_info • project_info • project_layers • project_tags • tool_groups • unity_instances

性能提示： 多个操作请使用 batch_execute — 比逐个调用快 10-100 倍！

手动配置

如果自动设置不生效，请把下面内容添加到你的 MCP Client 配置文件中：

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 Editor 实例。要将操作定向到某个特定实例：

  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
  • Server 无法启动： 确认 uv --version 可用，并检查终端错误
  • Client 无法连接： 确认 HTTP server 正在运行，并且 URL 与你的配置一致

详细的设置指南：

还是卡住？开一个 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 历史

Star History Chart

研究引用 如果你正在进行与 Unity-MCP 相关的研究，请引用我们！ 
@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}
}

Coplay 的 Unity AI 工具

Coplay 提供 3 个 Unity AI 工具：

  • MCP for Unity 在 MIT 许可证下免费提供。
  • Coplay 是一个运行在 Unity 内的高级 Unity AI 助手，功能超过 MCP for Unity。
  • Coplay MCP 是 Coplay 工具的“目前免费”版 MCP。

（这些工具有不同的技术栈。参见这篇博客文章：comparing Coplay to MCP for Unity。）

Coplay

免责声明

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