MCP 服务器

Unity MCP Server

A Unity Editor plugin that exposes Unity Editor capabilities to external AI agents via the Model Context Protocol. It enables AI agents to interact with Unity through tools for debugging, scene inspection, project management, and build operations.

README

Unity MCP Server

中文 | English

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

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

特性

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

内置工具

工具	分类	功能
`console_getLogs`	debug	获取 Unity Console 最近 N 条日志
`debug_getStackTrace`	debug	获取最近一条 Error/Exception 的完整堆栈
`debug_getPerformanceStats`	debug	获取 FPS、DrawCall、内存占用等性能指标
`debug_screenshot`	debug	截取 Game/Scene 视图截图（base64 PNG）
`menu_execute`	editor	按路径执行 Unity 菜单项
`playmode_control`	editor	进入/退出/查询 PlayMode 状态
`editor_getSelection`	editor	获取当前选中的 GameObject 和 Asset 信息
`editor_getHierarchy`	editor	获取场景 GameObject 树结构（可限深度）
`editor_getProjectStructure`	editor	获取 Assets 目录结构（可限深度）
`editor_getInspector`	editor	获取选中对象的 Inspector 序列化字段值
`build_compile`	build	触发脚本编译并返回结果
`build_getCompileErrors`	build	获取当前编译错误列表
`build_runTests`	build	运行 Unity Test Runner 测试并返回结果

安装

Git URL 安装（推荐）

Unity Editor → Window → Package Manager → + → Add package from git URL
输入以下 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"
  }
}

本地路径安装

克隆本仓库
Unity Editor → Window → Package Manager → + → Add package from disk
选择本仓库根目录的 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.1.0

对应 Packages/manifest.json 配置：

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

不带 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 即可。

使用

启动服务

Unity Editor → Window → MCP Server
设置端口（默认 8090），点击 Start
复制面板中的配置 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!"));
    }
}