统一-MCP-尖端
项目介绍
🎮 Unity MCP Sharp
适用于Unity编辑器的Model Context Protocol的C#实现
Unity MCP Sharp是一个生产就绪的MCP服务器，使AI助手（如Claude、Cursor等）能够直接与Unity编辑器交互。它基于.NET 9.0和官方的MCP C# SDK构建，提供了26个强大的工具用于游戏开发自动化，包括场景操作、GameObject创建、资产管理以及实时播放模式控制。
🚀 快速开始 • 📦 安装 • 🛠️ MCP工具 • 📖 文档 • ❓ 问题
</div>📋 目录
✨ 特性
<details open> <summary><b>🔌 WebSocket通信（JSON-RPC 2.0）</b></summary>- 实时双向与Unity编辑器通信
- 扩展命令/响应模式
- 支持Unity操作和查询
| 类别 | 工具及资源 |
|---|---|
| 资源（只读） | 项目信息、控制台日志、编译状态、播放模式、活动场景、场景对象、所有场景 |
| 多编辑器 | 列出连接的编辑器、选择会话编辑器 |
| 控制台及编译 | 触发编译、刷新资产 |
| GameObjects | 创建、查找、批量创建、添加组件、设置组件字段、列出场景对象 |
| 场景 | 列表、打开、关闭、保存、获取/设置活动场景 |
| 资产 | 创建脚本、创建具有复杂结构的资产（ScriptableObjects、材质等） |
| 播放模式 | 进入、退出、获取播放模式状态 |
| 系统 | 程序化运行任何Unity菜单项 |
- 多个Unity编辑器：将多个Unity编辑器实例连接到一个MCP服务器
- 每个会话的选择：每个MCP客户端（LLM会话）可以选择并独立工作于不同的编辑器
- 智能自动选择：单编辑器场景无缝工作无需手动选择
- 跨重新编译持久：编辑器选择在Unity脚本编译重连后仍然有效
- 丰富的元数据：每个编辑器报告项目名称、场景、机器、进程ID、Unity版本
- ✅ 所有工具返回确认消息以提供可靠的反馈
- 🔗 工具描述包含交叉引用以便链接操作
- ⚠️ 明确记录副作用和警告
- 📝 丰富的返回描述帮助LLMs理解响应
- 🎨 基于UIToolkit的状态监控仪表板
- 👁️ 操作跟踪的视觉反馈系统
- 🐳 Docker容器生命周期管理
- 🔄 自动连接和启动功能
- ⚙️ 通过ScriptableObject进行配置
- 基于.NET 9.0和ASP.NET Core构建
- 发布到GitHub容器注册表（ghcr.io）
- 多平台支持（linux/amd64, linux/arm64）
- 使用GitHub Actions的完整CI/CD流水线
🏗️ 架构
基本流程
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ AI助手 │ │ Unity编辑器 │ │ Unity包 │
│ (IDE/LLM) │◄────────┤ │◄────────┤ (OpenUPM) │
└────────┬────────┘ MCP │ │ 编辑器 └────────┬────────┘
│ (HTTP) │ │ API │
│ └──────────────────┘ │
│ │
│ │
└────────────────┐ ┌─────────────────┘
│ │
▼ ▼ WebSocket
┌──────────────────────────────┐
│ Unity MCP服务器 │
│ (Docker容器) │
│ ┌────────────────────┐ │
│ │ ASP.NET Core │ │
│ │ - HTTP端点 │ │
│ │ - WebSocket │ │
│ │ - JSON-RPC 2.0 │ │
│ └────────────────────┘ │
└──────────────────────────────┘
多编辑器架构（v0.5.0+）
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ MCP会话 │ │ MCP会话 │ │ MCP会话 │
│ A │ │ B │ │ C │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└────────┬────────┴────────┬────────┘
│ │
▼ ▼
┌─────────────────────────────┐
│ MCP服务器 │
│ ┌───────────────────────┐ │
│ │ 编辑器会话管理器 │ │ 会话 → 编辑器映射
│ │ Mcp会话中间件 │ │ 异步本地上下文
│ └───────────────────────┘ │
└─────────────────────────────┘
│ │ │
┌────────┘ │ └────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│Unity编辑器1 │ │Unity编辑器2 │ │Unity编辑器3 │
│ 项目A │ │ 项目B │ │ 项目C │
│ 场景X │ │ 场景Y │ │ 场景Z │
└──────────────┘ └──────────────┘ └──────────────┘
🚀 快速开始
先决条件
- Unity 2021.3或更高版本
- Docker桌面已安装并运行
- .NET 9.0 SDK（仅限服务器开发）
三步设置
- 安装包（参见安装部分）
- 打开设置向导：在Unity中，
工具 → Unity MCP服务器 → 设置向导 - 启动并连接：通过仪表板，
工具 → Unity MCP服务器 → 仪表板
✅ 完成！现在可以使用AI助手与Unity了。
📦 安装
<details open> <summary><b>选项1：OpenUPM（推荐）⭐</b></summary>openupm add com.mezookan.unity-mcp-sharp
- 打开Unity包管理器
- 点击
+→ "从Git URL添加包..." - 输入：
https://github.com/Abbabon/unity-mcp-sharp.git
添加到 Packages/manifest.json：
{
"dependencies": {
"com.mezookan.unity-mcp-sharp": "https://github.com/Abbabon/unity-mcp-sharp.git"
}
}
第一次设置
<details open> <summary><b>点击展开设置步骤</b></summary>-
安装Docker桌面（如果尚未安装）
- 从docker.com下载
- 启动Docker桌面
-
打开设置向导
- 在Unity中：
工具 → Unity MCP服务器 → 设置向导 - 按照屏幕上的说明操作
- 在Unity中：
-
启动服务器
- 转到
工具 → Unity MCP服务器 → 仪表板 - 点击**“启动服务器”**（首次运行时会下载Docker镜像）
- 点击**“连接”**以建立WebSocket连接
- 转到
-
验证连接
- 仪表板显示“已连接 ✓”（绿色）
- 控制台日志：“Unity MCP服务器连接成功”
🤖 使用AI助手
<details> <summary><b>VS Code / GitHub Copilot</b></summary>添加到 .vscode/settings.json：
{
"mcpServers": {
"unity": {
"url": "http://localhost:8080/mcp",
"transport": "sse"
}
}
}
添加到 ~/.cursor/config.json：
{
"mcpServers": {
"unity": {
"url": "http://localhost:8080/mcp",
"transport": "sse"
}
}
}
添加到你的Claude Desktop MCP配置：
{
"mcpServers": {
"unity": {
"url": "http://localhost:8080/mcp",
"transport": "sse"
}
}
}
🛠️ 可用的MCP工具及资源
<details> <summary><b>📚 MCP资源（7个资源）</b></summary>所有工具都设计为最佳LLM交互，带有确认消息、工具链提示和副作用警告。
新版本v0.4： 资源是只读的应用程序控制的数据源，在每次访问时提供新鲜数据。它们通过将读取操作与基于动作的工具分离来减少LLM的认知负荷。
unity://project/info
Unity项目的元数据，包括名称、版本、活动场景、路径和编辑器状态。
返回值： 包含名称、Unity版本、活动场景、数据路径、播放/暂停状态的项目信息
💡 提示： 当开始处理项目时首先使用此资源以了解环境。
🔄 更新： 当场景变化或播放模式变化时自动更新
unity://console/logs
Unity编辑器中的最近控制台日志（错误、警告、调试日志）。
返回值： 包含类型、消息和堆栈跟踪的控制台日志
💡 提示： 在创建脚本、进入播放模式或编译失败后检查此资源。
🔄 更新： 当新的日志消息出现时自动更新
unity://compilation/status
当前编译状态和上次编译结果。
返回值： 编译状态（空闲/编译中）和成功/失败状态
🔗 相关： unity_trigger_script_compilation
🔄 更新： 当编译开始或结束时自动更新
unity://editor/playmode
Unity编辑器当前的播放模式状态。
返回值： 播放模式状态（播放、暂停或停止）
🔗 相关： unity_enter_play_mode, unity_exit_play_mode
🔄 更新： 当播放模式变化时自动更新
unity://scenes/active
关于当前活动Unity场景的信息。
返回值： 场景名称、路径、isDirty状态、根GameObject数量、加载状态
💡 提示： 如果isDirty为真，请使用unity_save_scene保存更改。
🔄 更新： 当活动场景变化或场景被加载时自动更新
unity://scenes/active/objects
活动场景的完整GameObject层次结构。
返回值： 包含激活/非激活状态指示符的分层列表
🔗 相关： unity_find_game_object, unity_create_game_object
🔄 更新： 当场景变化时自动更新
unity://scenes/all
项目中所有.unity场景文件的列表。
返回值： 相对于项目根目录的场景路径列表
🔗 相关： unity_open_scene, unity_get_active_scene
🔄 更新： 当资产数据库刷新时
</details> <details> <summary><b>🔍 系统及编译（1个工具）</b></summary>unity_trigger_script_compilation
强制Unity重新编译所有C#脚本。
返回值： 确认编译已被触发
⚠️ 注意： Unity在编译期间暂时断开连接。使用unity://compilation/status资源后验证成功。
unity_create_game_object
在当前活动场景中创建一个新的GameObject。
参数：
name(字符串，必需)：GameObject名称x,y,z(浮点数，默认：0)：世界位置components(字符串，可选)：逗号分隔的组件（例如："Rigidbody,BoxCollider"）parent(字符串，可选)：父GameObject名称
返回值： 包含名称、位置、组件和层次结构位置的确认
📌 示例： 在位置(0, 1, 0)处创建一个带有Rigidbody和CapsuleCollider的"Player"
🔗 相关： unity_find_game_object, unity_add_component_to_object
unity_find_game_object
按名称、标签或路径查找GameObject，并提供详细信息。
参数：
name(字符串，必需)：GameObject名称searchBy(字符串，默认："name")：搜索模式："name"、"tag"或"path"
返回值： 位置、旋转、比例、激活状态以及所有附加组件
🔗 相关： unity_list_scene_objects, unity_add_component_to_object
unity_add_component_to_object
向现有的GameObject添加一个组件。
参数：
gameObjectName(字符串，必需)：目标GameObjectcomponentType(字符串，必需)：组件类型（例如："Rigidbody"、"BoxCollider"、自定义脚本）
返回值： 确认组件已添加
💡 提示： 使用unity_find_game_object先验证GameObject存在。