统一-MCP

<img width="676" height="380" alt="MCP for Unity" src="docs/images/logo.png" />

English	简体中文

由 Coplay 赞助并维护 -- 最佳的 Unity AI 助手。

使用 LLM 创建您的 Unity 应用程序！

MCP for Unity 作为桥梁，允许 AI 助手（如 Claude、Cursor）通过本地 MCP（模型上下文协议）客户端 直接与您的 Unity 编辑器交互。给您的 LLM 工具来管理资源、控制场景、编辑脚本并在 Unity 中自动化任务。

<img width="406" height="704" alt="MCP for Unity 截图" src="docs/images/readme_ui.png">

---

💬 加入我们的 Discord

获取帮助，分享想法，并与其他 MCP for Unity 开发者合作！

---

关键特性 🚀

• 🗣️ 自然语言控制： 指示您的 LLM 执行 Unity 任务。
• 🛠️ 强大工具： 管理资源、场景、材质、脚本和编辑器功能。
• 🤖 自动化： 自动化重复的 Unity 工作流程。
• 🧩 可扩展性： 设计用于与各种 MCP 客户端一起工作。

<details open> <summary><strong>工具</strong></summary>

您的 LLM 可以使用以下函数：

• execute_menu_item: 执行 Unity 编辑器菜单项（例如，“文件/保存项目”）。
• manage_asset: 执行资源操作（导入、创建、修改、删除等）。
• manage_editor: 控制和查询编辑器的状态和设置。
• manage_gameobject: 管理 GameObject（创建、修改、删除、查找和组件操作）。
• manage_prefabs: 执行预制件操作（创建、修改、删除等）。
• manage_scene: 管理场景（加载、保存、创建、获取层次结构等）。
• manage_script: 兼容路由器用于旧版脚本操作（创建、读取、删除）。建议使用 apply_text_edits 或 script_apply_edits 进行编辑。
• manage_shader: 执行着色器 CRUD 操作（创建、读取、修改、删除）。
• read_console: 获取或清除控制台消息。
• run_tests: 在 Unity 编辑器中运行测试。
• set_active_instance: 将后续工具调用路由到特定的 Unity 实例（当多个实例运行时）。
• apply_text_edits: 使用预条件哈希和原子多编辑批次进行精确文本编辑。
• script_apply_edits: 结构化的 C# 方法/类编辑（插入/替换/删除），具有更安全的边界。
• validate_script: 快速验证（基本/标准）以在写入前后捕获语法/结构问题。
• create_script: 在给定的项目路径下创建一个新的 C# 脚本。
• delete_script: 通过 URI 或 Assets 相对路径删除 C# 脚本。
• get_sha: 获取 Unity C# 脚本的 SHA256 和基本元数据，而不返回文件内容。

</details> <details open> <summary><strong>资源</strong></summary>

您的 LLM 可以检索以下资源：

• unity_instances: 列出所有正在运行的 Unity 编辑器实例及其详细信息（名称、路径、端口、状态）。
• menu_items: 检索 Unity 编辑器中的所有可用菜单项。
• tests: 检索 Unity 编辑器中的所有可用测试。可以选择特定类型的测试（例如，“EditMode”，“PlayMode”）。
• editor_active_tool: 当前激活的编辑器工具（移动、旋转、缩放等）和变换句柄设置。
• editor_prefab_stage: 如果预制件处于隔离模式，则当前预制件编辑上下文。
• editor_selection: 编辑器中当前选中的对象的详细信息。
• editor_state: 当前编辑器运行状态，包括播放模式、编译状态、活动场景和选中总结。
• editor_windows: 所有当前打开的编辑器窗口及其标题、类型、位置和焦点状态。
• project_info: 静态项目信息，包括根路径、Unity 版本和平台。
• project_layers: 项目 TagManager 中定义的所有层及其索引（0-31）。
• project_tags: 项目 TagManager 中定义的所有标签。

</details>

---

工作原理

MCP for Unity 使用两个组件连接您的工具：

1. MCP for Unity 桥梁： 在编辑器内部运行的 Unity 包。（通过包管理器安装）。
2. MCP for Unity 服务器： 一个本地运行的 Python 服务器，负责在 Unity 桥梁和您的 MCP 客户端之间通信。（首次运行时自动安装或通过自动设置；手动设置作为备用方案）。

