# UnityEditorMCP

**Repository Path**: furanzhang/unity-editor-mcp

## Basic Information

- **Project Name**: UnityEditorMCP
- **Description**: 🚀 UnityEditorMCP 是一个兼容 Unity 2019.4 LTS +的 MCP 工具项目，用于让支持 MCP 的 AI 客户端连接并操作 Unity Editor，支持场景、对象、组件、资源、脚本与 Prefab 等常用编辑器操作。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-09-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎮 Unity Editor MCP

让支持 MCP 的 AI 客户端稳定操作 Unity Editor。

最低兼容 Unity `2019.4 LTS`，支持更高版本。

## ✨ 亮点

- 🚀 Unity Bridge 自动随 Editor 启动，默认监听 `127.0.0.1:8765`
- 🔎 MCP Server 自动探测 `8765-8775` 端口范围内的 Unity 工程
- 🧭 支持多 Unity 工程路由，可自动按工程路径、工程名或运行时选择目标
- 🧊 基础几何体秒级原生创建：`unity_gameobject_create` 支持 `primitiveType`（Cube、Sphere、Capsule、Cylinder、Plane、Quad），0 编译、毫秒级响应
- 📋 控制台实时自检诊断：`unity_console_get_logs` / `unity_console_clear` 读取 Console 日志与异常堆栈，支持 AI 全自动排错
- 📸 视口画面捕获：`unity_viewport_screenshot` 实时捕获 SceneView / GameView / Camera 渲染图像，打通多模态视觉闭环
- 🎮 运行态控制：`unity_editor_play_mode` 自由切换 Play / Stop / Pause / Step，支持自动化运行与验证
- 🎨 UI 原型极速构建：`unity_ui_create` 一键生成 Button、Text、Image、Panel、Canvas，自动装配 TextMeshPro 与 EventSystem
- 📐 空间感知与物理射线：`unity_bounds_get` 计算全局复合包围盒，`unity_raycast` 发射物理射线，精准防悬空与穿模
- 🖌️ 材质属性快速配置：`unity_material_set_property` 快速修改材质颜色、贴图与 Shader 参数
- 🧱 覆盖场景、Hierarchy、GameObject、Transform、Component、Asset、Prefab、脚本等常用编辑器操作
- 🛠️ 内置 `Tools > Unity MCP` 窗口，可查看状态、日志和权限开关

## 📦 版本

| 模块 | 包名 / 版本 |
| --- | --- |
| Unity Bridge | `com.yys.unity-mcp-bridge@0.7.1` |
| MCP Server | `@luoluo123/unity-mcp-server@0.7.0` |
| Unity | `2019.4 LTS+` |
| Node.js | `18+` |

## ⚡ 快速开始

### 1. 安装 Unity Bridge

在 Unity 中打开：

```text
Window > Package Manager > + > Add package from git URL...
```

输入任一地址：

```text
https://gitee.com/furanzhang/unity-editor-mcp.git?path=/Packages/com.yys.unity-mcp-bridge#v0.7.1
```

```text
https://github.com/FRZ5201314/UnityEditorMCP.git?path=/Packages/com.yys.unity-mcp-bridge#v0.7.1
```

导入后可在 Unity 菜单打开：

```text
Tools > Unity MCP
```

### 2. 配置 MCP Server

MCP Server 已发布为 npm 包，推荐用 `npx` 启动：

```json
{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@luoluo123/unity-mcp-server@0.7.0"],
  "env": {
    "UNITY_MCP_AUTO_DETECT": "true",
    "UNITY_MCP_DETECT_HOST": "127.0.0.1",
    "UNITY_MCP_DETECT_PORT_START": "8765",
    "UNITY_MCP_DETECT_PORT_END": "8775",
    "UNITY_MCP_TIMEOUT_MS": "30000"
  },
  "enabled": true
}
```

### 3. 验证连接

启动 Unity Editor 和 MCP 客户端后调用：

```text
unity_health
```

返回 Bridge 状态信息即连接成功。

## 🧩 项目结构

```text
Packages/com.yys.unity-mcp-bridge/   Unity Editor Bridge UPM 包
server/                              Node.js MCP stdio server
docs/                                使用说明、测试记录和实现文档
```

## 🧭 多工程

同时打开多个 Unity 工程时，每个 Bridge 会自动占用 `8765-8775` 中的可用端口。MCP Server 的选择优先级：

1. `UNITY_MCP_BRIDGE_URL`
2. `UNITY_MCP_PROJECT_PATH`
3. `UNITY_MCP_PROJECT_NAME`
4. 当前工作目录推断
5. 唯一在线 Bridge
6. 多个候选时通过 `unity_bridge_list` / `unity_bridge_select` 手动选择

## 🔐 权限与日志

Bridge 日志：

```text
Library/UnityMcp/bridge.log
```

`Tools > Unity MCP` 中可切换：

- `Allow Scene Object Delete`
- `Allow Asset Delete`
- `Allow Script Write`

这些开关只限制 MCP Bridge 暴露的命令入口，不是 Codex、Shell、Unity UI 或文件系统层面的全局安全边界。

## 🛠 常用工具
 
- `unity_health`：连接健康检查
- `unity_bridge_list` / `unity_bridge_select`：多工程 Bridge 发现与切换
- `unity_project_get_info`：获取 Unity 版本与工程信息
- `unity_scene_get_active` / `unity_scene_open` / `unity_scene_save`：场景生命周期管理
- `unity_hierarchy_list` / `unity_gameobject_find`：层级与对象查找
- `unity_gameobject_create`：创建 GameObject（支持 `primitiveType`: Cube, Sphere, Capsule 等原生基础几何体）
- `unity_transform_set` / `unity_transform_get`：世界/本地坐标变换设置与读取
- `unity_component_add` / `unity_component_set_property`：组件挂载与属性修改
- `unity_console_get_logs` / `unity_console_clear`：Console 日志与异常堆栈查询及清空
- `unity_viewport_screenshot`：SceneView / Camera 视口画面捕获输出 PNG 截图
- `unity_editor_play_mode`：Editor 运行模式控制（Play/Stop/Pause/Step/GetState）
- `unity_ui_create`：原生创建常用 UI 原型（Canvas, Button, Text, Image, Panel，优先 TMP）
- `unity_bounds_get` / `unity_raycast`：计算复合全局包围盒与物理射线检测
- `unity_material_set_property`：快速配置材质颜色、贴图与 Shader 浮点参数
- `unity_asset_find` / `unity_asset_refresh`：资产检索与刷新
- `unity_prefab_create` / `unity_prefab_instantiate`：预制体制作与实例化
- `unity_script_create` / `unity_script_attach`：MonoBehaviour 脚本创建与挂载

完整工具和参数见 [完整使用说明](docs/mcp-usage-guide.md)。

## 📚 文档

- [完整使用说明](docs/mcp-usage-guide.md)
- [开发进度](docs/development-status.md)
- [实现计划](docs/implementation-plan.md)