企业官网建设流程全解析

Unity MCP 连不上？3 步排查端口占用 + 4 个调优参数

【免费下载链接】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 编辑器的桥接服务器，让 Claude、Cursor 等 LLM 直接操作场景、资源和脚本。如果你的客户端一直转圈、工具调用卡住、或连接反复断开，这篇指南从端口冲突、超时设置到桥接稳定性逐项排障，改完即生效。

客户端一直转圈：端口被占是最常见原因

默认 6400 被占时，MCP 会自动换端口，多数情况不用你动手

Unity MCP 默认监听 6400 端口（PortManager中的DefaultPort常量）。当 6400 被其他进程占用时，FindAvailablePort从 6401 起逐个探测，最多尝试 100 个端口。选中后写入用户目录~/.unity-mcp/下的注册表 JSON，下次启动直接复用，不会每次随机漂移。端口分配与持久化的完整逻辑见 PortManager.cs，它负责探测可用端口并把结果落盘。

端口被自己的旧桥接占用：等 3 秒再下结论

域重载（domain reload）后，旧监听器的 socket 释放比新桥接启动慢，Windows 和 macOS 上尤为明显。MCP 内置 3 秒宽限期（BusyPortFallbackWindowSeconds = 3.0）：端口"被占"状态持续不到 3 秒就继续等，不会误判为外部冲突去换端口。你偶尔看到连接延迟几秒才建立，属于正常行为。

手动指定端口：两步搞定

自动机制不满足时（比如需要固定端口配防火墙规则），在编辑器窗口 Connection 区的 Unity Socket Port 输入框填入目标端口号（建议 1024-65535），点击应用。该输入框与连接状态显示由 McpConnectionSection.cs 控制，同时负责传输协议切换和版本不匹配警告。

工具调用卡住不动：把超时参数调到够用

现象：长任务（大资源导入、跑测试、批量编辑）中途断连

默认单命令 socket 接收超时是 300 秒（connection_timeout）。项目里跑大型资源导入或长时间 Play Mode 测试时，300 秒不够用，命令被截断，客户端表现为转圈后报错或卡死无响应。

改法：两个环境变量直接覆盖

在启动 MCP 服务器的 shell 中导出对应变量即可。注意command_total_timeout必须 ≥connection_timeout，否则总上限会先触发。所有可调参数集中在 config.py，它是服务端唯一配置入口，涵盖网络、传输、重试、遥测等全部字段。

预期效果

超时上调后，长任务不再被中途切断，客户端等待时间延长但不会再出现"假死"。如果你的任务普遍在 5 分钟内完成，默认 300 秒已经够用，不必盲目调大。

桥接反复断开重启：重试与心跳参数

现象：Unity 域重载期间客户端报"连接被重置"

Unity 重编译脚本或切换场景时触发域重载，桥接暂时不可用。MCP 默认"礼貌重试"策略：间隔 250 毫秒（reload_retry_ms），最多 40 次（reload_max_retries），总窗口约 10 秒。大型项目重载时间超过 10 秒时，40 次不够，客户端就会看到连接断开。

改法：延长重试窗口

调整reload_retry_ms（每次间隔）和reload_max_retries（最大次数）。重载慢的项目把次数提到 80-100，间隔保持 250 毫秒，总窗口扩展到 20-25 秒，覆盖绝大多数场景。

现象：stdio 模式下心跳丢失、帧超时

stdio 传输有独立握手机制：handshake_timeout默认 1 秒，heartbeat_timeout默认 2 秒，max_heartbeat_frames默认 16 帧。本地回环偶发抖动时，把heartbeat_timeout放宽到 3-5 秒，避免误判为连接死亡而触发重连。

只有特殊需求才动的 4 个开关

UV 路径与服务器源码覆盖

机器上 uv（Python 包管理器）不在默认 PATH，或你想用本地 fork 的 Server 代码调试时，在 Advanced Settings 区分别设置 UVX Path 和 Server Source。普通用户保持默认即可。

允许局域网绑定

默认 HTTP 本地模式只监听 127.0.0.1。AI 客户端跑在另一台机器上时，打开"Allow LAN Bind"开关让服务器绑定局域网地址，并确认防火墙放行对应端口。

截图输出目录与包部署

Screenshots Folder 控制截图工具输出位置（默认 Assets/Screenshots）。Package Source 的 Deploy/Restore 按钮用于在开发机与 Unity 项目间同步桥接包，适合多人协作调试同一套自定义工具。

高级设置区的全部控件定义在 McpAdvancedSection.uxml，包含上述路径覆盖、开关和部署按钮。

动手前的 7 项自查清单

• 6400 端口未被其他进程占用，或已手动指定可用端口
• ~/.unity-mcp/下端口注册表文件指向当前项目路径（换项目后端口会变）
• 长任务场景下connection_timeout和command_total_timeout已按实际耗时上调
• 大型项目域重载时间 > 10 秒时，reload_max_retries已相应增大
• 跨机器访问时已开启 Allow LAN Bind 且防火墙放行
• Advanced Settings 中 Debug Logging 已开启，便于复现问题时抓日志
• 客户端配置文件 mcp.json 中的端口号与 Unity 窗口显示一致

【免费下载链接】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