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-mcpMCP for Unity 是把 AI 助手Claude 等客户端与 Unity Editor 连起来的桥梁让 LLM 能管理资源、控制场景、编辑脚本。如果你的客户端连不上 Unity Editor或者想让默认配置更稳定省心下面四节内容按先解决最痛的问题、再讲原理的顺序带你走一遍。端口冲突快速定位自动选端口的机制最常见的连接故障是端口被占用——可以理解成门牌号被别人占了。好消息是大部分情况项目会自动处理你不需要动手。默认端口 6400 与 100 个端口的扫描逻辑Unity MCP 的默认端口是 6400。服务启动时PortManager先检查 6400 是否可用被占就自动从 6401 开始逐个向上扫描最多尝试 100 个端口取第一个空闲的。这个可用判断不是猜测而是真正创建测试监听器去尝试绑定由操作系统给出结论在 macOS 上还会额外开启独占绑定避免多个进程误报可用。相关逻辑在MCPForUnity/Editor/Helpers/PortManager.cs中可以看到。端口为什么会变端口注册表与 3 秒宽限窗口选定的端口会按项目记录在用户主目录的~/.unity-mcp/下——每个 Unity 项目一个独立文件所以重新打开项目时用的是同一个端口客户端不会漂走。还有一个容易忽略的细节域重载后旧的监听器释放套接字可能慢一拍Windows/macOS 尤其明显所以服务器会容忍最长 3 秒的端口仍被占用期间不急着换端口避免一次短暂冲突就把客户端的地址改没了。反过来如果你想手动指定端口被占用的端口会被直接拒绝必须先换一个空闲的。连接失败的诊断三步排查流程客户端连不上 Editor 时别盲目重启按这个顺序来。先确认走的是哪种传输和哪个端口MCP for Unity 有两种传输方式HTTP带 WebSocket 推送适合远程或多客户端和 stdio由客户端直接拉起进程适合本地单机。当前启用哪种由编辑器里的一个设置项决定当前实际在用的端口可以在编辑器窗口的状态区看到。第一步永远是确认你以为在用的传输和端口跟实际状态一致——不少连不上其实就是客户端还指着旧地址。用内置验证检查 Ping 与握手编辑器窗口自带连接验证它会依次检查两件事端口是否响应 ping、协议握手是否通过结果会直接展示错误信息和细节。验证失败时先读返回的错误文本需要更细的线索时打开调试日志开关MCPForUnity/Editor/Constants/EditorPrefKeys.cs里的DebugLogs设置项Unity 控制台里就能看到端口探测、保存、传输启停的完整过程。配置改在哪里客户端侧与编辑器侧配置实际分两块AI 客户端里写入的内容和 Unity 编辑器内的设置。mcpServers 只有 4 个字段客户端侧只需要关心 McpConfig 里的mcpServers结构每个服务条目最多 4 个字段command要启动的程序、args参数、type部分客户端要求的传输类型标记、urlHTTP 传输模式下用的地址。用不到的字段不会写进配置。类定义在MCPForUnity/Editor/Models/McpConfig.cs非常简洁。HTTP 与 stdio 怎么选本地单机调试选 stdio 最省心客户端直接拉起服务器不存在端口问题。HTTP 则是 Editor 内常驻的服务通过 WebSocket 推送实时状态适合多客户端或远程场景。切换在编辑器窗口的设置区完成切换时旧的传输会被自动停掉避免残留进程抢端口。两种模式的编排逻辑在MCPForUnity/Editor/Services/BridgeControlService.cs中可以看到。省掉排障时间的几个小习惯这些不算高级技巧但能减少大部分弯路。多项目共存时让端口保持稳定按项目区分的端口注册表意味着同时打开两个 Unity 项目它们各用各的端口互不挤占。真正要小心的是同一个项目开了两个 Editor 实例或者之前没关干净的旧进程——它们会抢同一个门牌号表现为端口反复被占用。出问题时先看日志再动配置调试开关打开后PortManager的每个端口决策命中默认端口、扫描到可用端口、保存成功或失败都会打一行日志。出问题时先找最近一条与端口相关的记录就能判断是被别的程序占了还是自己的旧进程还没释放比反复重启 Editor 快得多。要点回顾默认端口 6400冲突时自动向上扫描最多 100 个端口结果按项目保存在~/.unity-mcp/一般无需手动干预。域重载可能造成短暂占用3 秒宽限窗口防止端口被无谓更换手动指定端口时被占用的端口会被拒绝。诊断顺序确认传输模式 → 内置验证ping 握手→ 打开调试日志看端口决策记录。客户端配置只有 command / args / type / url 四个字段本地单机选 stdio远程或多客户端选 HTTP。故障时先查最近的端口相关日志判断是外部占用还是旧进程未释放再决定动作。把这些吃透后回到编辑器窗口的设置区按你的环境微调端口与传输方式即可——遇到新问题时对照上面各节的机制定位原因会快很多。【免费下载链接】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），仅供参考