Skip to content

Commit bbcdb61

Browse files
laiyangli001laiyangli001
committed
feat: 新增 Unity MCP 服务和配置文档
1 parent b7042d1 commit bbcdb61

111 files changed

Lines changed: 10564 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/unity-mcp-setup-sop.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# SOP: Unity MCP Bridge 从零配置
2+
3+
**版本：** 1.0
4+
**更新日期：** 2026-06-02
5+
**负责人：** 开发人员
6+
**适用对象：** 需要让 Claude Code 控制 Unity 编辑器的开发者
7+
8+
---
9+
10+
## 1. 目的
11+
12+
配置 Unity MCP Bridge，让 Claude Code 可以通过自然语言直接控制 Unity 编辑器（操作场景对象、组件、检查编译错误、运行测试等）。
13+
14+
## 2. 谁来做
15+
16+
Unity 开发者，熟悉 VS Code + Claude Code 环境。
17+
18+
## 3. 需要的工具
19+
20+
- VS Code（安装了 Claude Code 扩展）
21+
- Unity 2021.3 或更新版本
22+
- Node.js 16+
23+
- Git
24+
25+
## 4. 开始前的准备
26+
27+
开始前确认以下条件：
28+
29+
- [ ] Claude Code 可以在 VS Code 中正常使用
30+
- [ ] `node --version` 返回 v16+
31+
- [ ] `npm --version` 返回正常版本号
32+
- [ ] 有一个 Unity 项目可用来验证
33+
34+
---
35+
36+
## 5. 逐步操作指南
37+
38+
### 阶段一：全局安装 Node.js MCP Server（只需做一次）
39+
40+
> 这一步在你的开发机上做一次即可，以后所有 Unity 项目共用。
41+
42+
#### 步骤 1：克隆仓库
43+
44+
```cmd
45+
cd C:\Users\LaiYangLi\.claude\mcp-servers
46+
git clone https://github.com/aiacats/unity-mcp.git unity-mcp
47+
```
48+
49+
**预期结果：** `unity-mcp` 目录出现在 `mcp-servers/` 下
50+
51+
#### 步骤 2：安装 Node 依赖
52+
53+
```cmd
54+
cd unity-mcp/Packages/com.aiacats.unity-mcp/Server~
55+
npm install
56+
```
57+
58+
**预期结果：** 显示 `added X packages`，`node_modules` 目录创建成功
59+
60+
#### 步骤 3：注册到 Claude Code 全局配置
61+
62+
打开 `C:\Users\LaiYangLi\.claude.json`，在 `mcpServers` 中添加：
63+
64+
```json
65+
"claude-code-mcp-unity": {
66+
"command": "node",
67+
"args": [
68+
"c:/Users/LaiYangLi/.claude/mcp-servers/unity-mcp/Packages/com.aiacats.unity-mcp/Server~/index.js"
69+
],
70+
"env": {
71+
"MCP_UNITY_HTTP_URL": "http://localhost:8090"
72+
}
73+
}
74+
```
75+
76+
**预期结果：** `.claude.json` 的 `mcpServers` 中增加了一条 `claude-code-mcp-unity` 配置
77+
78+
#### 步骤 4：Reload 窗口
79+
80+
在 VS Code 中按 `Ctrl+Shift+P` → `Developer: Reload Window`
81+
82+
**预期结果：** 新 MCP 服务加载完成
83+
84+
---
85+
86+
### 阶段二：每个 Unity 项目安装 UPM 包（每个项目做一次）
87+
88+
#### 步骤 1：打开项目 manifest.json
89+
90+
进入 Unity 项目目录，打开 `Packages/manifest.json`。
91+
92+
#### 步骤 2：添加依赖
93+
94+
在 `dependencies` 中添加以下两行：
95+
96+
```json
97+
"com.aiacats.unity-mcp": "https://github.com/aiacats/unity-mcp.git?path=Packages/com.aiacats.unity-mcp",
98+
"org.khronos.unitygltf": "https://github.com/KhronosGroup/UnityGLTF.git",
99+
```
100+
101+
**预期结果：** `dependencies` 中新增两个包
102+
103+
#### 步骤 3：启动 Unity 编辑器
104+
105+
双击打开 Unity 项目。Unity 会自动从 Git 下载并解析这两个包。
106+
107+
**首次启动可能需要等待 1-3 分钟。**
108+
109+
#### 步骤 4：验证 UPM 包安装成功
110+
111+
打开 Unity 菜单 `Window > Package Manager`，在列表中找到：
112+
- `Claude Code MCP Unity`
113+
- `UnityGLTF`
114+
115+
**预期结果：** 两个包都在已安装列表中，无红色错误标记
116+
117+
#### 步骤 5：关闭自动安装（推荐）
118+
119+
在 Unity 菜单中点击：
120+
`Tools > Claude Code MCP > Setup: Toggle Auto Install on Editor Load`
121+
122+
点一次即可关闭。以后每次启动不再弹 `npm install` 错误。
123+
124+
> **为什么？** MCP server 已经安装在全局 `.claude` 下，Unity 不需要再装一份。这个开关只关掉 Unity 侧的自动安装，不影响功能。
125+
126+
---
127+
128+
### 阶段三：验证连接
129+
130+
#### 步骤 1：确认 Unity 编辑器在运行
131+
132+
Unity 编辑器必须打开且不在后台编译中。
133+
134+
#### 步骤 2：在 Claude Code 中测试
135+
136+
输入以下命令：
137+
138+
```
139+
检查 Unity 编译状态
140+
```
141+
142+
**预期结果：** 返回 `isCompiling: false`，`hasErrors: false`
143+
144+
也可以试：
145+
146+
```
147+
查找 Assets 下的所有 C# 脚本
148+
```
149+
150+
**预期结果：** 返回脚本列表
151+
152+
---
153+
154+
## 6. 验证清单
155+
156+
全部完成后确认：
157+
158+
- [ ] `claude-code-mcp-unity` 已注册到 `.claude.json`
159+
- [ ] `npm install` 在 `Server~/` 执行成功
160+
- [ ] Unity 项目 `manifest.json` 包含 unity-mcp 和 unitygltf
161+
- [ ] Unity 编辑器启动后无编译错误
162+
- [ ] `check_compilation_status` 返回成功
163+
- [ ] `find_assets` 能搜到文件
164+
165+
---
166+
167+
## 7. 常见问题
168+
169+
| 问题 | 原因 | 解决方法 |
170+
|------|------|---------|
171+
| `npm install` 报错 exit code 1 | Unity 侧 MCPAutoBootstrap 尝试在自己的 PackageCache 路径装依赖 | 关掉自动安装：Tools > Claude Code MCP > Toggle Auto Install |
172+
| `'ClearReference' does not exist` | unitygltf 需要 Visual Scripting >= 1.9 | 升级 Unity 到 6000.0+，或手动升级 Visual Scripting 包 |
173+
| `UnityGLTF namespace not found` | 项目中没装 unitygltf 包 | 在 manifest.json 添加 unitygltf 依赖 |
174+
| MCP 工具返回"连接失败" | Unity 编辑器不在运行，或 8090 端口被占用 | 确认 Unity 已打开，检查 8090 端口是否有其他程序 |
175+
| UPM 包解析后报黄字"Failed to resolve packages" | Git URL 无法访问（网络问题） | 检查科学上网，或改用本地路径安装 |
176+
177+
---
178+
179+
## 8. 备注
180+
181+
**关于 Unity 版本要求：**
182+
183+
| Unity 版本 | Visual Scripting 版本 | unitygltf 兼容 | 说明 |
184+
|-----------|----------------------|---------------|------|
185+
| 2022.3 LTS | 1.8.x | ❌ 无 ClearReference | 需要锁 unitygltf 早期版本或升 Unity |
186+
| 2023.2 | 1.8.x | ❌ 无 ClearReference | 同上 |
187+
| 6000.0+ | 1.9.x | ✅ 完全兼容 | 推荐 |
188+
189+
**关于全局配置的说明：**
190+
- `.claude.json` 是全局 MCP 配置，所有项目共用
191+
- Unity 端 UPM 包是项目级别的，每个 Unity 项目都要装一次
192+
- MCP server（Node.js）只需安装一次，UPM 包（C#）每个项目都要装
193+
194+
**关于自动安装开关：**
195+
- 关闭后 Unity 不会自动在 PackageCache 路径下跑 npm install
196+
- MCP 通信走全局 server → HTTP → Unity 8090 端口，不受开关影响
197+
198+
**关于 vs package安装：**
199+
- 也可以打开 Package Manager → `+` → `Add package from git URL...` 手动添加两个包
200+
- 但直接改 manifest.json 更快
201+
202+
---
203+
204+
## 9. 版本历史
205+
206+
| 版本 | 日期 | 作者 | 变更 |
207+
|------|------|------|------|
208+
| 1.0 | 2026-06-02 | Process Owner | 初始版本 |

