星战科技xingzhan.cloud
返回市场
Unity-MCP服务器

Unity-MCP服务器

作者：MiAO-AI-Lab22 星标更新：2025-08-18
安装使用来源：spider==github.com

项目介绍

Unity MCP (服务器 + 插件)

License Stand With Ukraine

image

Unity 版本编辑模式播放模式独立模式
2022.3.61f12022.3.61f12022.3.61f12022.3.61f1
2023.2.20f12023.2.20f12023.2.20f12023.2.20f1
6000.0.46f16000.0.46f16000.0.46f16000.0.46f1

Unity-MCP 是一个连接大型语言模型（LLM）与Unity的桥梁。它向LLM暴露并解释了Unity的工具。LLM理解接口，并根据用户请求的方式利用这些工具。

通过集成的 AI Connector 窗口，将 Unity-MCP 连接到LLM客户端，如 Claude 或 Cursor。支持自定义客户端。

该项目旨在让开发者能够添加自定义工具。接下来的目标是在玩家构建中启用相同的功能。目前仅在Unity编辑器中工作。

该系统是可扩展的：您可以在Unity项目代码库中直接定义自定义 tool，向AI或自动化客户端暴露新的能力。这使得Unity-MCP成为构建高级工作流程、快速原型设计或将AI驱动功能集成到开发过程中的灵活基础。

✅ 新核心功能

🚀 1. 工作流中间件架构

架构概述：

AI代理 → MCP协议 → McpServer（工作流中间件）→ Unity运行时
                              ↓
                        RPC网关 → ModelUse/Unity等
                              ↓  
                        工作流编排引擎

工作流架构

层1：RPC网关

  • ✅ 动态Unity工具发现 - 通过 ToolRouter_ListAll RPC 实现运行时发现
  • ✅ 工具调用 - 自动生成的工具代理
  • ✅ 统一接口 - 所有RPC调用通过统一的 IRpcGateway 接口

层2：工作流编排

  • ✅ 表达式语法支持 - ${input.param}，${step.result}
  • ✅ 条件执行 - 步骤条件和重试策略
  • ✅ 多种步骤类型 - rpc_call，model_use，data_transform

2. AI模型集成及ModelUse API

提供Unity完整的AI模型使用API：

  • 双向通信：Unity运行时 ↔ MCP服务器 ↔ 代理
  • 反向模型调用：Unity可以主动请求代理的AI模型能力
  • 模型类型支持：文本、视觉、代码分析和其他AI模型
  • 统一API接口：通过ModelUse API统一访问各种AI服务

3. 交互式用户输入系统

  • ✅ 询问用户输入工具 - 交互式用户输入收集
  • ✅ 撤销与重做系统 - 完整的撤销/重做功能用于GameObject操作

4. 工具系统

增加了众多工具特性

AI工具

<table> <tr> <td valign="top">

GameObject

  • ✅ 创建
  • ✅ 销毁
  • ✅ 查找
  • ✅ 修改（标签、图层、名称、静态）
  • ✅ 设置父对象
  • ✅ 复制
  • ✅ 设置激活/非激活
  • ✅ 设置组件激活/非激活
GameObject.Components
  • ✅ 添加组件
  • ✅ 获取组件
  • ✅ 修改组件
    • ✅ 字段 设置值
    • ✅ 属性 设置值
    • ✅ 引用 链接设置
  • ✅ 销毁组件
  • ✅ 缺失组件检测
  • 🔲 移除缺失组件

编辑器

  • ✅ 状态（播放模式）
    • ✅ 获取
    • ✅ 设置
  • ✅ 获取窗口
  • ✅ 图层
    • ✅ 获取所有
    • ✅ 添加
    • ✅ 删除
  • ✅ 标签
    • ✅ 获取所有
    • ✅ 添加
    • ✅ 删除
  • ✅ 执行 MenuItem
  • 🔲 运行测试

编辑器选择

  • ✅ 获取选择
  • ✅ 设置选择

预制件

  • ✅ 实例化
  • ✅ 创建
  • ✅ 打开
  • ✅ 修改（GameObject.Modify）
  • ✅ 保存
  • ✅ 关闭

