Unity Editor MCP Server

MCP Unity 编辑器（游戏引擎）

MCP Unity 是 Unity 编辑器模型上下文协议 (MCP) 的实现，允许 AI 助手与你的 Unity 项目进行交互。此软件包在 Unity 和实现 MCP 协议的 Node.js 服务器之间架起了一座桥梁，使 Claude、Windsurf 和 Cursor 等 AI 代理能够在 Unity 编辑器中执行操作。

特征

IDE 集成 - 包缓存访问

MCP Unity 通过将 Unity Library/PackedCache文件夹添加到您的工作区，提供与类似 VSCode 的 IDE（Visual Studio Code、Cursor、Windsurf）的自动集成。此功能：

• 改进 Unity 软件包的代码智能
• 为 Unity 软件包提供更好的自动完成和类型信息
• 帮助 AI 编码助手了解项目的依赖关系

MCP 服务器工具

以下工具可用于通过 MCP 操作和查询 Unity 场景和游戏对象：

• execute_menu_item ：执行 Unity 菜单项（标有 MenuItem 属性的函数）

  示例提示： “执行菜单项‘GameObject/Create Empty’创建一个新的空GameObject”

• select_gameobject ：通过路径或实例 ID 选择 Unity 层次结构中的游戏对象

  示例提示： “选择场景中的主摄像机对象”

• update_gameobject ：更新 GameObject 的核心属性（名称、标签、层、活动/静态状态），如果 GameObject 不存在则创建该 GameObject

  示例提示： “将玩家对象的标签设置为‘敌人’并使其处于非活动状态”

• update_component ：更新 GameObject 上的组件字段，如果 GameObject 不包含该组件，则将其添加到 GameObject

  示例提示： “为 Player 对象添加一个 Rigidbody 组件，并将其质量设置为 5”

• add_package ：在 Unity 包管理器中安装新包

  示例提示： “将 TextMeshPro 包添加到我的项目”

• run_tests ：使用 Unity Test Runner 运行测试

  示例提示： “运行我的项目中的所有 EditMode 测试”

• send_console_log ：向 Unity 发送控制台日志

  示例提示： “将控制台日志发送到 Unity 编辑器”

• add_asset_to_scene ：将 AssetDatabase 中的资源添加到 Unity 场景

  示例提示： “将我的项目中的 Player 预制件添加到当前场景”

MCP 服务器资源

• unity://menu-items ：检索 Unity 编辑器中所有可用菜单项的列表，以方便使用execute_menu_item工具

  提示示例： “显示与 GameObject 创建相关的所有可用菜单项”

• unity://scenes-hierarchy ：检索当前 Unity 场景层次结构中所有游戏对象的列表

  提示示例： “显示当前场景的层次结构”

• unity://gameobject/{id} ：通过场景层次结构中的实例 ID 或对象路径检索有关特定 GameObject 的详细信息，包括所有 GameObject 组件及其序列化属性和字段

  提示示例： “获取有关玩家游戏对象的详细信息”

• unity://logs ：从 Unity 控制台检索所有日志的列表

  提示示例： “显示 Unity 控制台中最近的错误消息”

• unity://packages ：从 Unity 包管理器检索有关已安装和可用包的信息

  示例提示： “列出我的 Unity 项目中当前安装的所有软件包”

• unity://assets ：检索有关 Unity Asset Database 中的资产信息

  示例提示： “查找我的项目中的所有纹理资产”

• unity://tests/{testMode} ：检索有关 Unity Test Runner 中的测试的信息

  示例提示： “列出我的 Unity 项目中所有可用的测试”

要求

• Unity 2022.3 或更高版本 -安装服务器
• Node.js 18 或更高版本 -启动服务器
• npm 9 或更高版本 - 用于调试服务器

安装

安装此 MCP Unity Server 是一个多步骤过程：

步骤 1：通过 Unity 包管理器安装 Unity MCP 服务器包

1. 打开 Unity 包管理器（窗口 > 包管理器）
2. 点击左上角的“+”按钮
3. 选择“从 git URL 添加包...”
4. 输入： https://github.com/CoderGamester/mcp-unity.git
5. 点击“添加”

第 2 步：安装 Node.js

要运行 MCP Unity 服务器，您需要在计算机上安装 Node.js 18 或更高版本：

1. 访问Node.js 下载页面
2. 下载 LTS 版本的 Windows 安装程序 (.msi)（推荐）
3. 运行安装程序并按照安装向导进行操作
4. 通过打开 PowerShell 并运行以下命令来验证安装：
   node --version
5. 访问Node.js 下载页面
6. 下载 LTS 版本的 macOS 安装程序 (.pkg)（推荐）
7. 运行安装程序并按照安装向导进行操作
8. 或者，如果您安装了 Homebrew，您可以运行：
   brew install node@18
9. 打开终端并运行以下命令来验证安装：
   node --version

步骤3：配置AI LLM客户端

1. 打开 Unity 编辑器
2. 导航至“工具”>“MCP Unity”>“服务器窗口”
3. 单击您的 AI LLM 客户端的“配置”按钮，如下图所示

