Unity MCP 连接问题排查与性能调优：从连不上到跑得顺

Unity MCP 连接问题排查与性能调优：从连不上到跑得顺

【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp

Unity MCP 是 AI 助手与 Unity 编辑器之间的桥（MCP 即 Model Context Protocol，让大模型获得操作工具的一套协议）：装好后 AI 就能管理资源、改场景、写脚本。本文聚焦 Unity MCP 配置中最头疼的两件事：连不上怎么排、连上了怎么调得更快。

连不上？先按这个思路排查

连接失败九成是端口问题，但别上来就换端口——按"看端口 → 验配置 → 查日志"三步走，大部分情况第一步就定位了。

1. 看端口：打开 Unity 编辑器菜单里的 MCP For Unity 窗口，连接区显示的端口号就是当前值。再执行一条命令确认谁占了它：netstat -ano | findstr 6400（macOS/Linux 用lsof -i :6400）。
   • 是 Unity 自己的进程占着：多半是上次域重载后旧监听器没放掉，等几秒重连即可，代码里专门留了 3 秒窗口处理这种"自己撞自己"的情况。
   • 是别的程序占着：走下一节的手动换端口。
2. 验配置：确认连接已建立、传输方式选对了。HTTP 传输下，高级设置区的"自动启动"没勾的话，编辑器打开后服务器不会自己跑，状态会一直是断开。
3. 查日志：打开 Unity 控制台的 MCP 输出，重点找in use、timeout、reload这类字样。要更多细节，在高级设置区勾选 Show Debug Logs，日志量会明显变大。

三处都正常还是连不上，把编辑器完整重启一次再测。

端口一次讲透：默认值、自动换端口与手动固定

默认端口是 6400，被占会自动顺延最多试 100 个。这套逻辑在 PortManager.cs 里：

• 首选 6400，可用就直接用；
• 被占则从 6401 开始逐个探测（IsPortAvailable做一次真实试绑定），找到即用，并写进用户目录下的~/.unity-mcp/里按项目记着；
• 每个项目独立记忆端口，多项目并行不会互相踩端口。

手动固定端口的操作步骤：

1. 打开 MCP For Unity 编辑窗口的连接区；
2. 在 Unity 端口输入框里填你想要的端口号（建议 1024–65535）；
3. 失焦即生效——若端口被占，会弹 "Port Unavailable" 并回滚到当前值，不占用就写入并持久化；
4. 用连接区的测试连接按钮确认通了。

配置参数调优清单

性能参数集中在 Python 端，改环境变量就行，不用动代码。服务器配置类ServerConfig定义在 Server/src/core/config.py，常用旋钮：

• UNITY_MCP_CONNECTION_TIMEOUT：单条命令的接收超时，默认 300 秒。大批量导入、跑测试被掐断就调大它；
• UNITY_MCP_COMMAND_TOTAL_TIMEOUT：含重试在内的总时限，默认 600 秒，务必大于上一条；
• 日志级别：默认 INFO，排查时再临时调高，平时别开 DEBUG——日志是 I/O 大户，常开白拖慢响应。

环境与资源同样值得整理：

• 关掉其他监听 6400–6500 区间的常驻服务，减少撞端口概率；
• 临时开了日志记录（会把每次工具执行写进Assets/UnityMCP/Log/mcp.log）用完就关，日志膨胀会拖慢编辑器；
• 编辑器与服务器同机跑时，给 Unity 让出内存比任何参数都有效。

高阶玩法：按场景定制服务器行为

高级设置区就是手动配置面板，常见定制需求都在这里。

• 换传输方式：连接区下拉里可切 stdio、HTTP Local、HTTP Remote。stdio 是客户端直接拉起进程，最省心；HTTP 适合需要多客户端或远程接入的场景，配"自动启动"后编辑器一开服务器就跟上；
• 改服务器源：高级设置区的 Server Source Override 指向本地Server目录（含 pyproject.toml），想试自改的服务器代码时用；
• 脚本校验等级：Basic 到 Strict 四档，决定 AI 改代码后的检查深度——追求响应快选 Basic，质量优先选 Comprehensive。

原则：只动你需要的项，改完点测试连接确认健康状态变绿。

排查速查表

从端口查起，端口 → 配置 → 日志，多数 Unity MCP 连接问题在前两步就有答案 🔧

【免费下载链接】unity-mcpUnity MCP acts as a bridge between AI assistants and your Unity Editor. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.项目地址: https://gitcode.com/GitHub_Trending/un/unity-mcp