MCP Unity Editor（游戏引擎）

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

MCP Unity 是 Model Context Protocol 在 Unity 编辑器中的实现，允许 AI 助手与您的 Unity 项目交互。这个包提供了 Unity 和实现 MCP 协议的 Node.js 服务器之间的桥梁，使 Claude、Windsurf 和 Cursor 等 AI 代理能够在 Unity 编辑器中执行操作。

功能

IDE 集成 - 包缓存访问

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

• 提高对 Unity 包的代码智能感知
• 为 Unity 包提供更好的自动完成和类型信息
• 帮助 AI 编码助手理解您项目的依赖关系

MCP 服务器工具

• execute_menu_item: 执行 Unity 菜单项（用 MenuItem 属性标记的函数）

  示例提示: "执行菜单项 'GameObject/Create Empty' 创建一个新的空 GameObject"

• select_gameobject: 通过路径或实例 ID 选择 Unity 层次结构中的游戏对象

  示例提示: "选择场景中的 Main Camera 对象"

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

  示例提示: "将 Player 对象的标签设置为 ‘Enemy’ 并使其不可用"

• update_component: 更新 GameObject 上的组件字段，如果 GameObject 不包含该组件则添加它

  示例提示: "给 Player 对象添加 Rigidbody 组件并设置其质量为 5"

• add_package: 在 Unity 包管理器中安装新包

  示例提示: "给我的项目添加 TextMeshPro 包"

• run_tests: 使用 Unity 测试运行器运行测试

  示例提示: "运行我项目中所有的 EditMode 测试"

• send_console_log: 发送控制台日志到 Unity

  示例提示: "发送控制台日志到 Unity 编辑器"

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

  示例提示: "将我的项目中的 Player 预制体添加到当前场景"

• create_prefab: 创建预制体，并可选择添加 MonoBehaviour 脚本和设置序列化字段值

  示例提示: "从 'PlayerController' 脚本创建一个名为 'Player' 的预制体"

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

  示例提示: "重新编译我 Unity 项目中的所有脚本"

• create_scene: 创建新场景并保存到指定路径

  示例提示: "在 Scenes 文件夹中创建一个名为 'Level1' 的新场景"

• load_scene: 通过路径或名称加载场景，支持可选的叠加加载

  示例提示: "加载 MainMenu 场景"

• delete_scene: 通过路径或名称删除场景并从构建设置中移除

  示例提示: "从我的项目中删除旧的 TestScene"

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

  示例提示: "获取 Player GameObject 的详细信息"

• get_console_logs: 获取 Unity 控制台日志，支持分页

  示例提示: "显示 Unity 控制台最近的 20 条错误日志"

• 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 的渲染器组件

  示例提示: "将 '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: 使用操作 play（开始或继续）、pause（切换暂停）、stop（退出播放模式）、step（前进一帧）控制 Unity 播放模式

  示例提示: "启动 Unity 播放模式"、"暂停游戏" 或 "前进一帧"

MCP 服务器资源

• unity://menu-items: 获取 Unity 编辑器中所有可用的菜单项列表，以方便 execute_menu_item 工具

  示例提示: "显示与 GameObject 创建相关的所有可用菜单项"

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

  示例提示: "显示当前场景层次结构"

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

  示例提示: "获取 Player GameObject 的详细信息"

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

  示例提示: "显示 Unity 控制台最近的错误信息"

• unity://packages: 从 Unity 包管理器获取已安装和可用包的信息

  示例提示: "列出我 Unity 项目中当前安装的所有包"

• unity://assets: 获取 Unity 资产数据库中资产的信息

  示例提示: "查找我项目中的所有纹理资产"

• unity://tests/{testMode}: 获取 Unity 测试运行器中测试的信息

  示例提示: "列出我 Unity 项目中所有可用的测试"

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

  示例提示: "打开 Unity 仪表板应用"

MCP 服务器提示词

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

• unity_dashboard: 打开 Unity 仪表板 MCP App，并提供其功能的上下文信息

  用法: 在 AI 助手中使用 unity_dashboard 提示词，以获得对 Unity 仪表板的引导式访问

