如何设置 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 视频生成、数字人、图像创建和语音克隆，从而加速您的游戏开发流水线。