<img width="562" height="121" alt="image" src="https://gips2.baidu.com/it/u=1566275472,22042439857&fm=3081&app=3081&f=PNG?w=1123&h=243" />

---

安装 ⚙️

前提条件

• Python: 版本 3.10 或更新版本。下载 Python

• Unity Hub & 编辑器: 版本 2021.3 LTS 或更新版本。下载 Unity

• uv (Python 工具链管理器):

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  
  # Windows (PowerShell)
  winget install --id=astral-sh.uv  -e
  
  # 文档: https://docs.astral.sh/uv/getting-started/installation/
  

• 一个 MCP 客户端: : Claude Desktop | Claude Code | Cursor | Visual Studio Code Copilot | Windsurf | 其他需要手动配置

• <details> <summary><strong>[可选] Roslyn 用于高级脚本验证</strong></summary>

  对于 **严格** 验证级别，可以捕获未定义的命名空间、类型和方法：
  
  **方法 1: Unity 的 NuGet (推荐)**
  1. 安装 [NuGetForUnity](https://github.com/GlitchEnzo/NuGetForUnity)
  2. 转到 `窗口 > NuGet 包管理器`
  3. 搜索 `Microsoft.CodeAnalysis`，选择版本 4.14.0 并安装该包
  4. 同时安装 `SQLitePCLRaw.core` 和 `SQLitePCLRaw.bundle_e_sqlite3` 包。
  5. 转到 `播放器设置 > 脚本定义符号`
  6. 添加 `USE_ROSLYN`
  7. 重启 Unity
  
  **方法 2: 手动安装 DLL**
  1. 从 [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp/) 下载 Microsoft.CodeAnalysis.CSharp.dll 及其依赖项
  2. 将 DLL 放置在 `Assets/Plugins/` 文件夹中
  3. 确保 .NET 兼容性设置正确
  4. 添加 `USE_ROSLYN` 到脚本定义符号
  5. 重启 Unity
  
  **注意:** 没有 Roslyn，脚本验证会回退到基本结构检查。Roslyn 可以启用完整的 C# 编译器诊断，并提供精确的错误报告。</details>
  

---

🌟 第一步: 安装 Unity 包

通过 Git URL 安装

1. 打开您的 Unity 项目。
2. 转到 窗口 > 包管理器。
3. 点击 + -> 从 Git URL 添加包...。
4. 输入：

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

5. 点击 添加。

通过 OpenUPM 安装

1. 安装 OpenUPM CLI
2. 打开终端（PowerShell、Terminal 等），导航到您的 Unity 项目目录
3. 运行 openupm add com.coplaydev.unity-mcp

注意: 如果您在 Coplay 维护之前安装了 MCP 服务器，您需要先卸载旧的包，然后再重新安装新的包。

🛠️ 第二步: 配置您的 MCP 客户端

将您的 MCP 客户端（Claude、Cursor 等）连接到第一步设置的 Python 服务器（自动）或通过手动配置（如下）。

选项 A: 自动设置（推荐用于 Claude/Cursor/VSC Copilot）

1. 在 Unity 中，转到 窗口 > MCP for Unity。
2. 点击 自动设置。
3. 查看绿色状态指示器 🟢 和 "已连接 ✓"。（这会尝试自动修改 MCP 客户端的配置文件）。

<details><summary><strong>针对客户端的具体故障排除</strong></summary>

• VSCode: 使用 Code/User/mcp.json，顶级 servers.unityMCP 和 "type": "stdio"。在 Windows 上，MCP for Unity 写入绝对 uv.exe（优先使用 WinGet Links shim）以避免 PATH 问题。
• Cursor / Windsurf (帮助链接): 如果 uv 丢失，MCP for Unity 窗口显示 "uv 未找到" 并带有快速 [HELP] 链接和 "选择 uv 安装位置" 按钮。
• Claude Code (帮助链接): 如果找不到 claude，窗口显示 "Claude 未找到" 并带有 [HELP] 和 "选择 Claude 位置" 按钮。注销现在会立即更新 UI。</details>

选项 B: 手动配置

如果自动设置失败或您使用不同的客户端：

1. 找到您的 MCP 客户端的配置文件。（查看客户端文档）。
   • Claude 示例（macOS）: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Claude 示例（Windows）: %APPDATA%\Claude\claude_desktop_config.json
2. 编辑文件，添加/更新 mcpServers 部分，使用步骤 1 中的确切路径。

<details> <summary><strong>点击以查看针对客户端的具体 JSON 配置片段...</strong></summary>

---

Claude Code

如果您使用 Claude Code，您可以使用以下命令注册 MCP 服务器：

macOS:

claude mcp add --scope user UnityMCP -- uv --directory /Users/USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src run server.py

Windows:

claude mcp add --scope user UnityMCP -- "C:/Users/USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe" --directory "C:/Users/USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src" run server.py

VSCode（所有操作系统）

{
  "servers": {
    "unityMCP": {
      "command": "uv",
      "args": ["--directory","<ABSOLUTE_PATH_TO>/UnityMcpServer/src","run","server.py"],
      "type": "stdio"
    }
  }
}

在 Windows 上，将 command 设置为绝对 shim，例如 C:\\Users\\YOU\\AppData\\Local\\Microsoft\\WinGet\\Links\\uv.exe。

Windows:

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\UnityMCP\\UnityMcpServer\\src",
        "server.py"
      ]
    }
    // ... 其他服务器可能在这里 ...
  }
}

