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-mcpUnity 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 秒不够用命令被截断客户端表现为转圈后报错或卡死无响应。改法两个环境变量直接覆盖参数默认值环境变量作用connection_timeout300 秒UNITY_MCP_CONNECTION_TIMEOUT单条命令的 socket 接收超时command_total_timeout600 秒UNITY_MCP_COMMAND_TOTAL_TIMEOUT含重试在内的总时间上限在启动 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 路径与服务器源码覆盖机器上 uvPython 包管理器不在默认 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考