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 工具

Editor 工具

Query（查询）

Mutation（修改）

Project（项目）

Asset（资产）

Build 工具

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

需在 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.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 即可。

使用

启动服务

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