桌面 GIS 接入 MCP 时，故障不一定发生在模型调用。QGIS 内的插件、外部 MCP server、客户端配置和包管理器各自运行；只要把“每次启动都更新”设成默认，现场没有网络时，原本可用的项目也可能根本连不上。
QGIS MCP v0.4.3 于 2026 年 6 月 11 日发布，最关键的修复是让 MCP server 不再因离线而无法启动。发布说明称，旧的默认与推荐配置包含 --refresh-package，它会让 uvx 每次启动都从 GitHub 重新解析包；该参数已从默认配置中移除。这个改动看似只是启动参数调整，却提供了一条更稳妥的桌面 GIS 运维原则：启动已验证的版本，与主动更新版本，应该是两件事。
QGIS MCP GitHub 仓库预览图
图：QGIS MCP 的 GitHub 仓库预览图，来源：项目仓库页面。
核心机制：默认启动使用缓存，更新成为明确动作
包刷新适合在受控时间取得新版本，却不适合作为每一次打开项目的前置条件。v0.4.3 的发布说明将自动更新保留为 configurator 中可选的勾选项；需要人工更新时，仍可显式运行带 --refresh-package 的 uvx 命令，然后重启 MCP 客户端。对于已有配置，插件还提供一次性提示，帮助移除旧的刷新参数。
这样拆分后，团队可以把日常启动视为“使用已验证缓存”的动作，把更新视为“在网络、日志和回退条件具备时拉取新包”的变更。没有网络时，正常启动不应为了寻找新版本而失败；有网络时，也不应在没有测试项目的情况下让每位用户静默得到不同版本。
GIS 场景：把外业前一晚的升级变成可回退步骤
设想一个要在外业前检查地块、图层和布局的 QGIS 项目。办公室网络正常，现场网络不稳定。若团队在每台机器的 MCP 配置中默认刷新包，出发前看似正常的更新可能在现场变成 server 无法启动；更难排查的是，QGIS 插件与外部 server 的版本也可能不再匹配。
可把升级限制在一台测试机：复制脱敏项目，记录当前插件版本、客户端配置文件和已缓存 server 的版本；主动运行更新命令并重启客户端；执行一个只读的连通检查、图层列表读取与地图渲染；确认后再推广。若检查失败，恢复先前配置和缓存版本，并用离线网络条件重新启动一次。将“断网能否打开已验证项目”纳入验收，才能真正检验 v0.4.3 所修复的路径。
Windows 本地安装先检查链接，再诊断代码
v0.4.3 还修复了 configurator 对 Windows junction 的识别。发布说明解释，当用户未开启 Developer Mode 而通过 install.py 安装插件时，安装方式会使用 mklink /J 创建 junction；过去 configurator 会把这种链接一直显示为“未链接”。新版本会跟随 junction，并在“Re-link Plugin”时优先回退到 junction，同时安全移除已有 junction。
这带来一个很实际的排错顺序：如果本地 clone 开发安装显示异常，不要先重装 QGIS 或修改 Python；先确认插件目录、junction 目标和 configurator 看到的是不是同一位置。对 Windows 团队，链接类型是部署状态的一部分，应连同 QGIS profile、插件路径与仓库 commit 一起记录。
连接徽章只代表通道，不代表业务成功
该版本新增工具栏连接徽章，实时显示已连接的 MCP 客户端数量，发布说明列举了 Claude Code、Claude Desktop、Gemini CLI 与 Codex 等客户端。这个信号适合做首层诊断：QGIS 端是否正在接收外部连接，重启后连接是否恢复。
但连接数不能证明 GIS 操作正确。一个客户端连接后仍可能使用错误项目、没有读图层权限、引用了过期路径或在坐标系转换处出错。因此，连接徽章之后至少还要运行三个可读检查：读取当前项目名称和 CRS；列出预期图层及要素数量；渲染固定范围的地图截图并与基线比较。涉及 Processing、编辑或导出时，再单独加入预览、人工确认和可撤销输出目录。
一份最小升级与回退清单
- 记录 QGIS 版本、插件版本、MCP 客户端和当前配置文件副本。
- 在可联网的测试机主动更新；不要把刷新参数设为所有日常启动的默认条件。
- 重启 MCP 客户端，确认 QGIS 工具栏连接徽章出现预期客户端数。
- 用脱敏项目执行只读的项目、图层、CRS 和固定视图渲染检查。
- 在断网条件下重启一次，确认已验证的缓存版本仍能启动。
- Windows 本地 clone 安装异常时，先核查 junction 与插件目录，再做重装或代码诊断。
- 将旧配置、旧缓存版本和测试结果保留到新版本在实际项目中稳定运行后。
风险边界
v0.4.3 的发布说明描述的是该版本的启动、安装识别和连接提示改动，不保证所有 QGIS、操作系统或 MCP 客户端组合都有相同行为。离线启动只说明刷新包不再是必要前置条件，不代表模型服务、私有数据源或其他依赖也可离线使用。连接徽章也不能取代数据读写权限、坐标参考系和空间结果的业务验证。
结论
QGIS MCP v0.4.3 的价值不只是修复了一个参数：它把“稳定启动”和“主动更新”分开了。对桌面 GIS 团队，先固定可用版本、在测试机更新、验证只读空间结果、再用断网重启检验回退，能让 MCP 从一次可演示的连接，变成可维护的工作台能力。