【Unity MCP 环境搭建指南】


■ 概述

本文档记录了如何使用 Unity MCP (IvanMurzak/Unity-MCP) v0.76.1 搭建 Unity 项目的 AI 辅助开发环境。适用于手机端微信小游戏 / 抖音小游戏开发。


■ 架构

Claude Code (HTTP MCP 客户端)
↓ HTTP 请求
unity-mcp-server.exe (SignalR Hub, 端口 24754)
↓ StreamableHttp
Unity Editor Plugin (com.ivanmurzak.unity.mcp)


■ 搭建步骤


· 1. 安装 Unity MCP 包

在 Packages/manifest.json 中添加：

{
"scopedRegistries": [
{
"name": "OpenUPM",
"url": "https://package.openupm.com",
"scopes": ["com.ivanmurzak.unity.mcp", "...NuGet依赖..."]
}
],
"dependencies": {
"com.ivanmurzak.unity.mcp": "0.76.1"
}
}


· 2. 下载 Server 二进制

从 GitHub Releases 下载 unity-mcp-server.exe（约 101MB），放入项目 Library/mcp-server/win-x64/ 目录。


· 3. 配置连接模式

编辑 UserSettings/AI-Game-Developer-Config.json：

{
"connectionMode": "Custom",
"host": "http://localhost:24754",
"keepServerRunning": true,
"transportMethod": "streamableHttp",
"generateSkillFiles": true
}

连接模式说明：
- Cloud：通过 ai-game.dev 云端中转 → 国内网络可能 SSL 失败
- Custom：本地直连 → 推荐，速度快且无网络问题


· 4. 配置 Claude Code MCP

在 C:\Users\Administrator\.claude.json 中添加：

{
"mcpServers": {
"ai-game-developer": {
"type": "http",
"url": "http://localhost:24754/mcp"
}
}
}


· 5. 启用 Skills 和 Tools

在 AI-Game-Developer-Config.json 中：
- 启用全部 46 个 Prompts
- 启用 57+ 个 Tools（共 75 个可用）
- 设置 generateSkillFiles: true 自动生成 SKILL.md

运行 unity-skill-generate 后，.claude/skills/ 目录生成 77 个 SKILL.md。


■ 常用端口

端口 用途
24754 Unity MCP Server HTTP


■ 常见问题


· SSL 证书验证失败
症状：Curl error 35，Unity Plugin 无法连接云端。
解决：切换到 Custom 模式，使用本地 server。


· Material 不生效
症状：修改 Material 后面板显示还是白/灰色。
原因：Scene 缺少 Directional Light，Standard Shader 在无光环境下显示黑色。
解决：添加 Directional Light（强度 1.5，旋转 50/-30/0）。


· Reflector 路径语法
- 使用属性名 color 而非序列化名 m_Color
- 使用属性 sharedMaterial 而非 material（避免运行时实例化警告）
- 路径分隔符用 /，数组索引用 [i]


■ 版本记录

- 2026-05-29：从 v0.48.1 升级到 v0.76.1
- 2026-05-30：完成全量 Skills 生成（77 个）