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：通过包管理器安装（推荐）
- 在Unity中，转到 窗口>包管理器
- 点击 + 在左上角
- 选择 从git URL添加包。。。
- 输入：
https://github.com/Nexonium/unity-mcp-bridge.git- 点击 添加
要安装特定版本，请附加标签：
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：本地下载并安装
- 下载或克隆此存储库
- 在Unity中，转到 窗口>包管理器
- 点击 + > 从磁盘添加包。..
- 导航到下载的文件夹并选择
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：启动服务器
- 在Unity中，转到 窗口>Unity MCP网桥>服务器
- 点击 启动服务器
- （可选）启用 Unity Open自动启动 为方便起见
- 重新启动Cursor以加载MCP服务器
用法
配置后，Cursor中的AI助手可以自动使用Unity工具。试着问：
- *“检查是否有任何编译错误”*
- *“显示最近的Unity控制台日志”*
- *“启动播放模式并截图”*
- *“打开播放器前言并显示其层次结构”*
- *“拍摄场景视图的屏幕截图”*
- *“在调试终端中执行'obj.findPlayer'”*
- *“在终端中运行'mem'以检查内存使用情况”*
示例工作流
调试工作流程：
- 在Cursor中编辑C#文件
- 问： *“是否存在任何编译错误？”*
- AI运行
unity_refresh然后unity_get_compilation_errors - AI显示文件路径和行号错误
- 你修复了错误，AI验证编译成功
目视检查工作流程：
- 问： *“打开信使通知前言”*
- AI运行
unity_open_asset进入预制模式 - AI运行
unity_get_hierarchy查看结构 - AI运行
unity_frame_selected和unity_screenshot捕捉视图 - AI描述它所看到的并提出改进建议
可用工具
编辑器状态
| 工具 | 说明 |
|---|---|
unity_status | 获取Unity编辑器状态（版本、项目、播放模式状态） |
unity_compilation_status | 检查Unity是否正在编译以及错误/警告计数 |
控制台日志
| 工具 | 说明 |
|---|---|
unity_get_logs | 使用可选的类型筛选器和限制获取控制台日志 |
unity_clear_logs | 清除所有存储的控制台日志 |
unity_get_compilation_errors | 获取文件路径和行号的编译错误 |
unity_get_compilation_warnings | 获取编译警告 |
播放模式
| 工具 | 说明 |
|---|---|
unity_play | 进入播放模式 |
unity_stop | 退出播放模式 |
unity_pause | 切换暂停状态 |
unity_refresh | 刷新资产数据库（触发重新编译） |
截图
| 工具 | 说明 |
|---|---|
unity_screenshot | 以可配置的质量捕获游戏视图或场景视图 |
参数：
view—"game"（默认）或"scene"quality—"low"（640x480，~500个令牌），"medium"（1280x720，约1200个代币），"high"（本地，约2700+代币）
资产导航
| 工具 | 说明 |
|---|---|
unity_open_asset | 按资源路径打开预制件、场景或脚本 |
unity_select_object | 按层次路径或名称选择游戏对象 |
unity_frame_selected | 在“场景视图”中框选对象（如按F键） |
unity_get_hierarchy | 获取当前场景或预制件中对象的完整层次结构 |
调试终端
| 工具 | 说明 |
|---|---|
unity_terminal_execute | 在运行时调试终端中执行命令（需要播放模式） |
unity_terminal_status | 获取终端状态（活动、可见、命令计数） |
unity_terminal_get_logs | 使用可选的类型/计数过滤器获取终端日志条目 |
unity_terminal_get_history | 获取命令历史记录 |
unity_terminal_execute_batch | 按顺序执行多个命令 |
调试终端
调试终端是一个用于运行时调试的游戏内IMGUI控制台。按 ~ （后退）切换。
内置命令
| 命令 | 描述 | |
|---|---|---|
help [cmd] | 列出命令或显示特定命令的帮助 | |
clear | 清除终端输出 | |
scene [name] | 显示/加载场景 | |
fps | 显示当前FPS | |
mem | 详细的内存使用情况（托管堆、分配、GC统计数据） | |
sysinfo | 系统信息（CPU、GPU、RAM、分辨率、质量） | |
gc | 强制垃圾收集 | |
time.scale [val] | 获取/设置时间刻度 | |
obj.find | 查找游戏对象 | |
obj.inspect | 检查部件 | |
obj.toggle | 切换活动状态 | |
| `obj.get | ||
| ` | 获取组件属性（例如。， obj.get Main Camera Transform.position.x) | |
| `obj.set | ||
| ` | 设置组件属性 | |
obj.members | 列出组件成员 | |
| `watch | ||
| ` | 添加实时手表表情 | |
unwatch | 删除手表表情 | |
debug.toggle [name] | 切换调试可视化标志 | |
alias [name] [cmd] | 创建/列出命令别名 | |
| `logs.capture [on\ | off]` | 切换Unity日志捕获 |
终端功能
- 选项卡完成 用于命令和参数（游戏对象名称、场景、组件、别名）
- 命令历史 带有向上/向下箭头（在会话中持续存在）
- 剪贴板 支持（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网桥>服务器）
| 设置 | 默认值 | 说明 |
|---|---|---|
| 端口 | 7890 | HTTP服务器端口 |
| 最大日志条目数 | 500 | 内存中保存的最大日志条目数 |
| 自动启动 | false | Unity打开时自动启动服务器 |
| 包括堆栈跟踪 | true | 在日志条目中包含堆栈跟踪 |
| 包括警告 | true | 跟踪编译警告（不仅仅是错误） |
| 屏幕截图质量 | 低 | 默认屏幕截图质量（低/中/高） |
| 屏幕截图清理 | 30分钟 | 自动删除在此之前的屏幕截图（0=禁用） |
环境变量（MCP服务器）
| 变量 | 默认值 | 描述 |
|---|---|---|
UNITY_HOST | 127.0.0.1 | Unity HTTP服务器主机 |
UNITY_PORT | 7890 | Unity HTTP服务器端口 |
UNITY_TIMEOUT | 5000 | 请求超时（毫秒） |
建筑
+-------------------+ +-------------------+
| Cursor || MCP Server |
| (AI Agent) | (stdio) | (Node.js) |
+-------------------+ +---------+---------+
|
HTTP REST
|
+---------+---------+
| Unity Editor |
| (HTTP Server) |
| Port 7890 |
+-------------------+请求流程：
- AI通过MCP协议（stdio）发送工具调用
- MCP服务器（TypeScript）转换为HTTP请求
- Unity HTTP服务器在后台线程上接收
- 直接处理的只读请求；排队等待主线程的操作
- 响应通过相同的路径返回
故障排除
“无法连接到Unity”
- 确保Unity编辑器已打开
- 检查MCP网桥服务器是否正在运行（窗口>Unity MCP网桥>服务器）
- 验证Unity和MCP服务器配置中的端口是否匹配
“请求超时”
- Unity可能正忙（编译、加载资产）
- 尝试在Unity窗口中单击“唤醒它”
- 增加
UNITY_TIMEOUT慢速操作的环境变量
端口已在使用中
- 在Unity MCP网桥设置中更改端口
- 更新
UNITY_PORT在您的MCP服务器配置或环境中
代码更改后服务器停止
这是意料之中的——Unity会重新编译并重新加载域。如果 自动启动 启用后，服务器会自动重新启动。
屏幕截图为空或错误
- 确保场景中存在摄像头（游戏视图需要摄像头）
- 对于“场景视图”屏幕截图，请确保“场景视图（Scene View）”窗口已打开
- 尝试使用
unity_frame_selected在拍摄之前定位相机
贡献
欢迎投稿！请随时提交拉取请求。
- 克隆该仓库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
支持
如果你觉得这个项目有用，可以考虑支持它的开发：
______________________________________________________________________
Made with Claude AI assistance