Unity MCP Bridge

Unity MCP Bridge

Connect AI assistants to Unity Editor via Model Context Protocol

Features • Installation • Usage • Tools • Configuration • Troubleshooting

______________________________________________________________________

Unity MCP Bridge支持以下AI助手 克劳德在光标 直接与Unity编辑器交互。阅读控制台日志、检查编译错误、控制播放模式、捕获屏幕截图、导航资源等，所有这些都无需离开代码编辑器。

特性

• 控制台日志 --实时访问Unity控制台，按类型过滤（日志/警告/错误）
• 编译错误 --C#编译错误和警告的即时通知，包括文件路径和行号
• 播放模式控制 --远程启动、停止和暂停播放模式
• 截图 --以可配置的质量（低/中/高）捕获游戏视图和场景视图
• 资产导航 --打开前言、场景和脚本；选择层次结构中的对象并设置其框架
• 层次结构检查 --查看场景和预制件的完整游戏对象层次结构
• 资产刷新 --代码更改后触发资产数据库刷新
• 调试终端 --游戏内IMGUI调试控制台，具有20多个内置命令、自定义命令支持、参数自动补全、观察表达式和剪贴板支持
• 后台操作 --即使Unity不在焦点上也能工作（对于大多数操作）
• 简易设置 --通过Unity软件包管理器进行简单安装

需求

• 统一 6000.0（Unity 6）或更高版本
• Node.js 18+（适用于MCP服务器）
• 光标IDE 支持MCP（或任何兼容MCP的客户端）

安装

第一步：安装Unity软件包

选项A：通过包管理器安装（推荐）

1. 在Unity中，转到 窗口>包管理器
2. 点击 + 在左上角
3. 选择 从git URL添加包。。。
4. 输入：

   https://github.com/Nexonium/unity-mcp-bridge.git

1. 点击 添加

要安装特定版本，请附加标签：

https://github.com/Nexonium/unity-mcp-bridge.git#v1.2.0-pre.1

选项B：添加到manifest.json

添加到您的 Packages/manifest.json:

{
  "dependencies": {
    "com.nexonium.unity-mcp-bridge": "https://github.com/Nexonium/unity-mcp-bridge.git#v1.2.0-pre.1"
  }
}

选项C：本地下载并安装

1. 下载或克隆此存储库
2. 在Unity中，转到 窗口>包管理器
3. 点击 + > 从磁盘添加包。..
4. 导航到下载的文件夹并选择 package.json

步骤2：构建MCP服务器

cd mcp-server
npm install
npm run build

步骤3：配置游标

添加到光标MCP设置文件中：

窗户： %USERPROFILE%\.cursor\mcp.json\ macOS/Linux： ~/.cursor/mcp.json

{
  "mcpServers": {
    "unity": {
      "command": "node",
      "args": ["C:/path/to/unity-mcp-bridge/mcp-server/dist/index.js"]
    }
  }
}

注： 使用正斜杠 / 在路径中，甚至在Windows上。

步骤4：启动服务器

1. 在Unity中，转到 窗口>Unity MCP网桥>服务器
2. 点击 启动服务器
3. （可选）启用 Unity Open自动启动 为方便起见
4. 重新启动Cursor以加载MCP服务器

用法

配置后，Cursor中的AI助手可以自动使用Unity工具。试着问：

• *“检查是否有任何编译错误”*
• *“显示最近的Unity控制台日志”*
• *“启动播放模式并截图”*
• *“打开播放器前言并显示其层次结构”*
• *“拍摄场景视图的屏幕截图”*
• *“在调试终端中执行'obj.findPlayer'”*
• *“在终端中运行'mem'以检查内存使用情况”*

示例工作流

调试工作流程：

1. 在Cursor中编辑C#文件
2. 问： *“是否存在任何编译错误？”*
3. AI运行 unity_refresh 然后 unity_get_compilation_errors
4. AI显示文件路径和行号错误
5. 你修复了错误，AI验证编译成功

目视检查工作流程：

1. 问： *“打开信使通知前言”*
2. AI运行 unity_open_asset 进入预制模式
3. AI运行 unity_get_hierarchy 查看结构
4. AI运行 unity_frame_selected 和 unity_screenshot 捕捉视图
5. AI描述它所看到的并提出改进建议

可用工具

编辑器状态

控制台日志

播放模式

截图

参数：

• view — "game" （默认）或 "scene"
• quality — "low" （640x480，~500个令牌）， "medium" （1280x720，约1200个代币）， "high" （本地，约2700+代币）

资产导航

调试终端

调试终端

调试终端是一个用于运行时调试的游戏内IMGUI控制台。按 ~ （后退）切换。

内置命令

终端功能

• 选项卡完成 用于命令和参数（游戏对象名称、场景、组件、别名）
• 命令历史 带有向上/向下箭头（在会话中持续存在）
• 剪贴板 支持（Ctrl+C/Ctrl+V）
• Ctrl+Backspace 向后删除单词
• 向上/向下翻页 滚动
• 观察面板 在终端下方显示实时更新值
• 命令别名 具有持久性（例如。， alias p obj.find Player)

自定义命令

使用添加游戏特定命令 [TerminalCommand] 属性：

using UnityMCPBridge.Terminal;

public static class MyCommands
{
    [TerminalCommand("hp", "Set player health", "hp [value]",
        CompleterMethod = "GameObjectNames")]
    public static string SetHealth(string[] args)
    {
        // Your game logic here
        return "Done";
    }
}

命令是通过反射自动发现的。看 CONTRIBUTING.md 了解全部细节。

配置

Unity设置（窗口>Unity MCP网桥>服务器）

环境变量（MCP服务器）

建筑

+-------------------+                          +-------------------+
|     Cursor        ||   MCP Server      |
|   (AI Agent)      |       (stdio)            |   (Node.js)       |
+-------------------+                          +---------+---------+
                                                         |
                                                    HTTP REST
                                                         |
                                               +---------+---------+
                                               |  Unity Editor     |
                                               |  (HTTP Server)    |
                                               |  Port 7890        |
                                               +-------------------+

请求流程：

1. AI通过MCP协议（stdio）发送工具调用
2. MCP服务器（TypeScript）转换为HTTP请求
3. Unity HTTP服务器在后台线程上接收
4. 直接处理的只读请求；排队等待主线程的操作
5. 响应通过相同的路径返回

故障排除

“无法连接到Unity”

• 确保Unity编辑器已打开
• 检查MCP网桥服务器是否正在运行（窗口>Unity MCP网桥>服务器）
• 验证Unity和MCP服务器配置中的端口是否匹配

“请求超时”

• Unity可能正忙（编译、加载资产）
• 尝试在Unity窗口中单击“唤醒它”
• 增加 UNITY_TIMEOUT 慢速操作的环境变量

端口已在使用中

• 在Unity MCP网桥设置中更改端口
• 更新 UNITY_PORT 在您的MCP服务器配置或环境中

代码更改后服务器停止

这是意料之中的——Unity会重新编译并重新加载域。如果 自动启动 启用后，服务器会自动重新启动。

屏幕截图为空或错误

• 确保场景中存在摄像头（游戏视图需要摄像头）
• 对于“场景视图”屏幕截图，请确保“场景视图（Scene View）”窗口已打开
• 尝试使用 unity_frame_selected 在拍摄之前定位相机

贡献

欢迎投稿！请随时提交拉取请求。

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

支持

如果你觉得这个项目有用，可以考虑支持它的开发：


______________________________________________________________________

Made with Claude AI assistance