• gameobject_handling_strategy: 提供用于处理 GameObject 的结构化工作流，包括应使用哪些工具和资源

  用法: 在 AI 助手中结合 GameObject ID、名称或路径使用 gameobject_handling_strategy 提示词，以获得逐步指导

要求

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

[!NOTE] 包含空格的项目路径

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 或更高版本：

步骤 2: 通过 Unity 包管理器安装 Unity MCP 服务器包

1. 打开 Unity 包管理器 (Window > Package Manager)
2. 点击左上角的 "+" 按钮
3. 选择 "Add package from git URL..."
4. 输入: https://github.com/CoderGamester/mcp-unity.git
5. 点击 "Add"

步骤 3: 配置 AI LLM 客户端

{
  "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": {}
    }
  }
}

启动 Unity 编辑器 MCP 服务器

1. 打开 Unity 编辑器
2. 导航到 Tools > MCP Unity > Server Window
3. 点击 "Start Server" 按钮以启动 WebSocket 服务器
4. 打开 AI 编码 IDE（例如 Cursor、Windsurf、Claude Code、Codex CLI、GitHub Copilot、Google Antigravity、OpenCode 等）并开始执行 Unity 工具

当 AI 客户端连接到 WebSocket 服务器时，它将自动显示在窗口的绿色框中

可选：设置 WebSocket 端口

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

1. 打开 Unity 编辑器
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 编辑器
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。

[!TIP]
您的 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 服务器会正常启动，但在批处理模式下永远不会运行 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 端点要求使用用户名 mcp-unity 的 HTTP Basic 身份验证，并拒绝所有带 Origin 请求头的 WebSocket 握手。直接连接 WebSocket 的集成必须提供身份验证且不能发送 Origin。可以在 Server Window 中复制或重新生成令牌；轮换令牌后，请重启所有 MCP 客户端进程。

Unity 包可能在编译时执行 Editor 代码，因此 add_package 工具默认禁用。仅当 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 Bridge 连接

默认情况下，WebSocket 服务器绑定到 'localhost'。要允许来自其他设备的 MCP Bridge 连接，请执行以下步骤：

1. 打开 Unity 编辑器
2. 依次点击菜单「Tools > MCP Unity > Server Window」
3. 勾选"Allow Remote Connections（允许远程连接）"复选框
4. Unity 将 WebSocket 服务器绑定到 '0.0.0.0'（所有网络接口）
5. 重新启动 Node.js 服务器以应用新的主机配置
6. 在远程运行 MCP Bridge 时，将环境变量 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）网络

当 MCP（Node.js）服务器在 WSL2 内运行，而 Unity 在 Windows 11 上运行时，连接 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 终端中设置：

# 从 resolv.conf 中检测 Windows 主机 IP
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 防火墙允许所配置端口（默认 8090）的入站 TCP。
• 在 WSL2 中，连接到 Windows 主机 IP（见解决方案 2），或在启用镜像网络后连接 localhost。

[!NOTE] 默认端口为 8090。您可以在 Unity 的 Server Window（Tools → MCP Unity → Server Window）中进行更改。该值映射到 McpUnitySettings，并持久化到 ProjectSettings/McpUnitySettings.json。

验证连接

npm i -g wscat
# 启用镜像网络后
wscat -c ws://localhost:8090/McpUnity
# 或使用 Windows 主机 IP
wscat -c ws://$UNITY_HOST:8090/McpUnity

运行测试

C# 测试（Unity）

使用 Unity 的 Test Runner 运行测试：

1. 打开 Unity 编辑器
2. 导航到 Window > General > Test Runner
3. 选择 "EditMode" 选项卡
4. 点击 "Run All" 执行所有测试

TypeScript 测试（服务器）

使用 Jest 运行测试：

cd Server~
npm test

要在监视模式下运行测试：

npm run test:watch

支持与反馈

如有问题或需要支持，请在本仓库提交 issue，或通过以下方式联系：

• Linkedin:
• Discord: gamester7178
• Email: [email protected]

贡献

欢迎贡献！欢迎提交 Pull Request 或 Issue。

提交请遵循 Conventional Commits 规范。

许可证

本项目使用 MIT License 授权。

鸣谢

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