CoplayDev/unity-mcp · 上手攻略

• 仓库：CoplayDev/unity-mcp
• 链接：https://github.com/CoplayDev/unity-mcp
• 分类：ai · skill · game-dev · unity
• 作者：Jay
• 更新：2026-07-05

这是什么

unity-mcp（MCP for Unity）是一个基于 Model Context Protocol（MCP）的 Unity 编辑器桥接工具，让 AI 助手（Claude、Codex、Cursor、VS Code 等 MCP 兼容客户端）能够直接操控 Unity Editor——创建场景和 GameObject、编写 C# 脚本、管理资产、运行测试、构建项目等。

本质上是给 Unity Editor 装了一个「AI 遥控器」，用自然语言就能驱动编辑器干活。最新版本 v10.0.0（2026-06-30），已获得 ACM SIGGRAPH 2025 学术论文引用。

解决什么问题

• Unity 脚本编写依赖手动查找文档和 API，开发节奏容易被打断
• 重复性编辑器任务（批量处理资产、场景验证、测试运行）耗时
• 想用 LLM 的代码生成能力，但又不想自己搭 MCP Server
• 多人协作时，希望 AI 助手能够感知和操作真实的 Unity 项目状态

快速安装

前提条件

• Unity：2021.3 LTS 及以上（最高兼容 Unity 6.x）
• Python：3.10+（推荐通过 uv 安装）
• MCP 客户端：Claude Desktop / Claude Code / Cursor / VS Code / Windsurf / Cline / Gemini CLI / Codex 等任意 MCP 兼容客户端

Step 1：安装 Unity Package

在 Unity 编辑器中： 1. 菜单 → Window → Package Manager 2. 点左上角 + → Add package from git URL 3. 输入（推荐锁定版本）： https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.0.0

或者使用 UPM（OpenUPM）：

openupm add com.coplaydev.unity-mcp

⚠️ 建议锁定 #v10.0.0 而非 #main，因为 beta 分支 API 可能不稳定。

Step 2：安装 Python MCP Server

# 推荐使用 uv（高性能 Python 包管理）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装 MCP Server（会自动安装依赖）
uv tool install mcp-server-unity

# 验证安装
mcp-server-unity --version

Step 3：配置 MCP 客户端

在 Unity 编辑器中： - 菜单 → Window → MCP for Unity → Configure All Detected Clients

工具会自动检测你安装的 MCP 客户端并写入对应配置文件。以 Claude Desktop 为例，配置后 claude_desktop_config.json 会包含类似以下内容：

{
  "mcpServers": {
    "unity": {
      "command": "mcp-server-unity",
      "args": ["--project", "/path/to/your/unity/project"]
    }
  }
}

Step 4：验证连接

在 Unity 中打开项目，然后对 AI 助手说：

「在原点创建一个红色立方体，并添加 Rigidbody 组件。」

AI 会通过 MCP 调用 Unity Editor，在场景中生成该对象。查看 Unity Console 确认无报错即连接成功。

核心工具一览

MCP for Unity 提供 47 个 MCP 工具入口，按功能分为：

场景与对象管理

• manage_scene：加载/保存/新建场景
• manage_gameobject：创建/删除/查找 GameObject
• create_simple_object：快速创建基础几何体
• manage_transform：操控位置/旋转/缩放

脚本管理

• manage_script：创建/编辑/删除 C# 脚本
• roslyn_validate：用 Roslyn 做语法验证（v10 新增）

资产与资源

• manage_material：创建和配置材质
• manage_physics：物理组件管理
• manage_audio：音频资产管理
• manage_prefab：预制件操作

测试与构建

• run_tests：执行 Unity Test Framework 测试
• build_player：构建播放器

编辑器状态

• editor_state：查询编辑器当前状态
• project_info：项目信息
• unity_instances：多实例路由

完整工具目录见：https://coplaydev.github.io/unity-mcp/reference/tools/

多实例路由（高级）

v10 支持同时控制多个 Unity 编辑器实例。通过 set_active_instance 切换目标项目，适合需要同时操作多个游戏关卡或同时驱动多个项目 AI agent 的场景。

文档：https://coplaydev.github.io/unity-mcp/guides/multi-instance

两种传输模式

v10 起 HTTP 成为默认传输方式，功能更现代。

典型使用场景

自然语言原型开发

用一句话让 AI 创建场景：「做一个第一人称射击游戏的基础场景，包含地面、一个玩家出生点和三个敌人目标。」AI 会自动生成对应 GameObject、脚本和配置。

C# 脚本生成与重构

让 AI 读取现有脚本并提出改进建议，或生成新功能脚本（如「写一个渐变色切换的 UI 动画系统」）。Roslyn 验证确保语法正确。

批量资产处理

AI 批量修改材质参数、批量处理导入的图片纹理设置、批量创建预制件变体。

自动化测试

用 run_tests 让 AI 执行 Unity Test Framework 测试套件，读取测试结果并给出修复建议。

游戏设计探索

非程序员主策/设计师可以通过自然语言快速搭建游戏原型，验证设计思路是否可行，降低试错成本。

坑与注意

1. 非 Unity 官方产品：明确声明与 Unity Technologies 无关联，不能期待与 Unity 官方工具同等质量和稳定性。

2. Python 环境依赖：必须安装 Python 3.10+，推荐用 uv 安装管理，否则 MCP Server 可能找不到正确的 Python 路径。

3. beta 分支开发中：活跃功能开发在 beta 分支进行，main 分支可能落后。提交 Issue 时建议注明分支版本。

4. C# 脚本需要手动挂载：AI 生成的脚本不会自动挂到 GameObject 上，仍需手动拖拽或在 Unity Inspector 中关联。

5. 大型项目性能：Unity 项目越大，project_info 和场景扫描类工具响应越慢，这是 Editor API 本身的限制。

6. Roslyn 验证仅语法层：Roslyn 验证只检查 C# 语法正确性，不检查运行时逻辑错误（如空引用、类型不匹配）。

7. 移动平台构建需额外配置：Unity 移动平台构建涉及 SDK 配置，MCP 目前聚焦编辑器操作，移动构建仍需手动处理。

8. 安全合规：不要让 AI 助手在不受信任的对话中操作真实项目，恶意指令（如删除资产）理论上可以通过 MCP 执行。

与同类对比

MCP for Unity 是目前最完整的 MCP + Unity 集成方案，支持工具数量和客户端覆盖都远超其他方案，且 MIT 免费。对比其他方案，它不需要写自定义 API 封装，开箱即用。

一句话结论

unity-mcp 让 AI 助手通过自然语言操控 Unity Editor，47 个 MCP 工具覆盖场景/脚本/资产/测试，v10.0.0 用 HTTP 传输支持多 agent 并行，适合想用 LLM 加速 Unity 原型开发和小团队工作流的开发者；安装只需 Unity Package + Python Server 两步，beta 分支 API 稳定性略低于 release 版。

Sources: GitHub README (https://github.com/CoplayDev/unity-mcp), Getting Started (https://coplaydev.github.io/unity-mcp/getting-started), v10.0.0 Release Notes (https://github.com/CoplayDev/unity-mcp/releases/tag/v10.0.0), 2026-07-05