IvanMurzak/Unity-MCP · 上手攻略

  • 仓库：IvanMurzak/Unity-MCP
  • 链接：https://github.com/IvanMurzak/Unity-MCP
  • 分类：AI 开发工具 / Unity 集成 / MCP
  • 作者：Tom
  • 更新：2026-07-28

这是什么

Unity-MCP（Unity Model Context Protocol）是一个将 Unity Editor 和 Runtime 接入 AI Agent（MCP 协议）的插件生态。装好后，AI Agent（如 Claude Code、Cursor、Copilot）能直接操作 Unity 场景、创建 GameObject、读写脚本、运行测试、截屏返回画面，实现「用自然语言开发游戏」。

核心组件分为三层：

组件 作用
Unity-MCP 插件（com.ivanmurzak.unity.mcp） 装入 Unity 项目，暴露 Editor/Runtime 的 MCP 接口
unity-mcp-cli（Node.js 全局工具） 创建项目、安装插件、配置 MCP、启动 Unity
GameDev-MCP-Server（二进制） MCP 服务端，负责 AI ↔ Unity 的 JSON-RPC 通信

⚠️ 另一条路线是直接用 unity-mcp-cli install-plugin 搭配云端认证，跳过手动配置 MCP JSON，推荐新手用这条路线。

解决什么问题

在 Unity 中开发时，重复性工作极多：手动建 GameObject、挂组件、改材质、调场景、跑测试。Unity-MCP 让 AI Agent 帮你做这些，典型场景包括：

  • 批量创建/修改场景对象：说「创建 3 个 Cube 围成圆形」→ AI 直接操作场景
  • 自动化测试：直接让 AI 运行 EditMode / PlayMode 测试并获取结果
  • 代码生成：AI 读写 C# 脚本文件，用 Roslyn 动态执行片段
  • 运行时 AI（Runtime）：在编译好的游戏里接入 LLM 做 NPC 对话或 AI 调试
  • 资产与包管理：搜索、安装、卸载 UPM 包

与 Unity 官方 AI 工具的区别：Unity 官方的 IoT、Sentis 等偏向嵌入式模型推理；Unity-MCP 偏向「让 AI Agent 控制 Editor」，是开发工作流工具而非运行时 AI 能力。

快速安装

方式一：CLI 自动化（推荐，3 步完成）

# 1. 安装 CLI（需要 Node.js ^20.19.0 或 >=22.12.0）
npm install -g unity-mcp-cli

# 2. 把插件装进 Unity 项目
unity-mcp-cli install-plugin ./MyUnityProject

# 3. 云端登录（OAuth 设备流，跳出浏览器授权）
unity-mcp-cli login

# 4. 启动 Unity 并自动连接 MCP
unity-mcp-cli open ./MyUnityProject

云端登录后，AI Agent 通过 https://ai-game.dev/mcp/p/ 连接，无需手动配 MCP JSON。团队可用 unity-mcp-cli install-plugin --enroll <code> 分发接入权限。

方式二：手动 .unitypackage 安装

  1. 从 Releases 页面 下载 AI-Game-Dev-Installer.unitypackage
  2. 双击或在 Unity 中 Assets → Import Package → Custom Package 导入
  3. 重启 Unity Editor

方式三：OpenUPM（适合包管理党）

# 需要先安装 openupm-cli
openupm add com.ivanmurzak.unity.mcp

⚠️ 重要限制：项目路径不能包含空格。 - ✅ C:/MyProjects/MyProject - ❌ C:/My Projects/MyProject - ❌ C:/MyProjects/My Project

核心用法

连接 AI Agent（以 Claude Code 为例）

第一步：在 Unity 中打开 Window → AI Game Developer，点击 Auto-generate Skills，会自动写入 Claude Code 的 MCP 配置。

第二步：在终端启动 Claude Code：

claude code

第三步：直接用自然语言下达指令：

创建 3 个 Cube，围成半径为 2 的圆
给它们都加上 Collider 和 Rigidbody
运行一下看效果

unity-mcp-cli 常用命令

# 查看 MCP 连接状态
unity-mcp-cli status ./MyUnityProject

# 配置启用哪些工具（默认全部开启）
unity-mcp-cli configure ./MyUnityProject \
  --enable-tools gameobject-create,gameobject-find \
  --disable-tools profiler-start,profiler-stop

# 手动触发技能文件生成
unity-mcp-cli setup-skills claude-code ./MyUnityProject

# 直接在命令行执行某个 MCP 工具
unity-mcp-cli run-tool gameobject-find ./MyUnityProject \
  --input '{"query":"Player"}'

