Unity MCP Public

🎮 UnityVision MCP

Unity编辑器最强大的AI桥梁

  ](https://nodejs.org/)  

*让AI助手看到、理解和控制你的Unity项目*

特性 • 安装 • 快速开始 • 工具 • 例子

______________________________________________________________________

🚀 什么是UnityVision？

UnityVision是一个 模型上下文协议（MCP） 为AI助手提供以下功能的服务器 克劳德, 风浪/瀑布, 光标，以及其他对Unity编辑器的深度编程访问。

AI可以：

• 📸 看 您的游戏截图
• 🔍 检查 场景层次和组件
• ✏️ 修改 游戏对象、组件和资产
• 🐛 调试 通过读取控制台日志并修复代码
• 🧪 测试 通过运行测试套件并迭代
• 🏗️ 构建 适用于任何平台的项目

______________________________________________________________________

✨ 特性

独特的功能（其他Unity MCP没有这些功能）

______________________________________________________________________

📦 安装

先决条件

• Node.js 18岁或以上
• 统一 2021.3 LTS或更高版本（见下表兼容性）
• 一 MCP兼容AI客户端 （风帆、克劳德桌面、光标等）

Unity版本兼容性

注： UnityVision通过反射使用一些内部Unity编辑器API（例如，用于控制台日志文件/行信息）。这些可能会在Unity版本之间发生变化。如果您遇到问题，请 报告他们.

步骤1：克隆存储库

git clone https://github.com/WeberNik/UnityMCP-Public.git
cd UnityMCP-Public

步骤2：安装Unity软件包

选项A：通过包管理器UI添加（推荐）

1. 开放团结
2. 首选 Window > Package Manager
3. 点击 + → Add package from git URL...
4. 粘贴： https://github.com/WeberNik/UnityMCP-Public.git?path=/Packages/com.unityvision.bridge

选项B：通过manifest.json添加

{
  "dependencies": {
    "com.unityvision.bridge": "https://github.com/WeberNik/UnityMCP-Public.git?path=/Packages/com.unityvision.bridge"
  }
}

选项C：本地文件参考（用于开发）

{
  "dependencies": {
    "com.unityvision.bridge": "file:../path/to/UnityMCP-Public/Packages/com.unityvision.bridge"
  }
}

步骤3：构建或下载MCP服务器

选项A：本地构建（如果更改服务器代码，建议使用）

cd unity-mcp-server
npm install
npm run build

选项B：下载预构建的服务器（不需要npm）

抓住 unity-mcp-server-prebuilt.zip 最新GitHub版本中的资产：https://github.com/WeberNik/UnityMCP-Public/releases/latest

它包括 dist/ 和 node_modules/，因此您可以在不安装npm的情况下运行服务器。

将其解压缩到任何位置，然后将您的MCP客户端指向：

/unity-mcp-server/dist/server.js

注： 运行服务器仍然需要Node.js。

可选：Unity菜单帮助程序（安装/重建MCP服务器）

Unity包括两个方便的菜单项，用于为您设置Node.js MCP服务器：

• Window > UnityVision > Install MCP Server\

提示 unity-mcp-server 文件夹，然后运行 npm install （如果需要）和 npm run build.

• Window > UnityVision > Rebuild MCP Server\

删除 dist/ 并奔跑 npm run build 使用之前保存的服务器路径。

这些助手遵循与以下相同的先决条件 选项A 如果您使用 预构建服务器.

如果出现故障，Unity将记录一个错误，您可以这样修复它：

• Node/NMP未安装或未在PATH上\

错误： npm is not available. Please install Node.js.\ 修复：安装Node.js 18+并重新启动Unity，然后重试。

• 未设置MCP服务器路径\

错误： MCP server path not configured.\ 修复：运行 安装MCP服务器 并选择 unity-mcp-server 文件夹，或在中设置路径 Window > UnityVision > Bridge Status.

• 选择了错误的文件夹（缺少package.json）\

错误： No package.json found at ...\ 修复：选择实际 unity-mcp-server 文件夹（包含 package.json).

• npm安装/构建失败\

