unity-mcp

18 KiB

Raw Blame History

English	简体中文

由 Coplay 荣誉赞助和维护 -- Unity 最好的 AI 助手。

使用大语言模型创建您的 Unity 应用！

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

💬 加入我们的 Discord

获得帮助、分享想法，与其他 MCP for Unity 开发者协作！

主要功能 🚀

🗣️ 自然语言操控： 指示您的大语言模型执行 Unity 任务。
🛠️ 强大工具： 管理资源、场景、材质、脚本和编辑器功能。
🤖 自动化： 自动化重复的 Unity 工作流程。
🧩 可扩展： 设计为与各种 MCP 客户端协作。
🌐 HTTP 优先传输： 默认启用 HTTP 连接（stdio 仍可作为备选方案）。

工具

您的大语言模型可以使用以下功能：

execute_custom_tool: 执行由 Unity 注册的项目范围自定义工具。
execute_menu_item: 执行 Unity 编辑器菜单项（例如，"File/Save Project"）。
manage_asset: 执行资源操作（导入、创建、修改、删除等）。
manage_editor: 控制和查询编辑器的状态和设置。
manage_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 和基本元数据，而不返回文件内容。

资源

您的大语言模型可以检索以下资源：

custom_tools: 列出活动 Unity 项目可用的自定义工具。
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 中定义的所有标签。

工作原理

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

MCP for Unity Bridge： 在编辑器内运行的 Unity 包。（通过包管理器安装）。
MCP for Unity Server： 本地运行的 Python 服务器（从终端窗口运行），通过 HTTP/JSON-RPC 与您的 MCP 客户端通信。Unity 窗口默认以 HTTP 模式为您启动它；如果您切换传输方式，stdio 仍然可用。

安装 ⚙️

前置要求

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 | 其他客户端可通过手动配置使用
[可选] Roslyn 用于高级脚本验证

对于捕获未定义命名空间、类型和方法的严格验证级别：

方法 1：Unity 的 NuGet（推荐）
1. 安装 NuGetForUnity
2. 前往 Window > NuGet Package Manager
3. 搜索 Microsoft.CodeAnalysis，选择版本 4.14.0 并安装包
4. 同时安装包 SQLitePCLRaw.core 和 SQLitePCLRaw.bundle_e_sqlite3。
5. 前往 Player Settings > Scripting Define Symbols
6. 添加 USE_ROSLYN
7. 重启 Unity
方法 2：手动 DLL 安装
1. 从 NuGet 下载 Microsoft.CodeAnalysis.CSharp.dll 和依赖项
2. 将 DLL 放置在 Assets/Plugins/ 文件夹中
3. 确保 .NET 兼容性设置正确
4. 将 USE_ROSLYN 添加到脚本定义符号
5. 重启 Unity
注意： 没有 Roslyn 时，脚本验证会回退到基本结构检查。Roslyn 启用完整的 C# 编译器诊断和精确错误报告。

🌟 步骤 1：安装 Unity 包

通过 Git URL 安装

打开您的 Unity 项目。
前往 Window > Package Manager。
点击 + -> Add package from git URL...。

输入：

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

点击 Add。

通过 OpenUPM 安装

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

注意： 如果您在 Coplay 维护之前安装了 MCP 服务器，您需要在重新安装新版本之前卸载旧包。

⚡️ 步骤 2：启动本地 HTTP 服务器（默认）

HTTP 传输默认启用。Unity 窗口可以为您启动 FastMCP 服务器：

打开 Window > MCP for Unity。
确保传输下拉菜单设置为 HTTP（默认），并且 HTTP URL 是您想要的（默认为 http://localhost:8080）。
点击启动本地 HTTP 服务器。Unity 会生成一个新的操作系统终端，运行 uv ... server.py --transport http。
在您工作时保持该终端窗口打开；关闭它会停止服务器。如果您需要干净地关闭它，请使用 Unity 窗口中的停止会话按钮。

更喜欢 stdio？将传输下拉菜单更改为 Stdio，Unity 将回退到嵌入式 TCP 桥接器，而不是启动 HTTP 服务器。

手动启动（可选）

您也可以从终端自己启动服务器——对 CI 或当您想查看原始日志时很有用：

uvx --from "git+https://github.com/CoplayDev/unity-mcp@v8.0.0#subdirectory=Server" mcp-for-unity --transport http --http-url http://localhost:8080

在客户端连接时保持进程运行。

🛠️ 步骤 3：配置您的 MCP 客户端

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

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

在 Unity 中，前往 Window > MCP for Unity。
点击 Auto-Setup。
寻找绿色状态指示器 🟢 和"Connected ✓"。（这会写入指向您在步骤 2 中启动的服务器的 HTTP url）。

客户端特定故障排除

VSCode：使用 Code/User/mcp.json 和顶级 servers.unityMCP、"type": "http" 以及步骤 2 中的 URL。在 Windows 上，当您切换回 stdio 时，MCP for Unity 仍然偏好绝对 uv.exe 路径。
Cursor / Windsurf (帮助链接)：如果缺少 uv，MCP for Unity 窗口会显示"uv Not Found"和快速 [HELP] 链接以及"Choose uv Install Location"按钮。
Claude Code (帮助链接)：如果找不到 claude，窗口会显示"Claude Not Found"和 [HELP] 以及"Choose Claude Location"按钮。注销现在会立即更新 UI。