# 等待 Unity Editor 启动完成（自动化脚本用）
unity-mcp-cli wait-for-ready ./MyUnityProject

# 关闭 Unity Editor（优雅退出）
unity-mcp-cli close ./MyUnityProject --timeout 60 --force

内置 MCP 工具一览（70+ 个，分 4 大类）

资产与场景： - assets-find / assets-copy / assets-move / assets-delete — 搜索和操作项目资产 - assets-material-create — 创建材质 - assets-prefab-create / assets-prefab-instantiate — Prefab 创建与实例化 - scene-create / scene-open / scene-save — 场景管理 - package-add / package-remove / package-list — UPM 包管理

GameObject 与组件： - gameobject-create / gameobject-destroy / gameobject-duplicate — 增删复制 - gameobject-find — 按名称/标签/类型查找 - gameobject-component-add / gameobject-component-modify — 组件操作

脚本与反射： - script-update-or-create — 读写 C# 脚本文件 - script-execute — 用 Roslyn 动态编译执行 C# 代码片段 - reflection-method-find / reflection-method-call — 查找并调用任意 C# 方法（含私有方法） - type-get-json-schema — 生成 C# 类型的 JSON Schema

编辑器状态与调试： - tests-run — 运行 EditMode / PlayMode 测试 - console-get-logs / console-clear-logs — 读取/清空控制台 - editor-application-set-state — 控制播放/暂停 - screenshot-game-view / screenshot-scene-view — 截图返回给 AI 看 - profiler-* 系列 — 获取 FPS、内存、渲染帧信息

典型使用场景

场景 1：批量搭建场景

让 AI 快速生成一组测试对象，无需手动点选菜单：

「在场景里创建一个地板平面，10 个不同颜色的球随机散落其上」

场景 2：自动生成脚本

AI 可以直接写入或修改 .cs 文件，结合 script-execute 可以立即验证代码是否正确编译。

场景 3：AI 驱动调试

在 PlayMode 下，AI 可以调用 console-get-logs 查看错误日志，定位问题后修改组件字段。

场景 4：自动化冒烟测试

unity-mcp-cli open ./MyGame
unity-mcp-cli wait-for-ready ./MyGame
unity-mcp-cli run-tool tests-run ./MyGame --input '{"testMode":"EditMode"}'
unity-mcp-cli close ./MyGame

场景 5：Runtime AI（进阶）

Unity-MCP Server 可以跑在游戏运行时内，通过 reflection-method-call 让 LLM 直接查询/修改游戏对象，实现 NPC 智能对话或游戏内 AI 辅助。

坑与注意

  1. 项目路径禁空格：空格会导致 MCP Server 启动失败。务必用无空格路径。
  2. macOS 无障碍权限：unity-mcp-cli open 在 macOS 上需要给终端加「辅助功能」权限才能自动点击 Unity 的「安全模式」弹窗（System Settings → Privacy & Security → Accessibility）。
  3. Linux Wayland 不支持：--no-auto-dismiss-launch-errors 在 Wayland 下无法自动关闭报错弹窗，需改用 X11 或加 --no-auto-dismiss-launch-errors 并手动处理。
  4. Windows Headless CI：Unity 以 Windows Service（Session 0）启动时，unity-mcp-cli close 的优雅退出（WM_CLOSE）会静默失效，需加 --force 杀掉进程。
  5. 登录凭证位置：默认存在 ~/.ai-game-dev/credentials.json，是 OAuth device flow 产生的云端令牌，无需手动创建 PAT。
  6. 云端 pinning：默认 MCP 配置指向 per-project 的云端 pinned endpoint（https://ai-game.dev/mcp/p/<pin>），加了 --no-pin 才用共享端点，团队分发时注意这点。
  7. 非交互终端：CI 环境中 CLI 会自动关闭 spinner 和颜色输出。

与同类对比

工具 定位 AI 控制方式 运行时支持 工具数量
Unity-MCP AI Agent 控制 Unity Editor MCP 协议，70+ 工具 ✅ Runtime 70+
Unity Sentis 嵌入式推理模型 非 Agent ✅ N/A
Unity IoT 外部设备集成 非 Agent ❌ N/A
Editor Console Pro（扩展） 人工调试辅助 无 ❌ N/A

Unity-MCP 的核心优势是开放生态：任何支持 MCP 的 AI Agent（Claude Code、Cursor、Copilot、Gemini 等）都可以接入，不绑死在某一家。

一句话结论

Unity-MCP 让 AI Agent 用 MCP 协议直接操控 Unity Editor 场景、脚本和测试，3 步安装后用自然语言开发游戏，是目前最成熟的 Unity AI 工作流工具。