CoderGamester/mcp-unity · 上手攻略

仓库：CoderGamester/mcp-unity
链接：https://github.com/CoderGamester/mcp-unity
分类：MCP · Unity · AI 开发工具
作者：Tom
更新：2026-08-21

这是什么

mcp-unity 是 Model Context Protocol（MCP）在 Unity 编辑器中的实现，通过 Node.js 服务器桥接 AI 编程助手（Cursor、Claude Code、Windsurf、Codex CLI 等）与 Unity Editor。项目提供 30+ 工具函数，涵盖场景操作、GameObject 增删改查、材质管理、包管理、测试运行、播放控制等，使 AI 助手能够直接操控 Unity 项目而无需手动配置。

解决的问题：Unity 项目的 AI 辅助编程长期受限于 AI 对 Unity 特定概念（GameObject、Prefab、Scene、Inspector）缺乏原生理解，开发者需要手动写繁琐的接口调用；mcp-unity 将 Unity Editor API 封装为标准 MCP 工具，AI 助手可直接调用，大幅降低 AI+Unity 的集成门槛。

快速安装

前置要求

组件	版本要求
Unity Editor	Unity 6 或更高版本
Node.js	18.x 或更高
npm	9.x 或更高
AI 助手	Cursor / Windsurf / Claude Code / Codex CLI 等

Step 1：安装 Unity Package

打开 Unity Editor
菜单栏：Window > Package Manager
点击左上角 + → Add package from git URL...
输入：https://github.com/CoderGamester/mcp-unity.git
点击 Add 等待安装完成

Step 2：配置 AI 助手

方式一：通过 Unity Editor 自动配置（推荐）

打开 Tools > MCP Unity > Server Window
选择 AI 客户端，点击 Configure（可选择全局配置或项目级配置 .mcp.json）
确认弹窗完成配置

方式二：手动配置

在各 AI 助手的 MCP 配置文件中添加：

// 以 Cursor 为例，~/.cursor/mcp.json 或项目 .mcp.json
{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": [
        "/path/to/mcp-unity/dist/index.js",
        "--project",
        "/path/to/your/unity/project"
      ]
    }
  }
}

⚠️ 注意：Unity 项目路径中包含空格在技术上是支持的，但建议优先使用无空格路径以避免潜在连接问题。

核心工具一览

场景与 GameObject 操作

工具名	功能
`get_scene_info`	获取当前场景信息（名称、路径、脏标记）
`create_scene`	创建新场景并保存到指定路径
`load_scene`	加载场景（支持叠加加载）
`delete_scene`	删除场景并从 Build Settings 移除
`save_scene`	保存当前场景（支持另存为）

# 示例 prompt（让 AI 助手执行）
# "Create a new scene called 'Level1' in the Scenes folder"
# "Load the MainMenu scene"
# "Save the current scene as 'Assets/Scenes/Level2.unity'"

GameObject 管理（增删改查）

工具名	功能
`get_gameobject`	获取 GameObject 详细信息（含所有组件）
`select_gameobject`	在 Hierarchy 中选中 GameObject
`update_gameobject`	更新 GameObject 属性（名称/tag/layer/active）
`create_prefab`	从脚本创建 Prefab（含 MonoBehaviour）
`delete_gameobject`	删除 GameObject
`duplicate_gameobject`	复制 GameObject（支持批量重命名）
`reparent_gameobject`	更改 GameObject 父子关系
`move_gameobject`	移动 GameObject（本地/世界坐标）
`rotate_gameobject`	旋转 GameObject（欧拉角或四元数）
`scale_gameobject`	缩放 GameObject
`set_transform`	一次性设置位置+旋转+缩放

# 示例 prompt
# "Set the Player object's tag to 'Enemy' and make it inactive"
# "Add a Rigidbody component to the Player object and set its mass to 5"
# "Create a prefab named 'Player' from the 'PlayerController' script"
# "Duplicate the Enemy prefab 5 times and rename them Enemy_1 through Enemy_5"
# "Set the Cube's position to (0, 5, 0), rotation to (0, 90, 0), and scale to (2, 2, 2)"