包

  • 🔲 获取已安装
  • 🔲 安装
  • 🔲 删除
  • 🔲 更新

动画

  • ✅ 添加事件
  • ✅ 读取片段

时间线管理器

  • ✅ 创建并附加
  • ✅ 添加轨道
  • ✅ 列出轨道
  • ✅ 添加片段
  • ✅ 添加标记
  • ✅ 获取标记
  • ✅ 添加信号标记

环境查询系统

  • ✅ 智能空间查询
    • ✅ 兴趣区域
    • ✅ 硬条件
    • ✅ 软评分
    • ✅ 权重合成
  • ✅ 位置选择
  • ✅ 对象放置

骨骼分析与可视化

  • ✅ 骨骼层次分析
  • ✅ 骨骼参考检测

交互式工具

  • ✅ 等待用户输入
</td> <td valign="top">

资产

  • ✅ 创建
  • ✅ 查找
  • ✅ 刷新
  • ✅ 读取
  • ✅ 修改
  • ✅ 重命名
  • ✅ 删除
  • ✅ 移动
  • ✅ 创建文件夹

场景

  • ✅ 创建
  • ✅ 保存
  • ✅ 加载
  • ✅ 卸载
  • ✅ 获取已加载
  • ✅ 获取层次结构
  • ✅ 搜索（编辑器）
  • ✅ 射线检测（理解体积）

相机

  • ✅ 相机控制
  • ✅ 屏幕捕获

材料

  • ✅ 创建
  • ✅ 修改（资产修改）
  • ✅ 读取（资产读取）
  • ✅ 分配给GameObject上的组件

着色器

  • ✅ 列出所有

脚本

  • ✅ 读取
  • ✅ 更新或创建
  • ✅ 删除

可编程对象

  • ✅ 创建
  • ✅ 读取
  • ✅ 修改
  • ✅ 删除

调试

  • ✅ 读取日志（控制台）

组件

  • ✅ 获取所有

AI模型工具

  • ✅ ModelUse 文本
  • ✅ ModelUse 视觉
  • ✅ ModelUse 代码

物理工具

  • ✅ 射线投射
  • ✅ 球体投射
  • ✅ 箱体投射
  • ✅ 胶囊投射
  • ✅ 重叠
  • ✅ 视线
  • ✅ 多射线

图层工具

  • ✅ 列出图层
  • ✅ 计算图层掩码
  • ✅ 解码图层掩码
  • ✅ 场景分析
</td> </tr> </table>

🚀 待办事项路线图

<table> <tr> <td valign="top">

架构层

McpServer 聚合器

  • 🔲 多模型兼容性
  • 🔲 多上游数据流
    • 🔲 Unity集成
    • 🔲 3dsMax集成
    • 🔲 Maya集成
    • 🔲 Houdini集成
    • 🔲 Figma集成
  • 🔲 自定义中间件系统
  • 🔲 共享上下文
  • 🔲 管道并行执行

工作流引擎

  • ✅ 数据流编排
  • ✅ 管道并行执行
  • 🔲 错误处理与回滚
  • 🔲 工作流模板

AI工具层

动画与绑定

  • 🔲 动画状态机编辑器
  • 🔲 动画过渡工具
  • 🔲 动画片段处理
  • 🔲 骨骼检测工具
  • 🔲 附着点工具

高级EQS

  • 🔲 增强的空间智能EQS

视觉编程

  • 🔲 Unity VisualScripting生成
  • 🔲 行为设计器集成
  • 🔲 NodeCanvas集成
  • 🔲 自定义节点创建
  • 🔲 流程图分析/测试

UI & UX工具

  • 🔲 UXML\USS生成
  • 🔲 USS生成
  • 🔲 UI Toolkit集成
  • 🔲 数据绑定

资产层

资产智能

  • 🔲 特征识别
  • 🔲 资产索引
  • 🔲 嵌入/元数据生成
  • 🔲 相似性检测
  • 🔲 自动分类
  • 🔲 依赖关系映射