修复：检查Unity控制台和 Logs/UnityVision_Debug.log，然后在该文件夹中手动运行命令：

  npm install
  npm run build

步骤4：配置您的AI客户端

你需要告诉你的AI客户端在哪里可以找到MCP服务器。最简单的方法是使用 内置配置生成器 在Unity中：

1. 打开Unity并安装软件包
2. 首选 Window > UnityVision > Bridge Status
3. 扩展 “AI客户端配置”
4. 点击 “复制配置”
5. 粘贴到AI客户端的MCP配置文件中

手动配置

如果您更喜欢手动设置，请将此添加到AI客户端的MCP配置中：

{
  "mcpServers": {
    "unity-vision": {
      "command": "node",
      "args": ["/absolute/path/to/UnityMCP-Public/unity-mcp-server/dist/server.js"]
    }
  }
}

⚠️ 重要提示： 使用正斜杠 / 甚至在Windows上。反斜杠可能会导致问题。

______________________________________________________________________

🌊 Windsurf / Cascade

配置文件位置：

• 窗户： C:\Users\\.codeium\windsurf\mcp_config.json
• macOS： ~/.codeium/windsurf/mcp_config.json
• Linux： ~/.codeium/windsurf/mcp_config.json

将此添加到 mcpServers 对象：

"unity-vision": {
  "command": "node",
  "args": ["/path/to/UnityMCP-Public/unity-mcp-server/dist/server.js"]
}

保存后， 重新启动Windsurf 加载新的MCP服务器。

🤖 Claude Desktop

配置文件位置：

• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

添加到配置中：

{
  "mcpServers": {
    "unity-vision": {
      "command": "node",
      "args": ["/absolute/path/to/UnityMCP-Public/unity-mcp-server/dist/server.js"]
    }
  }
}

保存后重新启动Claude Desktop。

📝 Cursor

打开光标设置→ MCP服务器→ 使用以下命令添加新服务器：

{
  "unity-vision": {
    "command": "node",
    "args": ["/absolute/path/to/UnityMCP-Public/unity-mcp-server/dist/server.js"]
  }
}

______________________________________________________________________

故障排除配置

______________________________________________________________________

🎯 快速开始

1. 开放团结 -网桥服务器自动启动
2. 验证连接 首选 Window > UnityVision > Bridge Status
3. 启动您的AI客户端 -它将通过MCP连接
4. 让AI与Unity互动！

"Show me the current scene hierarchy"
"Create a cube at position (0, 5, 0) with a Rigidbody"
"What errors are in the console?"
"Take a screenshot of the game view"

______________________________________________________________________

🛠️ 可用工具（26+）

使用 action 参数。这使工具数量保持较低，同时提供完整的功能。

v1.1中的新功能（第50阶段）

自定义工具（可扩展）

UnityVision支持 自定义工具注册.Unity项目可以定义自己的工具，这些工具会自动被发现并在MCP服务器上注册：

创建自定义工具： 从……继承…… McpToolBase 并实施 Execute() 或 ExecuteAsync()工具是通过反射自动发现的。

使用示例

// Get editor state
unity_editor({ action: 'get_state' })

// Enter play mode
unity_editor({ action: 'set_play_mode', mode: 'play' })

// Get console errors
unity_console({ action: 'get_logs', logType: 'error' })

// Create a cube
unity_gameobject({ action: 'create', name: 'MyCube', primitiveType: 'Cube' })

// Search for materials
unity_asset({ action: 'search', searchQuery: 't:Material' })

// Take a screenshot
unity_screenshot({ action: 'game_view' })

// Create a new script
unity_script({ action: 'create', path: 'Scripts/PlayerController.cs', template: 'MonoBehaviour' })

// List installed packages
unity_package({ action: 'list' })

// Recompile scripts
unity_editor({ action: 'recompile' })

______________________________________________________________________

💡 示例工作流

🐛 调试NullReferenceException

User: "My game crashes with a NullReferenceException when I press Play"

AI uses:
1. unity_console({ action: 'get_logs', logType: 'error' }) → Sees the exception with stack trace
2. Reads the script file mentioned in the stack trace
3. Identifies the uninitialized variable
4. Fixes the code
5. unity_editor({ action: 'set_play_mode', mode: 'play' }) → Tests the fix
6. unity_console({ action: 'get_logs', logType: 'error' }) → Confirms no more errors

