MCP for Unity v5 迁移指南从 UnityMcpBridge 平滑升级到全新 MCPForUnity 包结构【免费下载链接】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本文以官方 v5 迁移文档website/docs/migrations/v5.md为骨架结合仓库内真实源码与配置系统讲解如何将旧版UnityMcpBridge安装平滑迁移到新版MCPForUnity包结构覆盖卸载旧包、从新路径安装、重建 MCP Server、迁移验证与故障排查全流程。读完本文你将掌握一套可复现的 v5 升级路径并理解迁移背后 Unity 编辑器自动执行的配置改写机制能在升级异常时快速定位问题。为什么需要迁移v5 包结构发生了根本变化从 v4 及更早版本升级到 v5最核心的变化是包的安装路径与目录结构旧版以UnityMcpBridge文件夹的形式存在而 v5 开始统一从MCPForUnity文件夹安装。这一调整把编辑器插件MCPForUnity/Editor、运行时库MCPForUnity/Runtime与 Python MCP ServerServer/收纳进一套更清晰的包结构中。从当前仓库的 MCPForUnity/package.json 可以看到新包的身份信息{ name: com.coplaydev.unity-mcp, version: 10.2.1-beta.1, displayName: MCP for Unity, description: A bridge that connects AI assistants to Unity via the MCP (Model Context Protocol)., unity: 2021.3 }即新包的包名为com.coplaydev.unity-mcp展示名为 MCP for Unity最低支持的 Unity 版本为 2021.3。迁移完成后你在 Package Manager 中看到的应当是这个展示名与MCPForUnity路径而不是旧版遗留的名称。说明本指南面向 v5 迁移这一历史节点但当前仓库的包已迭代到 10.2.1-beta.1。迁移完成后建议继续按官方文档的后续章节了解Window MCP for Unity编辑器窗口详见 MCPForUnity/README.md与 Python Server 的维护方式。迁移前准备在动手前建议先确认以下几点避免迁移中断Unity 版本确认你的 Unity 版本不低于 2021.3见MCPForUnity/package.json的unity: 2021.3字段。Python 运行环境v5 的 MCP Server 由 Python 实现仓库Server/目录迁移后重建 Server 需要 Python 与 uv/uvx 可用。仓库中 DependencyManager.cs 会在编辑器内自动检查这些依赖缺失时会在 Setup 窗口中提示安装。旧版配置心中有数v5 会在首次启动时自动改写旧版遗留的客户端配置详见下文迁移背后的自动逻辑迁移前无需手动备份但了解这一点有助于你理解升级后客户端配置为何会变化。Step 1卸载旧包旧版包通过 Package Manager 卸载操作路径如下打开 Unity 的包管理器菜单Window Package Manager在左上角下拉框中切换到Packages: In Project在包列表中找到MCP for Unity旧版安装条目点击Remove按钮卸载旧版包。卸载后旧版UnityMcpBridge相关的编辑器脚本不再参与编译为下一步安装新包腾出干净的包空间。Step 2从新路径安装新版包v5 开始包通过 Git URL 安装且 URL 中明确指定了子目录?path/MCPForUnity这正是新旧版本分水岭的关键所在在 Package Manager 窗口左上角点击按钮选择Add package from git URL...输入以下 URLhttps://github.com/CoplayDev/unity-mcp.git?path/MCPForUnity点击Add完成安装。安装完成后Unity 会把仓库中MCPForUnity子目录解析为本地包对应包名com.coplaydev.unity-mcp。这也解释了为什么当前仓库根目录旁同时存在CustomTools/、TestProjects/等目录——它们并不属于包本体安装时只有MCPForUnity被导入。Step 3重建 MCP Server新包安装后编辑器脚本首次编译会触发自动初始化SetupWindowServiceSetupWindowService.cs会在[InitializeOnLoad]静态构造函数中检查MCPForUnity.SetupCompleted/MCPForUnity.SetupDismissed两个 EditorPrefs 键若从未完成过设置则自动弹出 Setup 窗口。不过要让 MCP Server 以当前版本运行还需要手动重建在 Unity 菜单栏进入Window MCP for Unity Open MCP Window菜单入口定义在 MCPForUnityMenu.cs快捷键为CtrlShiftM/CmdShiftM在窗口的 Server Status 区域点击Rebuild MCP Server按钮。该按钮会基于 Python 重新构建/安装 MCP Server按 MCPForUnity/README.md 的描述它会重建基于 Python 的 MCP server并确保客户端通过uvx以当前包版本启动 server构建完成后窗口应显示成功提示。重建的本质是把客户端的 MCP 配置改写为通过uvx从当前包的 Git 源启动 server。这一逻辑集中在 ConfigJsonBuilder.csstdio 模式下它写入{ command: uvx 路径, args: [--from, git-url, mcp-for-unity, --transport, stdio] }HTTP 模式下则写入url字段。换句话说重建 让所有 MCP 客户端指向与当前包版本一致的 server 启动方式。验证迁移是否成功完成三步操作后按以下清单逐项确认包列表Package Manager 中显示的包名为MCP for Unitycom.coplaydev.unity-mcp包路径包详情中的位置指向新的MCPForUnity路径而不是UnityMcpBridge功能冒烟打开Window MCP for Unity窗口确认 Server Status 为 Installed、Unity Bridge 可启动并尝试让某个 MCP 客户端如 Cursor、VS Code、Claude Code调用一个简单工具确认链路可用。迁移背后的自动逻辑两个源码级的隐形迁移器v5 迁移并非只有手动三步。仓库MCPForUnity/Editor/Migrations/目录下有两个[InitializeOnLoad]静态迁移器会在编辑器启动时自动完成旧配置的兜底迁移1. LegacyServerSrcMigration清理旧版内嵌 Server 配置LegacyServerSrcMigration.cs 负责检测旧版内嵌 Server遗留的 EditorPrefs 键MCPForUnity.ServerSrcMCPForUnity.UseEmbeddedServer这两个键在 EditorPrefKeys.cs 中被定义为 v5 迁移的目标清理对象。逻辑如下编辑器启动后非批处理模式若检测到这两个键存在则调用MCPServiceLocator.Client.ConfigureAllDetectedClients()把所有已检测到的 MCP 客户端配置统一改写为新版启动方式随后删除这两个遗留键防止每次启动重复迁移。若部分客户端改写失败会在 Console 输出警告并仍然删除旧键避免迁移死循环失败客户端可后续手动配置。这意味着大部分用户的客户端配置在首次启动新版时会被自动修正。2. StdIoVersionMigration按包版本同步 stdio 客户端StdIoVersionMigration.cs 解决另一个问题MCP 客户端配置里写死的 server 启动参数需要跟随包版本更新。它读取EditorPrefKeys.LastStdIoUpgradeVersion将当前包版本来自AssetPathUtility.GetPackageVersion()与上次改写的版本比对若版本一致跳过若版本不同遍历 McpClientRegistry 中的所有配置器CLI 型客户端如 Claude Code CLI调用CheckStatus(attemptAutoRewrite: true)自动重新注册JSON 文件型客户端先解析配置文件确认unityMCP节点使用的是command字段即 stdio 模式后重新调用ConfigureClient改写若当前传输设为 HTTP则跳过不支持 HTTP 的客户端全部成功后再记录当前版本号避免重复执行。**这条自动逻辑与 v5 迁移步骤 3 的关系是**手动Rebuild MCP Server是即时生效的主动操作而StdIoVersionMigration是每次编辑器启动时的版本同步保险丝——两者共同保证客户端配置永远与当前包版本一致。故障排查若迁移后 MCP 无法正常工作按以下顺序排查查看 Unity Console迁移器LegacyServerSrcMigration/StdIoVersionMigration与配置改写过程都会通过McpLog输出日志Console 中带有MCPForUnity前缀的 Warning/Error 是定位问题的最直接线索确认 Python 依赖完整MCP Server 依赖 Python 与 uv/uvx。仓库的 DependencyManager.cs 负责检查缺失时使用 Setup 窗口或菜单Window MCP for Unity Local Setup Window安装uv 安装器实现在 UvInstaller.cs重试重建网络波动或临时缓存问题可能导致重建失败回到 MCP 窗口再次点击Rebuild MCP Server重启 Unity重启后编辑器会重新触发[InitializeOnLoad]初始化与两个自动迁移器配置改写有失败时会在下一次启动自动重试StdIoVersionMigration在失败时故意不记录版本号保证下次会话重试核对客户端配置若某个客户端始终连不上检查其配置文件中的unityMCP节点是否为uvx --from git-url mcp-for-unity形式stdio或正确的urlHTTP必要时使用窗口中的Auto Configure/Manual Setup重新生成。小结v5 迁移本质上是一次包结构 启动方式的统一包从UnityMcpBridge变为MCPForUnitycom.coplaydev.unity-mcp安装方式变为git URL ?path/MCPForUnity而 Server 统一由uvx按当前包版本启动。手动三步卸载 → 新路径安装 → 重建 Server加上两个自动迁移器LegacyServerSrcMigration、StdIoVersionMigration构成了从旧版平滑过渡的完整闭环。理解这套机制后无论是首次升级 v5还是日后每次包升级你都能清楚知道谁在改我的配置、为什么改、改错了去哪查。【免费下载链接】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），仅供参考