如何设置 Unity MCP Server (2026)
通过 Model Context Protocol 将 Unity 游戏引擎连接至 AI 助手
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
如何设置 Unity MCP Server (2026)
Unity MCP Server 将 Unity 游戏引擎连接到 AI 助手,如 Claude、Cursor 和其他兼容 MCP 的工具。这意味着您的 AI 助手可以直接检查您的 Unity 场景层级(Hierarchy)、读取组件属性、创建和修改 GameObject、管理资产、运行播放模式,甚至执行 C# 脚本——这一切都通过自然语言实现。本指南将带您完成完整的设置和实际操作。
什么是 Unity MCP Server?
MCP (Model Context Protocol) 是由 Anthropic 开发的一项开放标准,旨在将 AI 助手连接到外部工具和数据源。Unity MCP Server 专门为 Unity Editor 实现了该协议,将 Unity 的功能作为 AI 模型可以调用的工具进行公开。
它能做什么?
| 功能 | 描述 |
|---|---|
| 场景检查 (Scene Inspection) | 读取完整的场景层级、GameObject 和组件 |
| 对象操作 (Object Manipulation) | 创建、移动、旋转、缩放和删除 GameObject |
| 组件管理 (Component Management) | 添加、移除和修改组件及其属性 |
| 资产操作 (Asset Operations) | 导入、查找和组织项目资产 |
| 脚本生成 (Script Generation) | 创建并向 GameObject 附加 C# 脚本 |
| 播放模式控制 (Play Mode Control) | 开始、停止和暂停播放模式 |
| 控制台读取 (Console Reading) | 读取 Unity 控制台日志和错误 |
| 构建管理 (Build Management) | 触发目标平台的构建 |
| Prefab 操作 | 创建和实例化 Prefab |
| 材质编辑 (Material Editing) | 修改材质、Shader 和贴图 |
前提条件
在设置 Unity MCP Server 之前,您需要:
- Unity Editor 2022.3 LTS 或更高版本(同样支持 2023.x 或 6000.x)
- Node.js 18 或更高版本
- Claude Desktop、Claude Code 或 Cursor(任何兼容 MCP 的 AI 客户端)
- 在编辑器中打开一个 Unity 项目
验证 Node.js:
node --version
# v18.x.x 或更高版本
第一步:安装 Unity MCP 软件包
方案 A:通过 Unity Package Manager(推荐)
- 打开您的 Unity 项目
- 前往 Window > Package Manager
- 点击左上角的 + 按钮
- 选择 Add package from git URL
- 输入软件包 URL:
https://github.com/anthropics/unity-mcp-server.git
- 点击 Add 并等待安装完成
方案 B:通过 manifest.json
打开项目的 Packages/manifest.json 文件并添加依赖项:
{
"dependencies": {
"com.anthropic.mcp-server": "https://github.com/anthropics/unity-mcp-server.git",
...
}
}
保存文件。Unity 将自动下载并安装该软件包。
方案 C:手动安装
# 克隆仓库
git clone https://github.com/anthropics/unity-mcp-server.git
# 将软件包复制到项目的 Packages 文件夹
cp -r unity-mcp-server/package ~/your-unity-project/Packages/com.anthropic.mcp-server
第二步:在 Unity 中启用 MCP Server
安装完成后,在 Unity Editor 中启用服务器:
- 前往 Edit > Preferences (macOS: Unity > Preferences)
- 在左侧面板中导航到 MCP Server
- 将 Enable MCP Server 切换为 On(开启)
- 记下 Port 端口号(默认为 6400)
- 可选:设置 Authentication Token 以增强安全性
您应该在 Unity 控制台中看到确认信息:
[MCP Server] Started on port 6400
[MCP Server] Waiting for connections...
配置选项
| 设置 | 默认值 | 描述 |
|---|---|---|
| Enable MCP Server | Off | 开启/关闭服务器 |
| Port | 6400 | MCP 连接的 TCP 端口 |
| Auth Token | (空) | 可选的身份验证令牌 |
| Allow Script Execution | Off | 允许 AI 运行任意 C# 代码 |
| Allow File Operations | On | 允许 AI 创建/修改项目文件 |
| Allow Build Triggers | Off | 允许 AI 开始构建 |
| Verbose Logging | Off | 将所有 MCP 请求记录到 Unity 控制台 |
安全提示: 请谨慎使用 "Allow Script Execution"。这会允许 AI 在您的 Unity 编辑器中运行任意 C# 代码。仅在受信任的本地开发环境中开启此功能。
第三步:配置您的 AI 客户端
Claude Desktop 配置
编辑您的 Claude Desktop 配置文件:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"unity": {
"command": "npx",
"args": [
"-y",
"@anthropic-ai/unity-mcp-bridge",
"--port",
"6400"
]
}
}
}
保存后重启 Claude Desktop。
Claude Code 配置
将服务器添加到您的项目或全局 MCP 配置中:
claude mcp add unity \
--command "npx" \
--args "-y" "@anthropic-ai/unity-mcp-bridge" "--port" "6400"
或者添加到项目根目录的 .mcp.json 中:
{
"mcpServers": {
"unity": {
"command": "npx",
"args": ["-y", "@anthropic-ai/unity-mcp-bridge", "--port", "6400"]
}
}
}
Cursor 配置
在项目的 .cursor/mcp.json 中添加:
{
"mcpServers": {
"unity": {
"command": "npx",
"args": ["-y", "@anthropic-ai/unity-mcp-bridge", "--port", "6400"]
}
}
}
第四步:验证连接
与您的 AI 助手开始对话并测试连接:
你能看到我的 Unity 项目吗?请列出当前场景中的 GameObject。
如果配置正确,AI 将查询 Unity 并返回您的场景层级。
实际使用场景
1. 场景搭建与原型设计
要求 AI 构建场景布局:
创建一个简单的平台跳跃关卡布局:
- 一个地面平面,位置 (0, 0, 0),缩放 (20, 1, 5)
- 5 个悬浮平台,高度在 y=2 到 y=8 之间随机分布
- 一个玩家出生点在 (0, 2, 0),用红色球体作为占位符
- 一个终点对象在 (18, 3, 0),包含绿色立方体和旋转动画
添加一个平行光并将相机设置为正交视图
2. 组件调试
当游戏中的某些功能不起作用时:
我的场景中有一个 "Player" GameObject。
CharacterController 组件似乎没有检测到标签为 "Enemy" 的对象碰撞。
你能检查一下 Player 的组件和 Enemy 对象,看看可能有哪里配置错了吗?
3. 自动生成 C# 脚本
创建一个名为 "CoinCollector" 的 C# 脚本,其功能为:
- 检测与标签为 "Coin" 的对象的触发器碰撞
- 播放收集音效
- 增加一个静态分数计数器
- 销毁硬币对象
- 使用新分数更新 UI Text 元素
将其附加到 Player GameObject 上。
AI 会生成脚本,将其保存到您的 Assets 文件夹中,并将其附加到指定的 GameObject。
4. 资产组织
组织我的 Assets 文件夹:
- 将所有 .png 和 .jpg 文件移动到 Assets/Art/Textures
- 将所有 .fbx 和 .obj 文件移动到 Assets/Art/Models
- 将所有 .cs 脚本移动到 Assets/Scripts,按命名空间分组
- 将所有 .wav 和 .mp3 文件移动到 Assets/Audio
如果文件夹不存在,请创建它们。
5. 性能分析
进入播放模式并监控场景 10 秒钟。
报告任何控制台警告或错误,提供大概的帧率,
并找出任何 MeshRenderer 中顶点数超过 10,000 的 GameObject。
6. 批量操作
找出场景中渲染使用 "Default-Material" 的所有带有 MeshRenderer 组件的 GameObject。
将它们的材质替换为位于 Assets/Materials/ 的 "StandardPBR" 材质。
可用 MCP 工具参考
以下是 Unity MCP Server 提供的关键工具:
unity_get_scene_hierarchy - 获取完整场景树
unity_get_gameobject - 获取特定 GameObject 的详细信息
unity_create_gameobject - 创建一个新的 GameObject
unity_delete_gameobject - 删除一个 GameObject
unity_set_transform - 设置位置、旋转、缩放
unity_add_component - 为 GameObject 添加组件
unity_remove_component - 移除组件
unity_set_component_property - 修改组件属性
unity_find_assets - 搜索项目资产
unity_create_script - 创建一个新的 C# 脚本文件
unity_attach_script - 将脚本附加到 GameObject
unity_enter_play_mode - 进入播放模式
unity_exit_play_mode - 退出播放模式
unity_read_console - 读取控制台日志条目
unity_execute_code - 在编辑器中运行任意 C#
unity_create_prefab - 从 GameObject 创建 Prefab
unity_instantiate_prefab - 在场景中实例化 Prefab
unity_set_material - 为渲染器分配材质
unity_trigger_build - 开始目标平台的构建
故障排除
| 问题 | 解决方案 |
|---|---|
| "Cannot connect to Unity" | 验证 Unity Preferences 中已启用 MCP Server 且端口与配置匹配 |
| "Port 6400 already in use" | 在 Unity Preferences 和 AI 客户端配置中更改端口号 |
| AI 无法看到场景变化 | 确保 Unity Editor 处于前台;某些操作需要聚焦 |
| 脚本无法编译 | 脚本创建后检查 Unity 控制台是否有 C# 编译错误 |
| "Permission denied" 错误 | 在 Unity MCP 设置中启用相关权限(文件操作、脚本执行) |
| 响应缓慢 | 拥有数千个对象的超大场景可能序列化较慢;尝试查询特定对象而非完整层级 |
安全最佳实践
- 在生产环境中使用 Auth Token。 在 Unity MCP Preferences 中设置身份验证令牌,并将其包含在客户端配置中。
- 默认禁用脚本执行。 仅在明确需要 AI 编写并运行 C# 代码时才开启。
- 不要将端口暴露给网络。 MCP 服务器应仅接受来自 localhost 的连接,除非您在安全的团队环境中工作。
- 运行前检查 AI 生成的脚本。 即使是最好的 AI,在将生成的 C# 代码附加到项目之前也应先进行阅读。
结论
Unity MCP Server 通过让 AI 助手直接访问 Unity 编辑器,彻底改变了游戏开发流程。您不再需要通过文本描述场景并来回粘贴代码,而是可以让 Claude 或 Cursor 直接在项目内工作——实时检查对象、生成脚本并验证更改。
对于需要 AI 生成视觉资产(如角色动画、过场视频、配音或推广内容)的游戏开发人员,Hypereal AI 提供了高性价比的 API 接入,支持 AI 视频生成、数字人、图像创建和语音克隆,从而加速您的游戏开发流水线。