（记得替换 YOUR_USERNAME 并使用双反斜杠 \）

macOS:

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/YOUR_USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... 其他服务器可能在这里 ...
  }
}

（替换 YOUR_USERNAME。注意：AppSupport 是一个符号链接到 "Application Support" 以避免引用问题）

Linux:

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/YOUR_USERNAME/.local/share/UnityMCP/UnityMcpServer/src",
        "server.py"
      ]
    }
    // ... 其他服务器可能在这里 ...
  }
}

（替换 YOUR_USERNAME）

</details>

---

使用方法 ▶️

1. 打开您的 Unity 项目。 MCP for Unity 包应自动连接。通过窗口 > MCP for Unity 检查状态。

2. 启动您的 MCP 客户端（Claude、Cursor 等）。它应该使用安装步骤 2 中的配置自动启动 MCP for Unity 服务器（Python）。

3. 交互！ Unity 工具现在应在您的 MCP 客户端中可用。

   示例提示：创建一个 3D 玩家控制器，创建一个 3D 的井字游戏，创建一个酷炫的着色器并应用到一个立方体上。

处理多个 Unity 实例

MCP for Unity 支持同时处理多个 Unity 编辑器实例。每个实例在 MCP 客户端会话中是隔离的。

要将工具调用定向到特定实例：

1. 列出可用实例：要求您的 LLM 检查 unity_instances 资源
2. 设置活动实例：使用 set_active_instance 和实例名称（例如，MyProject@abc123）
3. 所有后续工具都将路由到该实例，直到更改为止

示例：

用户: "列出所有 Unity 实例"
LLM: [显示 ProjectA@abc123 和 ProjectB@def456]

用户: "设置活动实例为 ProjectA@abc123"
LLM: [调用 set_active_instance("ProjectA@abc123")]

用户: "创建一个红色立方体"
LLM: [在 ProjectA 中创建立方体]

---

开发与贡献 🛠️

开发设置和指南

参见 README-DEV.md 以获取完整的开发设置和工作流文档。

添加自定义工具

MCP for Unity 使用与 Unity 的 C# 脚本绑定的 Python MCP 服务器来实现工具。如果您想通过自己的工具扩展功能，请参阅 CUSTOM_TOOLS.md 学习如何操作。

如何贡献

1. 分叉 主仓库。
2. 创建一个问题 来讨论您的想法或错误。
3. 创建一个分支 (feature/your-idea 或 bugfix/your-fix)。
4. 进行更改。
5. 提交 (feat: 添加酷炫的新功能)。
6. 推送 您的分支。
7. 打开一个拉取请求 对抗主分支，引用您之前创建的问题。

---

📊 数据分析 & 隐私

MCP for Unity 包含 注重隐私的匿名数据分析，以帮助我们改进产品。我们收集使用分析和性能数据，但 绝不会 收集您的代码、项目名称