材质与资源

工具名	功能
`create_material`	创建新材质（指定 shader）
`assign_material`	为 GameObject 分配材质
`modify_material`	修改材质属性（颜色/金属度等）
`get_material_info`	获取材质完整信息
`add_asset_to_scene`	将 AssetDatabase 资源添加到场景

# 示例 prompt
# "Create a red material called 'EnemyMaterial' using the URP Lit shader"
# "Change the color of 'EnemyMaterial' to blue and set metallic to 0.8"

播放控制与测试

工具名	功能
`get_play_mode_status`	获取播放状态（isPlaying/isPaused）
`set_play_mode_status`	控制播放（play/pause/stop/step）
`run_tests`	运行 Unity Test Runner 测试
`get_console_logs`	获取 Unity 控制台日志（支持分页）
`send_console_log`	向 Unity 控制台发送日志

# 示例 prompt
# "Start Unity play mode"
# "Run all EditMode tests in my project"
# "Show me the last 20 error logs from the Unity console"

其他常用工具

工具名	功能
`execute_menu_item`	执行 Unity 菜单项
`add_package`	通过 Package Manager 安装包
`recompile_scripts`	触发脚本重新编译
`batch_execute`	批量执行多个操作（原子性，失败可回滚）

典型适用场景

批量资源处理：AI 批量创建/重命名/复制 GameObject，替代繁琐的手动操作
自动化测试：AI 触发 Test Runner 并解析结果日志
场景搭建辅助：AI 根据描述自动创建空场景、预设物体层级结构
Prefab 工厂：AI 批量生成同系列 Prefab 变体
材质自动化：AI 批量替换场景中材质，快速换肤
游戏逻辑原型：AI 直接操作 GameObject 属性，快速验证玩法概念

坑与注意

⚠️ 必须 Unity 6+：Unity 6 以下版本不支持 MCP Server 连接，升级前请确认项目兼容。

⚠️ Node.js 版本敏感：必须 18.x 及以上，低版本可能存在 ESM 模块兼容问题。

⚠️ 路径空格问题：虽然文档说支持空格路径，但遇到连接问题时优先尝试无空格路径。

⚠️ batch_execute 原子性：批量操作失败时可回滚，但回滚机制依赖操作的性质，某些破坏性操作（如 delete_gameobject）无法恢复。

⚠️ Play Mode 下限制：部分工具在 Play Mode 下行为与 Edit Mode 不同，详情参考 Unity 官方 Editor 脚本限制文档。

⚠️ 无 C# 代码生成：mcp-unity 专注于 Editor 操作和 GameObject 管理，不直接生成 C# 脚本逻辑，需配合 Cursor/Windsurf 的代码生成能力。

⚠️ VS Code 版本要求：Unity Dashboard 功能需 VS Code 1.109+。

与同类对比

方案	协议	Unity 版本	工具数量	AI 集成方式
mcp-unity	MCP	Unity 6+	30+	直接 MCP 工具调用
Unity CLS（官方）	JSON-RPC	Unity 2020+	~15	外部进程通信
unity-sml (VS Extension)	—	Unity 5+	~10	VS Code 插件
GitHub Copilot + Unity	—	通用	0（代码补全）	仅代码生成

核心差异：MCP Unity 是目前唯一基于标准 MCP 协议与 Unity Editor 深度集成的开源方案，与 AI 编程助手生态（Cursor/Windsurf/Claude Code）天然兼容，无需额外工作流配置。

一句话推荐结论

强烈推荐给需要在 Unity 项目中引入 AI 辅助的开发者，尤其是使用 Cursor/Windsurf 的团队；工具链覆盖 GameObject 管理到播放控制全链路，安装配置简单（Unity Package + 自动配置），但需注意 Unity 6+ 的版本门槛和 Node.js 环境要求。