选项 B：手动配置

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

找到您的 MCP 客户端配置文件。（查看客户端文档）。
- Claude 示例（macOS）： ~/Library/Application Support/Claude/claude_desktop_config.json
- Claude 示例（Windows）： %APPDATA%\Claude\claude_desktop_config.json
编辑文件 以添加/更新 mcpServers 部分，使其指向步骤 2 中的 HTTP 端点。

点击查看客户端特定的 JSON 配置片段...

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（所有操作系统 – HTTP 默认）

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

macOS / Windows / Linux（Claude Desktop、Cursor、Claude Code、Windsurf 等 – HTTP 默认）

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

将 URL 设置为与您在 Unity 窗口中输入的内容匹配（包括 /mcp）。

Stdio 配置示例（传统 / 可选）

将 Unity 传输下拉菜单切换到 Stdio，然后使用以下 command/args 块之一。

VSCode（stdio）

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

macOS / Linux（stdio）

{
  "mcpServers": {
    "UnityMCP": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/Users/YOUR_USERNAME/Library/AppSupport/UnityMCP/UnityMcpServer/src",
        "server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

Windows（stdio）

{
  "mcpServers": {
    "UnityMCP": {
      "command": "C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uv.exe",
      "args": [
        "run",
        "--directory",
        "C:/Users/YOUR_USERNAME/AppData/Local/UnityMCP/UnityMcpServer/src",
        "server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

根据您的平台需要替换 YOUR_USERNAME 和 AppSupport 路径段。

使用方法 ▶️

打开您的 Unity 项目 并验证 HTTP 服务器正在运行（Window > MCP for Unity > Start Local HTTP Server）。一旦服务器启动，指示器应显示"Session Active"。
启动您的 MCP 客户端（Claude、Cursor 等）。它连接到步骤 3 中配置的 HTTP 端点——客户端不会生成额外的终端。
交互！ Unity 工具现在应该在您的 MCP 客户端中可用。

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

使用多个 Unity 实例

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

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

列出可用实例：要求您的大语言模型检查 unity_instances 资源
设置活动实例：使用 set_active_instance 与实例名称（例如，MyProject@abc123）
所有后续工具路由到该实例，直到更改

示例：

用户: "列出所有 Unity 实例"
大语言模型: [显示 ProjectA@abc123 和 ProjectB@def456]

用户: "将活动实例设置为 ProjectA@abc123"
大语言模型: [调用 set_active_instance("ProjectA@abc123")]

用户: "创建一个红色立方体"
大语言模型: [在 ProjectA 中创建立方体]

开发和贡献 🛠️

开发设置和指南

查看 README-DEV.md 获取完整的开发设置和工作流程文档。

添加自定义工具

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

如何贡献

Fork 主仓库。
创建问题 讨论您的想法或错误。
创建分支（feature/your-idea 或 bugfix/your-fix）。
进行更改。
提交（feat: Add cool new feature）。
推送您的分支。
对主分支开启拉取请求，引用您之前创建的问题。

📊 遥测和隐私

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

🔒 匿名：仅随机 UUID，无个人数据
🚫 轻松退出：设置 DISABLE_TELEMETRY=true 环境变量
📖 透明：查看 TELEMETRY.md 获取完整详情

您的隐私对我们很重要。所有遥测都是可选的，旨在尊重您的工作流程。

故障排除 ❓

点击查看常见问题和修复方法...

Unity Bridge 未运行/连接：
- 确保 Unity 编辑器已打开。
- 检查状态窗口：Window > MCP for Unity。
- 重启 Unity。
MCP 客户端未连接/服务器未启动：
- 确保本地 HTTP 服务器正在运行（Window > MCP for Unity > Start Local HTTP Server）。保持生成的终端窗口打开。
- 验证服务器路径： 双重检查您的 MCP 客户端 JSON 配置中的 --directory 路径。它必须完全匹配安装位置：
  - Windows： %USERPROFILE%\AppData\Local\UnityMCP\UnityMcpServer\src
  - macOS： ~/Library/AppSupport/UnityMCP/UnityMcpServer\src
  - Linux： ~/.local/share/UnityMCP/UnityMcpServer\src
- 验证 uv： 确保 uv 已安装并正常工作（uv --version）。
- 手动运行： 尝试直接从终端运行服务器以查看错误：
```
cd /path/to/your/UnityMCP/UnityMcpServer/src
uv run server.py
```
配置失败：
- 使用手动配置步骤。插件可能缺乏写入 MCP 客户端配置文件的权限。

仍然卡住？开启问题或加入 Discord！

许可证 📜

MIT 许可证。查看 LICENSE 文件。

Star 历史

Unity AI 工具由 Coplay 提供

Coplay 提供 2 个 Unity AI 工具

MCP for Unity 在 MIT 许可证下免费提供。
Coplay 是一个高级 Unity AI 助手，位于 Unity 内部，功能比 MCP for Unity 更多。

（这些工具有不同的技术栈。查看这篇博客文章比较 Coplay 和 MCP for Unity。）

免责声明

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

18 KiB Raw Blame History Unescape Escape