Unity MCP Server

中文 | English

Unity Editor 插件，通过 MCP (Model Context Protocol) 将 Unity Editor 能力暴露给外部 AI Agent。

Agent（如 Kiro、Cursor、Claude Code）可通过标准 MCP 协议连接到 Unity Editor，调用编辑器功能。

理念

本插件定位为 AI Agent 的 Unity 感知层 + 诊断工具链：

  • 感知优先 — 优先覆盖"读取场景状态、获取上下文、辅助诊断"等高频场景，让 Agent 能充分理解当前工程状态并辅助开发决策。
  • 结构化写入 — 提供安全、可审计的写操作能力（如修改属性、增删节点），但不追求覆盖 Unity Editor GUI 的所有交互。
  • 不替代编辑器 — 目标是增强工程师与 Agent 协作的效率，而非将 Editor 的全部操作搬到对话框里。

特性

  • Streamable HTTP 传输 — 基于 MCP 2025-03-26 规范，单一 HTTP 端点
  • 进程内运行 — 无需外部 Node.js/Python 进程，直接在 Editor 内启动
  • 可扩展工具系统 — 实现 IMcpTool 接口即可注册新工具，零修改核心代码
  • Domain Reload 自动恢复 — 进入/退出 PlayMode 后服务自动重启

内置工具

完整的参数说明和使用示例见 工具详细文档。

Debug 工具

工具 功能
console_getLogs 获取 Unity Console 日志（支持过滤）
console_clearLogs 清空日志缓冲区
debug_getStackTrace 获取最近 Error/Exception 的完整堆栈
debug_getPerformanceStats 获取 FPS、DrawCall、内存等性能指标
debug_screenshot 截取 Game/Scene 视图截图（暂时禁用）

Editor 工具

Query（查询）
工具 功能
editor_getHierarchy 获取 GameObject 树结构
editor_getInspector 获取 Inspector 序列化字段值
editor_getSelection 获取当前选中对象信息
editor_findGameObjects 按名称/组件搜索 GameObject
editor_getProjectPath 获取项目根目录路径
editor_getProjectStructure 获取 Assets 目录结构
Mutation（修改）
工具 功能
editor_addGameObject 添加 GameObject
editor_deleteGameObject 删除 GameObject
editor_setField 修改序列化字段值
editor_setTransform 修改 Transform 属性
editor_setActive 修改激活状态
editor_reparentGameObject 修改父节点
editor_addComponent 添加组件
editor_removeComponent 移除组件
editor_setComponentEnabled 启用/禁用组件
editor_selectGameObject 选中指定 GameObject
Project（项目）
工具 功能
menu_execute 按路径执行 Unity 菜单项
playmode_control 控制 PlayMode 状态
Asset（资产）
工具 功能
asset_deleteFolder 删除 Assets 子目录

Build 工具

工具 功能
build_compile 触发脚本编译
build_getCompileErrors 获取编译错误列表
build_runTests 运行 Test Runner 测试

Code 工具（实验性，仅 Unity 2022 Mono）

工具 功能
code_executeImmediate 动态编译并执行 C# 代码（支持主线程/后台双模式）

需在 Window → MCP Server 面板手动开启。详见 工具详细文档。

安装

Git URL 安装（推荐）

  1. Unity Editor → Window → Package Manager → + → Add package from git URL
  2. 输入以下 URL：
https://github.com/yangfch3/Unity-MCP-Server.git

或直接编辑宿主项目的 Packages/manifest.json：

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

本地路径安装

  1. 克隆本仓库
  2. Unity Editor → Window → Package Manager → + → Add package from disk
  3. 选择本仓库根目录的 package.json

或在 Packages/manifest.json 中添加：

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "file:../../path/to/unity-mcp"
  }
}

版本更新

UPM 通过 Git URL 安装后，会在宿主项目的 packages-lock.json 中锁定当前 commit hash。后续不会自动更新。

如需锁定特定版本，可在 URL 末尾追加 Git Tag：

https://github.com/yangfch3/Unity-MCP-Server.git#v0.3.0

对应 Packages/manifest.json 配置：

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git#v0.3.1"
  }
}

不带 Tag 则跟踪默认分支最新 commit：

{
  "dependencies": {
    "com.yangfch3.unity-mcp": "https://github.com/yangfch3/Unity-MCP-Server.git"
  }
}

更新版本时，修改 manifest.json 中的 #tag 后缀为新版本号，或在 UPM GUI 重新 Add package from git URL 输入新 Tag 的 URL 即可。

使用

启动服务

  1. Unity Editor → Window → MCP Server
  2. 设置端口（默认 8090），点击 Start
  3. 复制面板中的配置 JSON

配置 Agent

将以下内容添加到 Agent 的 MCP 配置文件（如 mcp.json）：

{
  "mcpServers": {
    "unity-mcp": {
      "url": "http://localhost:8090/"
    }
  }
}

扩展：添加自定义工具

实现 IMcpTool 接口，放在任意 Editor 程序集中，服务启动时会自动发现并注册：

using System.Collections.Generic;
using System.Threading.Tasks;
using UnityMcp.Editor;

public class MyCustomTool : IMcpTool
{
    public string Name => "my_custom_tool";
    public string Category => "custom";
    public string Description => "我的自定义工具";
    public string InputSchema => "{\"type\":\"object\",\"properties\":{}}";

    public Task<ToolResult> Execute(Dictionary<string, object> parameters)
    {
        return Task.FromResult(ToolResult.Success("Hello from custom tool!"));
    }
}

要求

  • Unity 2022.3+
  • 仅 Editor 环境，不影响运行时构建

参与贡献

欢迎参与本项目的开发，详见 CONTRIBUTING.md。

License

MIT