‎mcp-servers/unity-mcp/.claude/settings.local.json‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(python3 -c \"import uuid; print\\(uuid.uuid4\\(\\).hex[:32]\\)\" 2>/dev/null || python -c \"import uuid; print\\(uuid.uuid4\\(\\).hex[:32]\\)\")",
5+
"Bash(python -c \"\nimport uuid\nfiles = ['Editor', 'package.json', 'CHANGELOG.md', 'LICENSE.md']\nfor f in files:\n guid = uuid.uuid4\\(\\).hex[:32]\n print\\(f'{f}: {guid}'\\)\n\")",
6+
"Bash(python -c \"import uuid; print\\(uuid.uuid4\\(\\).hex[:32]\\)\")",
7+
"Bash(find \"D:/_Personal/Project/unity-mcp/Packages/com.aiacats.unity-mcp\" -name \"*.cs\" -type f | xargs wc -l | sort -rn)",
8+
"Bash(find \"D:/_Personal/Project/unity-mcp/Packages/com.aiacats.unity-mcp\" -name \"*.cs\" -type f | xargs grep -l \"class\\\\|struct\\\\|interface\" | sort)",
9+
"Bash(grep -n \"namespace\" \"D:/_Personal/Project/unity-mcp/Packages/com.aiacats.unity-mcp/Editor/\"*.cs)",
10+
"Bash(cd \"D:/_Personal/Project/unity-mcp/Packages/com.aiacats.unity-mcp\" && rm Editor/Core/MCPUnityServer.cs && rm Editor/Core/MCPUnityServerTest.cs && rm Editor/TestCubeCreator.cs && mv Editor/ClaudeCodeMCPWindow.cs Editor/UI/ && mv Editor/ClaudeCodeMCPStatusBar.cs Editor/UI/ && echo \"Done\")",
11+
"Bash(cd \"D:/_Personal/Project/unity-mcp/Packages/com.aiacats.unity-mcp\" && rm Editor/Core/MCPUnityServer.cs.meta Editor/Core/MCPUnityServerTest.cs.meta Editor/TestCubeCreator.cs.meta && mv Editor/ClaudeCodeMCPWindow.cs.meta Editor/UI/ && mv Editor/ClaudeCodeMCPStatusBar.cs.meta Editor/UI/ && echo \"Done\")",
12+
"Bash(python -c \"\nimport uuid\nfiles = [\n 'Editor/UI',\n 'Editor/Core/Handlers',\n 'Editor/Core/MCPHttpServer.cs',\n 'Editor/Core/Handlers/IMCPHandler.cs',\n 'Editor/Core/Handlers/HandlerBase.cs',\n 'Editor/Core/Handlers/GameObjectHandler.cs',\n 'Editor/Core/Handlers/ComponentHandler.cs',\n 'Editor/Core/Handlers/SceneHandler.cs',\n 'Editor/Core/Handlers/CompilationHandler.cs',\n 'Editor/Core/Handlers/ConsoleHandler.cs',\n 'Editor/Core/Handlers/EditorHandler.cs',\n]\nfor f in files:\n guid = uuid.uuid4\\(\\).hex[:32]\n print\\(f'{f}|{guid}'\\)\n\")",
13+
"Bash(curl -s http://localhost:8090/mcp/ping 2>&1)",
14+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/hot_reload -H \"Content-Type: application/json\" -d '{\"saveAssets\": true, \"optimized\": true}' 2>&1)",
15+
"Bash(sleep 5 && curl -s -X POST http://localhost:8090/mcp/tools/check_compilation_status -H \"Content-Type: application/json\" -d '{}' 2>&1)",
16+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/force_compilation -H \"Content-Type: application/json\" -d '{\"forceUpdate\": true}' 2>&1)",
17+
"Bash(sleep 10 && curl -s -X POST http://localhost:8090/mcp/tools/check_compilation_status -H \"Content-Type: application/json\" -d '{}' 2>&1)",
18+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/get_compilation_errors -H \"Content-Type: application/json\" -d '{}' 2>&1)",
19+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/get_console_logs -H \"Content-Type: application/json\" -d '{\"limit\": 20, \"includeStackTrace\": false}' 2>&1)",
20+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/update_gameobject -H \"Content-Type: application/json\" -d '{\"objectPath\": \"MCP_TestCube\", \"gameObjectData\": {\"name\": \"MCP_TestCube\"}}' 2>&1)",
21+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/get_gameobject_info -H \"Content-Type: application/json\" -d '{\"objectPath\": \"MCP_TestCube\"}' 2>&1)",
22+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/select_gameobject -H \"Content-Type: application/json\" -d '{\"objectPath\": \"MCP_TestCube\"}' 2>&1)",
23+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/update_component -H \"Content-Type: application/json\" -d '{\"objectPath\": \"MCP_TestCube\", \"componentName\": \"Rigidbody\", \"componentData\": {\"mass\": 5.0}}' 2>&1)",
24+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/get_component_properties -H \"Content-Type: application/json\" -d '{\"objectPath\": \"MCP_TestCube\", \"componentName\": \"Rigidbody\"}' 2>&1)",
25+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/remove_component -H \"Content-Type: application/json\" -d '{\"objectPath\": \"MCP_TestCube\", \"componentName\": \"Rigidbody\"}' 2>&1)",
26+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/play_mode_control -H \"Content-Type: application/json\" -d '{\"action\": \"status\"}' 2>&1)",
27+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/send_console_log -H \"Content-Type: application/json\" -d '{\"message\": \"Verification test from Claude Code\", \"type\": \"info\"}' 2>&1)",
28+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/find_assets -H \"Content-Type: application/json\" -d '{\"type\": \"Scene\", \"limit\": 5}' 2>&1)",
29+
"Bash(curl -s -X POST http://localhost:8090/mcp/tools/save_scene -H \"Content-Type: application/json\" -d '{}' 2>&1)",
30+
"Bash(curl -s http://localhost:8090/mcp/resources/scenes_hierarchy 2>&1)",
31+
"Bash(sleep 3 && curl -s http://localhost:8090/mcp/resources/scenes_hierarchy 2>&1)",
32+
"Bash(curl -s -m 10 http://localhost:8090/mcp/ping 2>&1)",
33+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/resources/scenes_hierarchy -H \"Content-Type: application/json\" -d '{}' 2>&1)",
34+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/tools/check_compilation_status -H \"Content-Type: application/json\" -d '{}' 2>&1)",
35+
"Bash(curl -s -m 15 -X POST http://localhost:8090/mcp/tools/hot_reload -H \"Content-Type: application/json\" -d '{\"saveAssets\": true, \"optimized\": true}' 2>&1)",
36+
"Bash(sleep 10 && curl -s -m 10 -X POST http://localhost:8090/mcp/tools/get_compilation_errors -H \"Content-Type: application/json\" -d '{}' 2>&1)",
37+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/tools/save_scene -H \"Content-Type: application/json\" -d '{}' 2>&1)",
38+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/tools/execute_menu_item -H \"Content-Type: application/json\" -d '{\"menuPath\": \"Window/General/Console\"}' 2>&1)",
39+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/tools/run_tests -H \"Content-Type: application/json\" -d '{\"queryOnly\": true}' 2>&1)",
40+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/tools/delete_gameobject -H \"Content-Type: application/json\" -d '{\"objectPath\": \"MCP_TestCube\"}' 2>&1)",
41+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/tools/screenshot -H \"Content-Type: application/json\" -d '{}' 2>&1)",
42+
"Bash(curl -s -m 10 -X POST http://localhost:8090/mcp/tools/create_material -H \"Content-Type: application/json\" -d '{\"name\": \"MCP_TestMaterial\", \"shader\": \"Standard\", \"color\": {\"r\": 1, \"g\": 0, \"b\": 0, \"a\": 1}}' 2>&1)",
43+
"Bash(cd \"D:\\\\_Personal\\\\Project\\\\unity-mcp\" && rm -rf Assets/Screenshots Assets/MCP_TestMaterial.mat Assets/MCP_TestMaterial.mat.meta Assets/Screenshots.meta 2>&1)",
44+
"Skill(update-config)",
45+
"Edit(.claude/claudeLog.txt)",
46+
"Write(.claude/claudeLog.txt)"
47+
]
48+
}
49+
}

‎mcp-servers/unity-mcp/.gitignore‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Unity
2+
[Ll]ibrary/
3+
[Tt]emp/
4+
[Oo]bj/
5+
[Bb]uild/
6+
[Bb]uilds/
7+
[Ll]ogs/
8+
[Uu]ser[Ss]ettings/
9+
10+
# Node.js
11+
**/node_modules/
12+
npm-debug.log*
13+
yarn-debug.log*
14+
yarn-error.log*
15+
16+
# IDE
17+
.idea/
18+
.vs/
19+
.vscode/
20+
*.csproj
21+
*.sln
22+
*.suo
23+
*.user
24+
*.pidb
25+
*.userprefs
26+
27+
# OS
28+
.DS_Store
29+
Thumbs.db
30+
*.swp
31+
*~
32+
!Packages/**/Server~/
33+
!Packages/**/Samples~/
34+
!Packages/**/Templates~/
35+
36+
# Unity package lock (auto-generated)
37+
Packages/packages-lock.json
38+
39+
# Build output
40+
*.dll
41+
*.pdb

0 commit comments

Comments
 (0)