🎨 设置UI布局

User: "Create a main menu with Play and Quit buttons"

AI uses:
1. unity_menu({ action: 'execute', menuPath: 'GameObject/UI/Canvas' }) → Creates Canvas
2. unity_gameobject({ action: 'create', ... }) → Creates buttons
3. unity_component({ action: 'set_properties', ... }) → Configures button text
4. unity_screenshot({ action: 'game_view' }) → Shows the result to verify

🏗️ 批量场景设置

User: "Create 10 cubes in a circle pattern"

AI uses:
1. unity_batch({ action: 'execute', operations: [...] })
   - 10 gameobject create operations with calculated positions
   - Atomic rollback if any fails

🥽 VR开发

User: "Position the XR rig at the spawn point and take a screenshot"

AI uses:
1. unity_scene({ action: 'hierarchy' }) → Finds the spawn point transform
2. unity_xr({ action: 'set_pose', position: {...} }) → Moves rig to spawn
3. unity_screenshot({ action: 'game_view' }) → Shows VR perspective

🔀 多项目工作流

User: "I have two Unity projects open - switch to MyGame and show its hierarchy"

AI uses:
1. unity_project({ action: 'list' }) → Sees both projects
2. unity_project({ action: 'switch', projectPath: 'MyGame' }) → Changes target
3. unity_scene({ action: 'hierarchy' }) → Shows hierarchy of MyGame

______________________________________________________________________

🔒 安全特性

UnityVision的设计考虑到了安全性：

• ↩️ 完全撤消支持 -每个突变都会在Unity的撤销系统中注册。按Ctrl+Z可恢复任何AI操作。
• 🔍 干运行模式 -通行证 dryRun: true 在不实际更改的情况下预览将要更改的内容。
• ⚠️ 需要确认 -破坏性行动，如 delete_game_object 和 delete_asset 要求明确 confirm: true.
• 🏠 仅限本地主机 -网桥服务器仅绑定到 localhost。无法进行远程访问。
• 🔐 可选身份验证 -使用启用会话令牌身份验证 UNITY_VISION_REQUIRE_AUTH=true.
• 📁 路径横向保护 -所有文件操作验证路径是否保持在 Assets/ 或 Packages/.拒绝 .. 遍历和符号链接。
• 💾 原子文件写入 -脚本写入 .tmp 首先是文件，然后原子移动以防止崩溃/中断时损坏。
• 🔑 SHA256前提条件 -脚本更新可能需要 precondition_sha256 以检测并发编辑中的冲突。

______________________________________________________________________

🏗️ 建筑

┌─────────────────────────────────────────────────────────────────┐
│                    AI Assistant (Claude, etc.)                  │
│                          MCP Client                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ stdio (MCP Protocol)
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    UnityVision MCP Server                       │
│                     (Node.js + TypeScript)                      │
│                                                                 │
│  • 26 Consolidated tools + 5 MCP Resources                      │
│  • WebSocket Server (port 7890)                                 │
│  • Custom tool registration from Unity                          │
│  • Type-safe request/response handling                          │
└─────────────────────────────────────────────────────────────────┘
                                ▲
                                │ WebSocket ws://localhost:7890
                                │ (Unity connects to MCP server)
                                │