4. 使用给定的弹出窗口确认配置安装

打开你的AI客户端的MCP配置文件（例如Claude Desktop中的claude_desktop_config.json）并复制以下文本：

将ABSOLUTE/PATH/TO替换为 MCP Unity 安装的绝对路径，或者直接从 Unity Editor MCP Server 窗口（工具 > MCP Unity > 服务器窗口）复制文本。

启动 Unity 编辑器 MCP 服务器

1. 打开 Unity 编辑器
2. 导航至“工具”>“MCP Unity”>“服务器窗口”
3. 点击“启动服务器”启动WebSocket服务器
4. 打开 Claude Desktop 或您的 AI 编码 IDE（例如 Cursor IDE、Windsurf IDE 等）并开始执行 Unity 工具

当AI客户端连接到WebSocket服务器时，会自动在窗口中显示绿色框

可选：设置 WebSocket 端口

默认情况下，WebSocket 服务器在端口 8090 上运行。您可以通过两种方式更改此端口：

1. 打开 Unity 编辑器
2. 导航至“工具”>“MCP Unity”>“服务器窗口”
3. 将“WebSocket 端口”值更改为所需的端口号
4. Unity 将设置系统环境变量 UNITY_PORT 为新的端口号
5. 重启 Node.js 服务器
6. 再次单击“启动服务器”将 Unity 编辑器 Web 套接字重新连接到 Node.js MCP 服务器
7. 在终端中设置 UNITY_PORT 环境变量
   • Powershell GXP6
   • 命令提示符/终端 GXP7
8. 重启 Node.js 服务器
9. 再次单击“启动服务器”将 Unity 编辑器 Web 套接字重新连接到 Node.js MCP 服务器

可选：设置超时

MCP 服务器与 WebSocket 之间的连接超时时间默认为 10 秒。您可以根据操作系统进行修改：

1. 打开 Unity 编辑器
2. 导航至“工具”>“MCP Unity”>“服务器窗口”
3. 将“请求超时（秒）”值更改为所需的超时秒数
4. Unity 将设置系统环境变量 UNITY_REQUEST_TIMEOUT 为新的超时值
5. 重启 Node.js 服务器
6. 再次单击“启动服务器”将 Unity 编辑器 Web 套接字重新连接到 Node.js MCP 服务器

对于非Windows操作系统，需要配置两个地方：

编辑器进程超时

1. 打开 Unity 编辑器
2. 导航至“工具”>“MCP Unity”>“服务器窗口”
3. 将“请求超时（秒）”值更改为所需的超时秒数

WebSocket 超时

1. 在终端中设置 UNITY_REQUEST_TIMEOUT 环境变量
   • Powershell GXP8
   • 命令提示符/终端 GXP9
2. 重启 Node.js 服务器
3. 再次单击“启动服务器”将 Unity 编辑器 Web 套接字重新连接到 Node.js MCP 服务器

[！提示]
您的 AI 编码 IDE（例如，Claude Desktop、Cursor IDE、Windsurf IDE）和 MCP 服务器之间的超时取决于 IDE。

调试服务器

MCP Unity 服务器使用 Node.js 构建。它需要在build目录中将 TypeScript 代码编译为 JavaScript。要构建服务器，请打开终端并执行以下操作：

1. 导航到服务器目录：
   cd ABSOLUTE/PATH/TO/mcp-unity/Server~
2. 安装依赖项：
   npm install
3. 构建服务器：
   npm run build
4. 运行服务器：
   node build/index.js

使用@modelcontextprotocol/inspector调试服务器：

• Powershell

• 命令提示符/终端

在关闭终端或使用MCP Inspector进行调试之前，请不要忘记使用Ctrl + C关闭服务器。

1. 在您的终端或 log.txt 文件中启用日志记录：
   • Powershell GXP16
   • 命令提示符/终端 GXP17

故障排除

• 确保 WebSocket 服务器正在运行（检查 Unity 中的服务器窗口）
• 从 MCP 客户端发送控制台日志消息以强制 MCP 客户端和 Unity 服务器之间重新连接
• 在 Unity 编辑器 MCP 服务器窗口中更改端口号。（“工具”>“MCP Unity”>“服务器窗口”）
• 检查 Unity 控制台中的错误消息
• 确保 Node.js 已正确安装并可在 PATH 中访问
• 验证所有依赖项是否都安装在服务器目录中

run_tests工具返回以下响应：

发生此错误的原因是，当切换到播放模式并重新加载域时，桥接连接丢失。
解决方法是在**“编辑”>“项目设置”>“编辑器”>“进入播放模式设置”中关闭“重新加载域”** 。

支持与反馈

如果您有任何疑问或需要支持，请在此存储库上打开一个问题。

您还可以通过以下方式联系我们：

• 领英：
• Discord：gamester7178
• 邮箱： game.gamester@gmail.com

贡献

欢迎贡献代码！欢迎提交 Pull 请求或创建 Issue 来表达你的请求。

按照常规提交格式提交您的更改。

执照

该项目采用MIT 许可证

致谢

• 模型上下文协议
• Unity 技术
• Node.js
• WebSocket-Sharp