UnityMCP集成服务器

Name: UnityMCP集成服务器
Author: quazaai

作者：quazaai94 星标更新：2025-04-15

安装使用来源：spider==github.com

项目介绍

🚀 Unity MCP 高级集成

此包提供了 Model Context Protocol (MCP) 和 Unity 编辑器之间的无缝集成，允许 AI 助手实时理解并与您的 Unity 项目进行交互。通过这种集成，AI 助手可以访问关于场景层次结构、项目设置的信息，并在 Unity 编辑器上下文中直接执行代码。

📚 特性

直接浏览和操作项目文件
访问实时的 Unity 项目信息
理解场景层次结构和游戏对象
在 Unity 编辑器中直接执行 C# 代码
监控日志和错误
控制编辑器的播放模式
等待代码执行

🚀 快速开始

先决条件

Unity 2021.3 或更高版本
Node.js 18+（用于运行 MCP 服务器）

安装

1. 安装 Unity 包

您有几种选项来安装 Unity 包：

选项 A：包管理器（Git URL）

打开 Unity 包管理器（窗口 > 包管理器）
点击 + 按钮并选择 从 Git URL 添加包...
输入仓库 URL：https://github.com/quazaai/UnityMCPIntegration.git
点击 添加

选项 B：导入自定义包

克隆此仓库或下载它作为 unityPackage
在 Unity 中，前往 资源 > 导入包 > 自定义包
选择 UnityMCPIntegration.unitypackage 文件

2. 设置 MCP 服务器

您有两种选项来运行 MCP 服务器：

选项 A：直接运行服务器

导航到 mcpServer 目录（可能位于 <项目路径>\Library\PackageCache\com.quaza.unitymcp@d2b8f1260bca\mcpServer\）
安装依赖项：
```
npm install
```
运行服务器：
```
node build/index.js
```

选项 B：添加到 MCP 主机配置

将服务器添加到您的 MCP 主机配置中，例如 Claude Desktop、自定义实现等

{
  "mcpServers": {
    "unity-mcp-server": {
      "command": "node",
      "args": [
        "path-to-project>\\Library\\PackageCache\\com.quaza.unitymcp@d2b8f1260bca\\mcpServer\\mcpServer\\build\\index.js"
      ],
      "env": {
        "MCP_WEBSOCKET_PORT": "5010"
      }
    }
  }
}

演示视频

通过 Smithery 安装

要通过 Smithery 自动安装 Unity MCP 集成到 Claude Desktop：

npx -y @smithery/cli install @quazaai/unitymcpintegration --client claude

🔧 使用方法

调试和监控

您可以在 Unity 中打开 MCP 调试窗口以监控连接并测试功能：

前往 窗口 > MCP 调试
使用调试窗口：
- 检查连接状态
- 测试代码执行
- 查看日志
- 监控事件

可用工具

Unity MCP 集成提供了一些工具给 AI 助手：

Unity 编辑器工具

get_editor_state: 获取关于 Unity 项目和编辑器状态的全面信息
get_current_scene_info: 获取当前场景的详细信息
get_game_objects_info: 获取场景中特定 GameObject 的信息
execute_editor_command: 在 Unity 编辑器中直接执行 C# 代码
get_logs: 提取并过滤 Unity 控制台日志
verify_connection: 检查是否与 Unity 编辑器有活动连接

文件系统工具

read_file: 读取 Unity 项目中的文件内容
read_multiple_files: 一次读取多个文件
write_file: 创建或覆盖带有新内容的文件
edit_file: 对现有文件进行有针对性的编辑，并预览差异
list_directory: 获取目录中文件和文件夹的列表
directory_tree: 获取目录和文件的分层视图
search_files: 查找匹配搜索模式的文件
get_file_info: 获取特定文件或目录的元数据
find_assets_by_type: 查找特定类型的资产（如材质、预制件）
list_scripts: 获取项目中所有 C# 脚本的列表

文件路径可以是绝对路径或相对于 Unity 项目的 Assets 文件夹。例如，"Scenes/MyScene.unity" 指的是 <项目>/Assets/Scenes/MyScene.unity。

🛠️ 架构

集成由两个主要组件组成：

Unity 插件（C#）: 位于 Unity 编辑器中，提供对编辑器 API 的访问
MCP 服务器（TypeScript/Node.js）: 实现 MCP 协议并与 Unity 插件通信

它们之间的通信通过 WebSocket 发生，传输 JSON 消息用于命令和数据。

文件系统访问

Unity MCP 集成现在包括强大的文件系统工具，允许 AI 助手：

浏览、读取和编辑 Unity 项目中的文件
创建新的文件和目录
查找特定文件或资产类型
分析项目结构
预览差异并进行有针对性的代码更改

所有文件操作都限制在 Unity 项目目录内以确保安全。该系统智能地处理绝对路径和相对路径，并始终将它们解析为相对于项目 Assets 文件夹的位置以便于使用。

示例用法：

获取目录列表：list_directory(path: "Scenes")
读取脚本文件：read_file(path: "Scripts/Player.cs")
编辑配置文件：edit_file(path: "Resources/config.json", edits: [{oldText: "value: 10", newText: "value: 20"}], dryRun: true)
查找所有材质：find_assets_by_type(assetType: "Material")

👥 贡献

欢迎贡献！以下是您可以如何贡献：

分叉仓库
创建一个功能分支 (git checkout -b feature/amazing-feature)
修改代码
提交更改 (git commit -m '添加一些惊人的功能')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

开发设置

Unity 方面：

在 Unity 中打开项目
修改 UnityMCPConnection/Editor 目录下的 C# 脚本

服务器方面：

导航到 mcpServer 目录
安装依赖项：npm install
修改 src 目录下的 TypeScript 文件
构建服务器：npm run build
运行服务器：node build/index.js

📄 许可证

该项目采用 MIT 许可证 - 详情见 LICENSE 文件。

📞 支持

如果您遇到任何问题或有任何疑问，请在 GitHub 仓库上提交问题。