┌─────────────────────────────────────────────────────────────────┐
│                    Unity Editor(s)                              │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │           UnityVision Bridge (C# Package)               │   │
│  │                                                         │   │
│  │  • WebSocket CLIENT (connects to MCP server)            │   │
│  │  • Auto-reconnect with exponential backoff              │   │
│  │  • Custom tool registration (register_tools)            │   │
│  │  • Main thread dispatch for Unity API calls             │   │
│  │  • Play mode & assembly reload handling                 │   │
│  │  • Full Undo integration                                │   │
│  │  • Atomic file writes with path protection              │   │
│  │  • Custom JSON converters for Unity types               │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

______________________________________________________________________

📁 项目结构

UnityMCP-Public/
├── unity-mcp-server/              # Node.js MCP server
│   ├── src/
│   │   ├── server.ts              # MCP entry point
│   │   ├── websocketHub.ts        # WebSocket server for Unity connections
│   │   ├── unityBridgeClient.ts   # Bridge client for tool execution
│   │   ├── types.ts               # TypeScript type definitions
│   │   ├── resources/             # MCP Resources
│   │   │   └── index.ts           # 5 resources (hierarchy, selection, logs, etc.)
│   │   └── tools/                 # Tool implementations
│   │       ├── consolidatedTools.ts  # 26 grouped tools with action parameter
│   │       ├── index.ts              # Tool registry
│   │       └── ...                   # Handler files
│   ├── tests/                     # Jest unit tests (102 tests)
│   ├── package.json
│   └── tsconfig.json
│
├── Packages/
│   └── com.unityvision.bridge/    # Unity package
│       ├── Editor/
│       │   ├── Bridge/
│       │   │   ├── BridgeServer.cs    # HTTP server (legacy, for fallback)
│       │   │   ├── RpcHandler.cs      # Method dispatch
│       │   │   └── RpcRequest.cs      # Request/response types
│       │   ├── Transport/
│       │   │   └── WebSocketClient.cs # WebSocket client (connects to MCP)
│       │   ├── Serialization/         # Custom JSON converters (NEW)
│       │   │   └── UnityJsonConverters.cs # Vector3, Color, Quaternion, etc.
│       │   ├── Tools/                 # Custom tool system
│       │   │   ├── McpToolBase.cs     # Base class for custom tools
│       │   │   ├── ToolRegistry.cs    # Auto-discovery and registration
│       │   │   └── CustomTools/       # Built-in custom tools
│       │   ├── Services/
│       │   │   └── TestRunnerService.cs  # Unity Test Framework integration
│       │   ├── Utils/
│       │   │   ├── McpServerSetup.cs     # Auto npm install/build
│       │   │   └── MainThreadDispatcher.cs # Main thread dispatch
│       │   ├── Handlers/              # 15+ handler files
│       │   │   ├── EditorHandlers.cs     # Editor state, recompile, compilation status
│       │   │   ├── SceneHandlers.cs      # Scene CRUD operations
│       │   │   ├── GameObjectHandlers.cs # Auto-create hierarchy, safe tags
│       │   │   ├── ScriptHandler.cs      # Atomic writes, path protection
│       │   │   ├── ConsoleHandlers.cs    # File/line info via reflection
│       │   │   └── ...
│       │   └── UI/
│       │       └── BridgeStatusWindow.cs  # Status UI with connection status
│       └── package.json
│
└── README.md

______________________________________________________________________

⚠️ 重要提示

Unity编辑器焦点和连接稳定性

UnityVision包括几种机制，即使Unity编辑器未聚焦，也能确保可靠的命令执行：

• QueuePlayerLoopUpdate() （Unity 2021.2+）-即使在未聚焦的情况下，也会强制编辑器的更新循环打勾。这是响应式命令处理的主要机制。
• 自动聚焦 --当命令等待时间超过2秒时，UnityVision会自动将Unity置于前台。这是可配置的（默认启用）。
• 心跳健康检查 --服务器定期通过ping/pong检查Unity是否处于活动状态。在30秒内检测到死连接并立即清理。
• 断路器 --在连续3次命令超时后，服务器会暂停新命令10秒，让Unity恢复，防止级联故障。
• 陈旧的命令收割者 --停留在队列中超过30秒的命令会自动过期，并显示一个明确的错误，而不是永远挂起。
• 会话迁移 --当Unity在重新加载程序集或播放模式后重新连接时，挂起的服务器端请求会立即解决，而不是等待。

最佳实践：

1. ✅ 保持团结可见 --将窗口与AI助手并排排列，以获得最佳性能
2. ✅ 等待编译 --Unity编译时不要运行MCP命令
3. ✅ 默认情况下，自动对焦处于打开状态 --当命令待定时，Unity将出现在前台。切换到 Window > UnityVision > Bridge Status
4. ⚠️ 30秒超时 --未在30秒内执行的命令将失败，并显示明确的错误消息

窗口布置示例：

┌─────────────────┬─────────────────┐
│   Windsurf/     │   Unity Editor  │
│   Claude/Cursor │   (VISIBLE)     │
│                 │                 │
│   AI Assistant  │   Scene View    │
│   Chat          │   Game View     │
└─────────────────┴─────────────────┘

注： 当命令处于挂起状态时，自动对焦功能可能会短暂地窃取窗口焦点。如果这会造成干扰，请通过以下方式禁用它 WebSocketClient.AutoFocusEnabled = false 或通过“网桥状态”窗口。

编译与性能

如果出现以下情况，Unity可能会在MCP操作期间短暂编译：

• 创建或修改脚本
• 资产被导入或更改
• 添加或删除包

编译过程中会发生什么：

• MCP命令将被拒绝： "Unity is currently compiling scripts. Please wait..."
• 这可以防止命令挂起或导致错误
• 等待编译完成（观看Unity右下角的进度条）

为了尽量减少编译：

• 禁用自动刷新： Edit > Preferences > Asset Pipeline > Auto Refresh = Off
• 需要时手动刷新： Assets > Refresh 或 Ctrl+R

______________________________________________________________________

⚙️ 配置

环境变量

多项目支持

UnityVision自动处理多个Unity实例：

1. 自动端口分配 -每个Unity实例都有一个唯一的端口（7890-7899）
2. 项目注册表 -项目注册地址： ~/.unityvision/projects.json
3. 自动发现 -MCP服务器发现所有正在运行的项目
4. 智能路由 -如果一个项目处于打开状态，则会自动选择它。多个项目提示选择。

手动端口超控

如果您需要特定端口（例如，用于防火墙规则）：

1. 集 UNITY_VISION_PORT 启动Unity之前的环境变量
2. 或者MCP服务器将自动发现Unity选择的任何端口

______________________________________________________________________

📋 更新日志

v1.2.0--连接稳定性检修

Unity客户端（C#桥）：

• QueuePlayerLoopUpdate() -使用官方的Unity API（2021.2+）强制编辑器更新记号，即使在未聚焦时也是如此。这是最大的稳定性改进。
• 自动聚焦 --当命令等待时间超过2秒时，自动将Unity置于前台。可通过以下方式配置 WebSocketClient.AutoFocusEnabled.
• 陈旧的命令收割者 --在Unity侧队列中停留超过30秒的命令会自动过期并返回错误响应，而不是永远挂起。
• 线程安全连接状态 — _isConnected 和 _isConnecting 现在是 volatile 以防止跨线程的CPU缓存过时。

MCP服务器（Node.js）：

• 乒乓球健康检查 --服务器现在可以正确处理 ping 来自Unity的消息（之前被删除为“未知消息类型”），并以 pong.
• 心跳停止会话检测 --服务器会定期检查所有会话，并关闭30秒内未发送ping的会话。
• 断开连接后立即拒绝命令 --断开连接的会话的挂起命令现在会立即被拒绝，而不是等待30秒超时。
• 断路器 --连续3次命令超时后，新命令会快速失败10秒，以防止级联挂起。下次成功时自动重置。
• 会话迁移 --当Unity在重新加载程序集后重新连接时，待定 resolveSession 服务员立即解决问题，而不是投票。
• 延长重新连接宽限期 --从10秒改为45秒，以适应大型项目装配的重新装载。

v1.1.0--第50阶段

• 编译状态跟踪、详细的控制台日志、带SHA前提条件的文本编辑
• 自动创建层次结构、安全标记分配、原子文件写入、路径遍历保护

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

1. 分叉 仓库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

开发设置

# Clone your fork
git clone https://github.com/YOUR_USERNAME/UnityMCP-Public.git

# Install dependencies
cd UnityMCP-Public/unity-mcp-server
npm install

# Build in watch mode
npm run build -- --watch

______________________________________________________________________

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

• 模型上下文协议 对于MCP规范
• Unity 技术公司 对于令人惊叹的游戏引擎
• AI助手社区推动了可能性的界限

______________________________________________________________________

建于❤️ Unity+AI社区

*截至2026年2月14日的状态--v1.2.0*

⬆ 返回页首