MCP Unity Editor (Game Engine)

MCP Unity 编辑器（游戏引擎）

                              ,/(/.   *(/,                                  
                          */(((((/.   *((((((*.                             
                     .*((((((((((/.   *((((((((((/.                         
                 ./((((((((((((((/    *((((((((((((((/,                     

             ,/(((((((((((((/*.           */(((((((((((((/*.                
            ,%%#((/((((((*                    ,/(((((/(#&@@(                
            ,%%##%%##((((((/*.             ,/((((/(#&@@@@@@(                
            ,%%######%%##((/(((/*.    .*/(((//(%@@@@@@@@@@@(                
            ,%%####%#(%%#%%##((/((((((((//#&@@@@@@&@@@@@@@@(                
            ,%%####%(    /#%#%%%##(//(#@@@@@@@%,   #@@@@@@@(                
            ,%%####%(        *#%###%@@@@@@(        #@@@@@@@(                
            ,%%####%(           #%#%@@@@,          #@@@@@@@(                
            ,%%##%%%(           #%#%@@@@,          #@@@@@@@(                
            ,%%%#*              #%#%@@@@,             *%@@@(                
            .,      ,/##*.      #%#%@@@@,     ./&@#*      *`                
                ,/#%#####%%#/,  #%#%@@@@, ,/&@@@@@@@@@&\.                    
                 `*#########%%%%###%@@@@@@@@@@@@@@@@@@&*´                   
                    `*%%###########%@@@@@@@@@@@@@@&*´                        
                        `*%%%######%@@@@@@@@@@&*´                            
                            `*#%%##%@@@@@&*´                                 
                               `*%#%@&*´                                     
                                                       
     ███╗   ███╗ ██████╗██████╗         ██╗   ██╗███╗   ██╗██╗████████╗██╗   ██╗
     ████╗ ████║██╔════╝██╔══██╗        ██║   ██║████╗  ██║██║╚══██╔══╝╚██╗ ██╔╝
     ██╔████╔██║██║     ██████╔╝        ██║   ██║██╔██╗ ██║██║   ██║    ╚████╔╝ 
     ██║╚██╔╝██║██║     ██╔═══╝         ██║   ██║██║╚██╗██║██║   ██║     ╚██╔╝  
     ██║ ╚═╝ ██║╚██████╗██║             ╚██████╔╝██║ ╚████║██║   ██║      ██║   
     ╚═╝     ╚═╝ ╚═════╝╚═╝              ╚═════╝ ╚═╝  ╚═══╝╚═╝   ╚═╝      ╚═╝   

MCP Unity 是面向 Unity 编辑器的模型上下文协议实现，可让 AI 助手与您的 Unity 项目交互。此软件包在 Unity 与实现 MCP 协议的 Node.js 服务之间提供桥接，使 Cursor、Windsurf、Claude Code、Codex CLI、GitHub Copilot、Google Antigravity 和 OpenCode 等 AI Agent 能够在 Unity 编辑器中执行操作。

功能

IDE 集成 - 软件包缓存访问

MCP Unity 通过将 Unity 的 Library/PackedCache 文件夹添加到工作区，为类似 VSCode 的 IDE（Visual Studio Code、Cursor、Windsurf、Google Antigravity）提供自动集成。此功能可以：

• 改进 Unity 软件包的代码智能
• 为 Unity 软件包提供更好的自动补全和类型信息
• 帮助 AI 编码助手理解项目的依赖项

MCP 服务工具

以下工具可通过 MCP 操作和查询 Unity 场景及 GameObject：

• execute_menu_item：执行 Unity 菜单项（带有 MenuItem 属性标记的函数）

  示例提示词：“执行菜单项 'GameObject/Create Empty'，创建一个新的空 GameObject”

• select_gameobject：按路径或实例 ID 选择 Unity 层级视图中的游戏对象

  示例提示词：“选择场景中的 Main Camera 对象”

• update_gameobject：更新 GameObject 的核心属性（名称、标签、图层、激活/静态状态）；如果 GameObject 不存在，则创建它

  示例提示词：“将 Player 对象的标签设为 'Enemy'，并将其设为非激活状态”

• update_component：更新 GameObject 上的组件字段；如果 GameObject 不包含该组件，则将其添加到 GameObject 上

  示例提示词：“为 Player 对象添加 Rigidbody 组件，并将其质量设为 5”

• add_package：在 Unity Package Manager 中安装新软件包

  示例提示词：“为我的项目添加 TextMeshPro 软件包”

• run_tests：使用 Unity Test Runner 运行测试

  示例提示词：“运行项目中的所有 EditMode 测试”

• send_console_log：向 Unity 发送控制台日志

  示例提示词：“向 Unity 编辑器发送控制台日志”

• add_asset_to_scene：将 AssetDatabase 中的资源添加到 Unity 场景

  示例提示词：“将项目中的 Player 预制件添加到当前场景”

• create_prefab：创建预制件，可选添加 MonoBehaviour 脚本和序列化字段值

  示例提示词：“使用 'PlayerController' 脚本创建名为 'Player' 的预制件”

• create_scene：创建新场景并将其保存到指定路径

  示例提示词：“在 Scenes 文件夹中创建名为 'Level1' 的新场景”

• load_scene：按路径或名称加载场景，可选择以叠加方式加载

  示例提示词：“加载 MainMenu 场景”

• delete_scene：按路径或名称删除场景，并将其从 Build Settings 中移除

  示例提示词：“从项目中删除旧的 TestScene”

• get_gameobject：获取特定 GameObject 的详细信息，包括所有组件

  示例提示词：“获取 Player GameObject 的详细信息”

• get_console_logs：获取 Unity 控制台中的日志，支持分页

  示例提示词：“显示 Unity 控制台中最近的 20 条错误日志”

• recompile_scripts：重新编译 Unity 项目中的所有脚本

  示例提示词：“重新编译我的 Unity 项目中的脚本”

• save_scene：保存当前活动场景，也可以选择另存为新路径

  示例提示词：“保存当前场景”或“将场景另存为 'Assets/Scenes/Level2.unity'”

• get_scene_info：获取活动场景的信息，包括名称、路径、未保存状态以及所有已加载的场景

  示例提示词：“我的项目中当前加载了哪些场景？”

• unload_scene：从层级视图中卸载场景（不会删除场景资源）

  示例提示词：“从层级视图中卸载 UI 场景”

• duplicate_gameobject：在场景中复制 GameObject，可选择重命名并更改父对象

  示例提示词：“将 Enemy 预制体复制 5 次，并将它们命名为 Enemy_1 到 Enemy_5”

• delete_gameobject：从场景中删除 GameObject

  示例提示词：“从场景中删除旧的 Player 对象”

• reparent_gameobject：更改 GameObject 在层级视图中的父对象

  示例提示词：“将 HealthBar 对象移到 UI Canvas 下作为子对象”

• move_gameobject：将 GameObject 移动到新位置（局部空间或世界空间）

  示例提示词：“将 Player 对象移动到世界空间中的位置 (10, 0, 5)”

• rotate_gameobject：将 GameObject 旋转到新的角度（局部空间或世界空间，可使用欧拉角或四元数）

  示例提示词：“将 Camera 绕 Y 轴旋转 45 度”

• scale_gameobject：将 GameObject 缩放到新的局部比例

  示例提示词：“将 Enemy 对象缩放到原来的两倍”

• set_transform：一次操作即可设置 GameObject 的位置、旋转和缩放

  示例提示词：“将 Cube 的位置设为 (0, 5, 0)、旋转设为 (0, 90, 0)，缩放设为 (2, 2, 2)”

• create_material：使用指定的着色器创建新材质并保存到项目中

  示例提示词：“使用 URP Lit 着色器创建一个名为 'EnemyMaterial' 的红色材质”

• assign_material：将材质分配给 GameObject 的 Renderer 组件

  示例提示词：“将 'EnemyMaterial' 分配给 Enemy GameObject”

• modify_material：修改现有材质的属性（颜色、浮点值、纹理）

  示例提示词：“将 'EnemyMaterial' 的颜色改为蓝色，并将金属度设为 0.8”

• get_material_info：获取材质的详细信息，包括着色器和所有属性

  示例提示词：“显示 'PlayerMaterial' 的所有属性”

• batch_execute：在单个批量请求中执行多个工具操作，减少往返次数，并支持在失败时选择回滚，以实现原子操作

  示例提示词：“通过单个批量操作创建 10 个名为 Enemy_1 到 Enemy_10 的空 GameObject”

MCP App 工具

• show_unity_dashboard：在 VS Code 中打开 Unity 仪表板 MCP App（需要 VS Code 1.109+）

  示例提示词：“打开 Unity 仪表板应用”

• get_play_mode_status：获取 Unity 播放模式状态（isPlaying、isPaused）

  示例提示词：“Unity 是否处于播放模式？”

• set_play_mode_status：通过以下操作控制 Unity 播放模式：'play'（开始或取消暂停）、'pause'（切换暂停状态）、'stop'（退出播放模式）、'step'（前进一帧）

  示例提示词：“开始 Unity 播放模式”或“暂停游戏”或“前进一帧”

MCP 服务资源

• unity://menu-items：获取 Unity Editor 中所有可用菜单项的列表，以便使用 execute_menu_item 工具

  示例提示词：“显示所有与创建 GameObject 相关的可用菜单项”

• unity://scenes-hierarchy：获取当前 Unity 场景层级中的所有游戏对象列表

  示例提示词：“显示当前场景的层级结构”

• unity://gameobject/{id}：根据实例 ID 或场景层级中的对象路径，获取特定 GameObject 的详细信息，包括该 GameObject 的所有组件及其序列化属性和字段

  示例提示词：“获取 Player GameObject 的详细信息”

• unity://logs：获取 Unity 控制台中的所有日志列表

  示例提示词：“显示 Unity 控制台中最近的错误消息”

• unity://packages：获取 Unity Package Manager 中已安装和可用软件包的信息

  示例提示词：“列出我的 Unity 项目当前安装的所有软件包”

• unity://assets：获取 Unity Asset Database 中资源的信息

  示例提示词：“查找我项目中的所有纹理资源”

• unity://tests/{testMode}：获取 Unity Test Runner 中的测试信息

  示例提示词：“列出我的 Unity 项目中所有可用的测试”

• ui://unity-dashboard：Unity 仪表板 MCP App UI

  示例提示词：“打开 Unity 仪表板应用”

MCP 服务提示词

提示词是预先配置的模板，可为常见的 Unity 任务提供引导式工作流。它们有助于 AI 助手了解特定场景中的正确操作顺序和可用工具。

• unity_dashboard：打开 Unity 仪表板 MCP 应用，并提供有关其功能的上下文信息

  **用法：**在 AI 助手中使用提示词“unity_dashboard”，以获取 Unity 仪表板的引导式访问

• gameobject_handling_strategy：提供使用 GameObject 的结构化工作流，包括应使用的工具和资源

  **用法：**在 AI 助手中使用提示词“gameobject_handling_strategy”，并提供 GameObject ID、名称或路径，以获取分步指导

要求

• Unity 6 或更高版本——用于安装服务
• Node.js 18 或更高版本——用于启动服务
• npm 9 或更高版本——用于调试服务

说明

包含空格的项目路径

MCP Unity 支持包含空格的项目路径。不过，如果遇到连接问题，可尝试将项目移至不含空格的路径，以排查问题。

示例：

• ✅ 推荐： C:\Users\YourUser\Documents\UnityProjects\MyAwesomeGame
• ✅ 支持： C:\Users\Your User\Documents\Unity Projects\My Awesome Game

安装

安装此 MCP Unity 服务需要多个步骤：

第 1 步：安装 Node.js

要运行 MCP Unity 服务，需要在计算机上安装 Node.js 18 或更高版本：

步骤 3：配置 AI 大模型客户端

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "${workspaceFolder}/Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["ABSOLUTE/PATH/TO/mcp-unity/Server~/build/index.js"]

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

{
   "mcpServers": {
       "mcp-unity": {
          "command": "node",
          "args": [
             "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"
          ]
       }
   }
}

[mcp_servers.mcp-unity]
command = "node"
args = ["Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"]

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp-unity": {
      "type": "local",
      "enabled": true,
      "command": ["node", "Library/PackageCache/com.gamelovers.mcp-unity@<hash>/Server~/build/index.js"],
      "environment": {}
    }
  }
}

AI 客户端连接到 WebSocket 服务后，会自动显示在窗口的绿色框中

可选：设置 WebSocket 端口

默认情况下，WebSocket 服务运行在端口 '8090' 上。若要更改：

1. 打开 Unity Editor
2. 导航至 Tools > MCP Unity > Server Window
3. 将“Connection Port”的值更改为所需的端口号
4. Unity 会将该值保存在 ProjectSettings/McpUnitySettings.json 中
5. 重启 Node.js 服务

Node 桥接程序会从其已安装的软件包路径中查找该项目设置文件，因此不依赖 MCP 客户端的工作目录。若要为单个 Node 进程覆盖此设置，请设置 UNITY_PORT，例如：UNITY_PORT=9001 node build/index.js。

可选：设置超时时间

默认情况下，MCP 服务与 WebSocket 之间的超时时间为 10 秒。 若要更改：

1. 打开 Unity Editor
2. 导航至 Tools > MCP Unity > Server Window
3. 将“Request Timeout (seconds)”的值更改为所需的超时秒数
4. Unity 会将该值保存在 ProjectSettings/McpUnitySettings.json 中
5. 重启 Node.js 服务

若要为单个 Node 进程覆盖此设置，请设置 UNITY_REQUEST_TIMEOUT（单位为秒），例如：UNITY_REQUEST_TIMEOUT=30 node build/index.js。

提示

你的 AI 编码 IDE（例如 Claude Desktop、Cursor IDE、Windsurf IDE）与 MCP 服务之间的超时时间取决于 IDE。

可选：运行持久化的无头 MCP 主机

默认情况下，MCP Unity 在 -batchmode 中保持禁用，因此 CI 和云构建不会启动桥接程序或运行 npm。若要将长期运行的无头 Editor 用作 MCP 主机，请在启动 Unity 前选择启用 Server Window 中的 Allow Batch Mode Server，或设置 MCP_UNITY_ALLOW_BATCH_MODE=true：

MCP_UNITY_ALLOW_BATCH_MODE=true Unity -batchmode -nographics -projectPath /path/to/project -logFile /path/to/unity.log

选择启用后，Unity 端的 WebSocket 服务会正常启动，但在 batch mode 下不会运行 npm install 或 npm run build。请确保 Node 桥接程序已构建完成，并可供 MCP 客户端使用。

桥接配置解析

Node 桥接程序按以下顺序解析每个连接值：对应的环境变量（UNITY_PORT、UNITY_HOST 或 UNITY_REQUEST_TIMEOUT）、MCP_UNITY_SETTINGS_PATH、在已安装软件包上级目录中找到的 ProjectSettings/McpUnitySettings.json 文件、在其工作目录上级目录中找到的文件，最后使用默认值。生成的 MCP 配置会显式设置 MCP_UNITY_SETTINGS_PATH 和 MCP_UNITY_AUTH_TOKEN_PATH。桥接程序会记录值的来源，并在回退到默认值前发出警告。

桥接安全性与软件包安装

MCP Unity 会在 Library/McpUnity/bridge-token 中为每个项目生成一个 256 位身份验证令牌。令牌解析采用严格规则：优先使用 MCP_UNITY_AUTH_TOKEN，其次是 MCP_UNITY_AUTH_TOKEN_PATH，最后使用在已发现的 Unity 项目旁边的令牌。明确指定的值若不存在或格式错误，都会直接报错，不会回退。生成的配置使用令牌文件路径，绝不会将密钥复制到 ProjectSettings。

Unity 端点要求使用 HTTP Basic 凭据，用户名为 mcp-unity，并拒绝所有包含 Origin 标头的 WebSocket 握手。直接集成 WebSocket 的程序必须进行身份验证，并省略 Origin。使用 Server Window 复制或重新生成令牌；轮换令牌后，请重启所有 MCP 客户端进程。

默认情况下，add_package 工具处于禁用状态，因为 Unity 软件包在编译时可以执行 Editor 代码。仅当软件包来源和 MCP 客户端可信时，才在 Tools > MCP Unity > Server Window 中启用 Allow Package Installation，或在 ProjectSettings/McpUnitySettings.json 中将 AllowPackageInstallation 设为 true。

版本 1.5.0 会有意拒绝 1.4.x Node 桥接程序。请升级 Unity 和 Node 软件包组件；如果软件包缓存路径已更改，请再次运行 Unity Configure 操作，然后重启 MCP 客户端。

可选：允许远程 MCP 桥接连接

默认情况下，WebSocket 服务会绑定到 'localhost'。若要允许其他机器连接 MCP 桥接程序：

1. 打开 Unity Editor
2. 前往 Tools > MCP Unity > Server Window
3. 勾选 "Allow Remote Connections"
4. Unity 会将 WebSocket 服务绑定到 '0.0.0.0'（所有接口）
5. 重启 Node.js 服务以应用新的主机配置
6. 从远程运行 MCP 桥接程序时，将环境变量 UNITY_HOST 设为 Unity 机器的 IP 地址：UNITY_HOST=192.168.1.100 node server.js

远程传输仍使用未加密的 ws://。身份验证可以防止未授权访问，但不会隐藏流量；请将远程使用限制在可信网络、VPN 或 SSH 隧道中。无法读取 Unity 项目令牌文件的远程桥接程序，必须通过安全的密钥机制获取 MCP_UNITY_AUTH_TOKEN。

调试服务

npx @modelcontextprotocol/inspector node Server~/build/index.js

npx @modelcontextprotocol/inspector node Server~/build/index.js

常见问题

Error:
Connection failed: Unknown error

故障排除：WSL2（Windows 11）网络

在 WSL2 中运行 MCP（Node.js）服务，同时在 Windows 11 上运行 Unity 时，连接 ws://localhost:8090/McpUnity 可能会失败，并显示 ECONNREFUSED。

原因：WSL2 和 Windows 使用不同的网络命名空间——WSL2 内部的 localhost 并不指向 Windows 主机。默认情况下，Unity 会监听 localhost:8090。

解决方案 1 — 启用 WSL2 镜像模式网络（推荐）

• Windows 11：设置 → 系统 → 面向开发人员 → WSL → 启用“镜像模式网络”。
• 或通过 .wslconfig 配置（然后运行 wsl --shutdown 并重新打开 WSL）：

[wsl2]
networkingMode=mirrored

启用后，Windows 和 WSL2 将共享 localhost，因此默认配置（localhost:8090）即可正常工作。

解决方案 2 — 将 Node 客户端指向 Windows 主机

启动 MCP 客户端前，在 WSL shell 中设置：

# Use the Windows host IP detected from resolv.conf
export UNITY_HOST=$(grep -m1 nameserver /etc/resolv.conf | awk '{print $2}')

这样，Server~/src/unity/mcpUnity.ts 将连接到 ws://$UNITY_HOST:8090/McpUnity，而不是 localhost（它会读取 UNITY_HOST；如果存在 ProjectSettings/McpUnitySettings.json，也可能会使用其中的 Host）。

解决方案 3 — 允许 Unity 接受远程连接

• Unity：Tools → MCP Unity → Server Window → 启用“Allow Remote Connections”（Unity 将绑定到 0.0.0.0）。
• 确保 Windows 防火墙允许在配置的端口上接收 TCP 入站连接（默认端口为 8090）。
• 在 WSL2 中连接到 Windows 主机 IP（参见解决方案 2）；如果启用了镜像模式，也可以连接到 localhost。

说明

默认端口为 8090。你可以在 Unity Server Window（Tools → MCP Unity → Server Window）中更改端口。该值映射到 McpUnitySettings，并保存在 ProjectSettings/McpUnitySettings.json 中。

验证连接

npm i -g wscat
# After enabling mirrored networking
wscat -c ws://localhost:8090/McpUnity
# Or using the Windows host IP
wscat -c ws://$UNITY_HOST:8090/McpUnity

运行测试

C# 测试（Unity）

使用 Unity 的 Test Runner 运行测试：

1. 打开 Unity Editor
2. 前往 Window > General > Test Runner
3. 选择“EditMode”选项卡
4. 点击“Run All”以运行所有测试

TypeScript 测试（服务端）

使用 Jest 运行测试：

cd Server~
npm test

以监视模式运行测试：

npm run test:watch

支持与反馈

如果你有任何问题或需要支持，请在此代码仓库中提交一个 问题，或者通过以下方式联系我们：

• Linkedin：
• Discord：gamester7178
• 电子邮件：[email protected]

贡献

欢迎贡献！欢迎提交 Pull Request，或针对你的需求创建 Issue。

请按照 Conventional Commits 格式提交更改。

许可证

此项目采用 MIT License

致谢

• Model Context Protocol
• Unity Technologies
• Node.js
• WebSocket-Sharp