</td> </tr> </table>

图例： ✅ = 已实现并可用，🔲 = 计划/尚未实现

  • 编辑器自动化：提供了丰富的API来自动化Unity编辑器操作
  • AI集成：支持连接和与AI模型互动
  • 资产管理：提供了管理和操作Unity资产的工具
  • 动画工具：用于读取和修改动画片段的工具
  • 时间线工具：用于操作Unity时间线资产的工具
  • 组件操作：提供了访问和修改游戏对象组件的API
  • 选择工具：用于获取和设置Unity编辑器中的选择
  • EQS工具：环境查询系统工具，用于智能空间查询、位置选择和对象放置
  • 射线投射工具：物理射线投射工具，支持多种射线类型（射线、球体、箱体、胶囊）和碰撞检测模式
  • 控制台日志：带有过滤器获取控制台日志
  • 简化和压缩工具数量，确保模型性能不会因过多的工具调用而下降。

安装

  1. 安装.NET 9.0
  2. 在本地克隆此仓库，并将其放置在Unity的Packages目录下，路径为 Packages/com.miao.mcp/{仓库内容}
  3. 手动添加到manifest.json：
{
    "scopedRegistries": [
        {
        "name": "package.openupm.com",
        "url": "https://package.openupm.com",
        "scopes": [
            "org.nuget"
        ]
        }
    ]
}

使用

  1. 确保您的项目路径中没有空格符号 " "。
  • ✅ C:/MyProjects/Project
  • ❌ C:/My Projects/Project
  1. 打开Unity项目，前往 👉 窗口/MCP Hub。

Unity_WaSRb5FIAR

  1. 安装MCP客户端
  1. 登录MCP客户端
  2. 在您的MCP客户端中点击 配置。

image

  1. 重新启动您的MCP客户端。
  2. 确保 AI连接器 在重启后处于“已连接”或“正在连接...”状态。
  3. 在您的客户端（Cursor，Claude桌面）中测试AI连接。在聊天框中输入任何问题或任务。例如：
  解释我的场景层次结构

AI配置（可选）

image

添加自定义 tool

⚠️ 它仅适用于支持动态工具列表更新的MCP客户端。

Unity-MCP旨在支持项目所有者开发自定义 tool。MCP服务器从Unity插件获取数据并将其暴露给客户端。因此，MCP通信链中的任何人都会收到有关新 tool 的信息。LLM可能会决定在某个时刻调用它。

要添加自定义 tool，您需要：

  1. 有一个带有 McpPluginToolType 属性的类。
  2. 在类中有带有 McpPluginTool 属性的方法。
  3. [可选] 为每个方法参数添加 Description 属性，以便LLM理解它。
  4. [可选] 使用 string? optional = null 属性和 ? 默认值来标记它们为LLM的 可选。

注意 MainThread.Instance.Run(() => 这一行，它允许在主线程中运行代码，这对于与Unity API交互是必要的。如果您不需要它，并且在后台线程中运行工具是可以接受的，请为了效率考虑不要使用主线程。

[McpPluginToolType]
public class Tool_GameObject
{
    [McpPluginTool
    (
        "MyCustomTask",
        Title = "创建一个新的GameObject"
    )]
    [Description("在这里向LLM解释这是什么，何时应该调用它。")]
    public string CustomTask
    (
        [Description("向LLM解释这是什么。")]
        string inputData
    )
    {
        // 在后台线程中执行任何操作

        return MainThread.Instance.Run(() =>
        {
            // 如果需要，在主线程中执行某些操作

            return $"[成功] 操作完成。";
        });
    }
}

添加自定义游戏内 tool

⚠️ 尚不支持。正在进行中

🎯 中间件工作流

工作流定义语法：

{
  "id": "simple_equipment_binding",
  "steps": [
    {
      "id": "find_character",
      "type": "rpc_call", 
      "connector": "unity",
      "operation": "GameObject_Find",
      "parameters": { "name": "${input.characterName}" }
    },
    {
      "id": "validate_character",
      "type": "model_use",
      "connector": "model