内容
# Unity MCP Claude 代码
> **一个专业的MCP服务器，通过Claude Unity Hub + Unity编辑器实现真正的自动化操作 — 从而构建完整的游戏，生成自己的高级2D/3D资产，并创建高质量的PBR纹理。**
[](LICENSE)
该服务器为Claude（Claude Code **和** Claude Desktop）提供真正的Unity操作能力：不仅可以**讨论**Unity，还可以安装编辑器、创建项目、编写代码、构建整个场景、生成资产、运行测试、分析和生成可执行文件 — 所有操作均通过最稳定的接口自动完成。
> 在 **Windows 11** 上针对 **Unity Hub 3.18** 和 **Unity编辑器 6000.4.10f1 (Unity 6)** 进行开发和 **实时验证**。
---
## 目录
- [亮点](#亮点)
- [Claude可以做什么？（94种工具）](#claude可以做什么94种工具)
- [“从零开始构建游戏”的流水线](#从零开始构建游戏的流水线)
- [自己生成高级图形](#自己生成高级图形)
- [控制策略](#控制策略)
- [安装](#安装)
- [Claude集成](#claude集成)
- [安全](#安全)
- [项目结构](#项目结构)
- [开发和测试](#开发和测试)
---
## 亮点
- 🎮 **构建完整的游戏** — 从C#游戏逻辑到基于JSON的场景，再到可执行文件，无需手动操作编辑器。
- 🧱 **从JSON生成专业场景** — GameObjects，URP材质，**完整的PBR**（基础颜色 + 法线 + AO + 金属/遮罩），物理，任意组件属性（包括对象/资产引用），预制件，环境和**后期处理**（Bloom/Vignette/Tonemapping ...）。
- 🎨 **自己生成资产** — **Blender** 无头（网格/材质/烘焙/导出GLB+FBX，CYCLES渲染），**free-tex-packer** （精灵图集），**Figma** REST（UI → PNG/SVG），**Krita** （.kra → PNG）。
- 🪨 **高级PBR纹理** — CC0库 **ambientCG** 和 **Poly Haven** （扫描，1K–8K）加 **程序化Blender烘焙** — 自动正确地连接到URP。
- 🤖 **动画** — 动画控制器，程序化剪辑，剪辑名称来自FBX（例如Mixamo/KayKit）。
- 🔍 **视觉QA和性能分析** — 场景 → PNG（Claude **看到**结果），编译器错误结构化，运行时FPS/内存/GC。
- 🖱️ **GUI自动化** — 真实的点击/键盘输入 + UIA检查，用于GUI-only流程的Electron Hub。
- 🛡️ **设计安全** — 确认门，路径沙盒，自动备份，编辑审计日志，敏感Hub文件的保护。
---
## Claude可以做什么？（94种工具）
完整目录及参数： **[docs/TOOLS.md](docs/TOOLS.md)**。按领域概览：
| # | 领域 | 工具 | 示例 |
|---|---|---:|---|
| 1 | **状态和进程** | 6 | `get_environment_status`，`launch_hub`，`stop_editor` |
| 2 | **编辑器和安装** | 9 | `install_editor`，`list_installed_editors`，`resolve_editor_changeset` |
| 3 | **项目** | 8 | `create_project`，`open_project`，`register_project_in_hub` |
| 4 | **编辑器自动化** | 9 | `build_player`，`run_tests`，`check_compile`，`run_editor_method` |
| 5 | **包（manifest.json）** | 3 | `add_project_package`，`remove_project_package` |
| 6 | **Hub设置** | 4 | `get_hub_settings`，`set_default_project_dir` |
| 7 | **日志，作业和诊断** | 8 | `read_editor_log`，`get_job_status`，`detect_errors_in_log` |
| 8 | **许可证（安全）** | 3 | `get_license_status`，`create_manual_activation_file` |
| 9 | **深链接/ GUI桥** | 4 | `open_create_project_ui`，`screenshot_desktop` |
| 10 | **备份和安全** | 2 | `list_backups`，`restore_backup` |
| 11 | **游戏创作** | 19 | `write_script`，`build_scene`，`capture_scene_render`，`profile_play`，`build_animator_controller` |
| 12 | **GUI自动化** | 6 | `gui_click`，`gui_inspect_window`，`gui_send_keys` |
| 13 | **资产创建 — Blender** | 4 | `blender_run_python`，`blender_render_preview`，`blender_bake_pbr` |
| 14 | **2D图集（free-tex-packer）** | 1 | `pack_sprite_atlas` |
| 15 | **Figma UI导出** | 2 | `figma_export_images`，`figma_get_outline` |
| 16 | **Krita** | 2 | `krita_export`，`krita_open` |
| 17 | **高级PBR纹理** | 4 | `download_pbr_material`，`download_polyhaven_texture` |
---
## “从零开始构建游戏”的流水线
```text
create_project # 空Unity项目
└─ write_script # C#游戏逻辑（MonoBehaviours）到Assets/
└─ build_scene # 世界 + 组件 + 材质/物理从JSON
└─ check_compile # 结构化检查错误 → 可能的write_script（自动修复）
└─ capture_scene_render # 场景 → PNG：Claude检查图像
└─ build_player # 完成的可执行文件
```
`build_scene`是核心：一个**JSON规范**描述整个场景，并通过注入的C#编辑器脚本转换为真正的`.unity` — 包括URP/ PBR材质，`Rigidbody`/`PhysicsMaterial`，通用属性设置（字段 → 属性 → 序列化对象）与对象/资产引用，预制件，环境/雾/环境光和后期处理卷。
证明可构建（演示在 [`scripts/`](scripts)）：几个可玩的3D游戏，包括物理，WASD控制，分数，Bloom HUD和动画角色。
---
## 自己生成高级图形
**一致性原则**：一个源 = 统一的外观。该服务器可以**获取**，**生成**和正确**安装**高级资产：
| 需求 | 工具 | 源 |
|---|---|---|
| 3D网格/材质 | `blender_run_python` | Blender（bpy，无头）→ GLB/FBX |
| 3D预览检查 | `blender_render_preview` | Blender CYCLES → PNG |
| **PBR纹理（扫描）** | `search_pbr_materials` / `download_pbr_material` | ambientCG（CC0，1K–8K） |
| **PBR纹理（扫描）** | `search_polyhaven_textures` / `download_polyhaven_texture` | Poly Haven（CC0） |
| **PBR纹理（程序化）** | `blender_bake_pbr` | Blender烘焙（砖/岩石/木头/金属） |
| 精灵图集（2D） | `pack_sprite_atlas` | free-tex-packer |
| 游戏UI | `figma_export_images` | Figma REST（PNG/SVG） |
| 2D手工润色 | `krita_open` / `krita_export` | Krita |
下载/烘焙的贴图在`build_scene`中**自动正确**处理：法线贴图作为`NormalMap`导入（ `_NORMALMAP` + `_BumpMap`/`_BumpScale`），AO/遮罩 **线性**（ `_OcclusionMap` / `_MetallicGlossMap`）。结果：真正的浮雕和深度，而不是扁平的纹理贴图 — 无需手动干预的高级外观。
> 资产工具的前提条件是各自的程序（Blender，Krita）或`FIGMA_TOKEN`。如果缺少某个程序，工具会干净地报告；Unity核心功能无需它们即可运行。
---
## 控制策略
没有万能的Unity API。相反，服务器使用 **混合** 机制，每个机制都是通过直接测量验证的最稳定机制：
| 层 | 用途 | 稳定性 |
|---|---|---|
| **Unity Hub CLI** (`Unity Hub.exe -- --headless …`) | 安装/列出编辑器，安装路径 | 高 |
| **Unity 编辑器 CLI** (`Unity.exe -batchmode … -executeMethod`) | 创建/打开项目，构建，测试，场景构建 | 高 |
| **文件/JSON层** | `projects-v1.json`，`user-settings.json`，`manifest.json`，`ProjectVersion.txt` | 高 |
| **日志层** | `Editor.log`，Hub日志，NUnit XML， `[MCP_RESULT]` 标记 | 高 |
| **发布 API** | 版本 → 变更集 + 深链接 | 高（在线） |
| **GUI 自动化 / 深链接 / 截图** | GUI-only 流程（登录，序列激活） | 尽力而为 |
| **Blender / free-tex-packer / Figma / Krita** | 无头资产创建 | 高（如果安装） |
代码中考虑的特殊情况（摘录）：
- Unity Hub 是 **GUI 子系统 Electron 二进制** → 仅通过真正的管道输出；无害的Chromium/GPU stderr噪音被过滤。
- **Unity 6 Batchmode 回归**：而不是 `EditorApplication.Exit()`，而是 `Environment.ExitCode` + `-quit`，主要从结果文件 + 看门狗（否则僵尸编辑器）。
- 考虑到Unity 6的重命名（`Rigidbody.drag → linearDamping`，`PhysicMaterial → PhysicsMaterial`，URP `_BaseColor`/`_Smoothness`，`FindObjectsByType`）。
- EEVEE 在Windows上无头渲染 **不会** → Blender 渲染/烘焙使用 **CYCLES**。
更多详情： **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**。
---
## 安装
### 要求
- Windows 10/11
- [Unity Hub](https://unity.com/download) （标准：`C:\Program Files\Unity Hub\Unity Hub.exe`）
- 至少通过Hub安装一个Unity编辑器
- [`uv`](https://docs.astral.sh/uv/) （推荐） **或** Python ≥ 3.10
- *可选用于资产工具：* Blender，Krita，Figma账户（令牌）
### 快速入门
```powershell
git clone https://github.com/MauricePutinas/Unity-MCP-Claude-Code.git
cd Unity-MCP-Claude-Code
uv sync # 创建.venv并安装依赖项
uv run python scripts\test_smoke.py # 功能测试 → "SMOKE TEST OK"
```
可选配置：复制`config.example.json` → `config.json`并调整`allowed_roots`。如果没有文件，将自动检测所有内容；写入权限仅限于默认项目文件夹，Hub应用数据和服务器数据区域。详细： **[docs/INSTALL.md](docs/INSTALL.md)**。
---
## Claude集成
### Claude Desktop — 1-Click扩展（推荐）
成品捆绑包： **[`dist/unity-hub-mcp.mcpb`](dist/unity-hub-mcp.mcpb)**。
Claude Desktop → **设置 → 扩展 → “安装扩展”** → 选择`.mcpb` → 设置“允许的项目文件夹” → 启用。 `uv` 必须在PATH中。
新构建捆绑包：
```powershell
npx -y @anthropic-ai/mcpb@latest pack dist\mcpb dist\unity-hub-mcp.mcpb
```
### Claude Code（CLI/IDE）
```powershell
claude mcp add --scope user --transport stdio unity-control -- uv --directory "C:\Path\To\Unity-MCP-Claude-Code" run python -m unity_hub_mcp
```
或在项目范围内创建一个`.mcp.json`文件，参见 [`claude_code.mcp.example.json`](claude_code.mcp.example.json)。
使用`claude mcp list`或会话中的`/mcp`进行检查。
### Claude Desktop（手动）
填充`%APPDATA%\Claude\claude_desktop_config.json`文件，参见 [`claude_desktop_config.example.json`](claude_desktop_config.example.json），并 **完全重启** Claude Desktop。
---
## 安全
- **确认门**：修改/破坏性工具需要`confirm=true`；如果没有确认，只会进行**预览**（Dry-Run特性）。
- **路径沙盒**：文件写入/删除工具仅在**允许的根目录** (`allowed_roots`) 内有效，阻止遍历（`..`）。
- **自动备份**：在JSON/资产更改（`list_backups` / `restore_backup`）之前。
- **审计日志**：每项操作都会 **编辑** 并写入`actions.jsonl` — 参数 **和** 结果通过编辑（令牌/机密/许可权益被隐藏）。
- **敏感的Hub文件** （`encryptedTokens.json`，`userInfoKey.json`，`Local State`，`Preferences`） **主动拒绝** 读取路径 — 从不输出或记录。
- **代码中没有机密**：`FIGMA_TOKEN`仅来自环境/参数，没有硬编码或持久化。
> **强大的工具的诚实提示**：`run_editor_method`和`blender_run_python` **有意执行任意代码** （这是他们的目的）。一些Hub/许可证/恢复工具（例如`set_default_project_dir`，`apply_license_file`，`restore_backup`，`import_external_asset`）通过`confirm=true`确保安全，但影响`allowed_roots`沙盒。仅在可信的本地环境中运行服务器。
---
## 项目结构
```
unity_hub_mcp/ # MCP服务器（服务器.py中的工具注册）
├─ core.py # 进程运行器，日志记录/编辑，备份，路径安全
├─ settings.py # 路径解析（Env → config.json → 自动检测）
├─ csharp_templates.py # 注入的C#自动化脚本（场景构建等）
├─ scene_builder.py / authoring.py / editor_cli.py / hub_cli.py / projects.py …
├─ blender.py / texpacker.py / figma.py / krita.py / textures.py # 资产创建
└─ gui.py / process.py / logs.py / releases.py / deeplinks.py
scripts/ # 烟雾/实时测试 + 演示管道
docs/ # TOOLS.md · ARCHITECTURE.md · INSTALL.md
dist/ # mcpb/manifest.json + 构建的unity-hub-mcp.mcpb
```
---
## 开发和测试
```powershell
uv sync
uv run python scripts\test_smoke.py # 基于文件的快速 → "SMOKE TEST OK"
uv run python scripts\test_live.py # Hub CLI + 发布 API（只读）
uv run python scripts\demo_make_game.py # 构建一个完整的迷你游戏 → .exe
```
服务器仅 **stderr** 日志记录（stdout保留给MCP协议）。自己的日志和审计日志位于 `%LOCALAPPDATA%\unity-hub-mcp\`。
---
## 许可证
[MIT](LICENSE) © 2026 Maurice Putinas
*Unity，Unity Hub和Unity徽标是Unity Technologies的商标。该项目是一个独立的自动化工具，与Unity Technologies无关。*
