1. QGIS 接 MCP 到底解决什么问题QGIS 本身已经很强图层加载、栅格裁剪、矢量叠加、坐标转换这些操作都能做但它的短板在于「人机交互」这一层。你想让 QGIS 帮你完成一句自然语言描述的任务比如「把这份土地利用栅格按坡度重分类再统计各等级面积」传统做法是你自己拆解成 Processing Toolbox 里的一串算法手动配参数、手动跑、手动导出。QGIS MCP 要解决的就是把这段「拆解 调参 执行」的活交给模型你只负责说清楚要什么。MCP 是 Model Context Protocol 的缩写你可以把它理解成模型和本地软件之间的一根标准数据线。模型本身不会直接操作 QGIS它只能输出结构化的调用意图MCP 服务端负责把这些意图翻译成 QGIS 能执行的 Python 或 Processing 调用再把执行结果回传给模型。qgis_mcp 这个项目就是给 QGIS 装了一个 MCP 服务端插件让 QGIS 暴露出一组可被模型调用的工具接口。适合谁用三类人最直接受益。第一类是经常做重复性空间分析的人比如每周都要跑同一套缓冲区 叠加 统计的流程用 MCP 可以把这套流程固化成一两句指令。第二类是不太熟 QGIS Python API 但懂业务逻辑的人你描述需求模型帮你生成并执行调用。第三类是已经在用 Cline、Claude Code 这类编码 Agent 的人你希望 Agent 不只会写代码还能直接驱动本地 GIS 软件干活。这里有个关键点容易被忽略MCP 服务端和模型之间是要走网络请求的模型 API 的 endpoint 和鉴权方式决定了这条链路稳不稳、好不好管。默认很多教程会让你分别去各家模型厂商申请 Key一个项目里塞好几个 Key换模型就得改配置。把 endpoint 统一到 TaoToken 的 Key/API 通道之后QGIS MCP 这条链路只需要维护一份鉴权信息模型切换只改一个 Model ID这是本篇要重点落地的部分。我试过把 qgis_mcp 的默认模型通道换成统一 Key 通道整个配置改动量比想象中小核心就是三处MCP 服务端读的模型配置、客户端 Agent 的 Provider 设置、以及 QGIS 插件本身的启动参数。下面按可复现的顺序拆开讲。2. TaoToken 前置准备与 qgis_mcp 插件安装在动 QGIS 之前先把模型通道这层准备好否则后面配置 MCP 服务端时会来回改。TaoToken 的定位是统一 Key/API 通道你在这里拿到一个 Key就能通过兼容 OpenAI 风格的接口去调用不同模型。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填的就是这个干净地址。你需要做两件事注册后在控制台创建一个 API Key然后确认你要用的 Model ID。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Model ID 这块建议先在模型对话页确认一下当前可用的模型名地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 避免配置里写了一个不存在的名字导致后面 404。拿到 Key 之后回到 QGIS 侧。qgis_mcp 插件来自 GitHub 上的 jjsantos01/qgis_mcp 项目QGIS 本体从官网下载安装即可。插件安装有个小坑GitHub 上给的是源码目录不是打包好的 zip。你需要把 qgis_mcp_plugin 这个文件夹单独压缩成 qgis_mcp_plugin.zip压缩时注意是「压缩文件夹本身的内容」让 zip 根目录下直接能看到 metadata.txt 和init.py而不是多套一层 qgis_mcp_plugin 目录。套错一层QGIS 安装时会提示找不到插件元数据。安装路径是 QGIS 菜单 Plugins - Manage and Install Plugins切到 Install from ZIP 标签页选中你压好的 zip点 Install Plugin。装完工具栏会出现 QGIS_MCP 图标点开右侧浮动面板面板里有个 Start Server 按钮默认监听端口 9876。这个端口后面 MCP 客户端配置里要对应上如果你本机 9876 被占用可以在插件配置里改但改完记得同步改客户端。这里要提醒一句插件启动的服务是本机回环服务只在你自己的机器上监听不要把它暴露到公网。MCP 的设计前提就是本地可信环境模型通过客户端 Agent 间接调用不是让外部直接连你的 QGIS。前置准备做完你手上应该有三样东西TaoToken 的 API Key、确认可用的 Model ID、QGIS 里已经 Start Server 的 9876 端口。接下来进入配置环节。3. 可复制的 MCP 服务端与客户端配置这一节是整篇的核心配置写错一个字段后面验证就会卡住。qgis_mcp 的链路里有两个配置文件要动一个是 MCP 客户端以 Cline 为例的 cline_mcp_settings.json一个是模型 Provider 的接入配置。如果你用的是 Claude Code 或 Codex 这类 Agent配置位置不同但字段逻辑一致关键是 Base URL、Key、Model ID 三件套要写全。先看 MCP 客户端里注册 qgis_mcp 服务端的片段。Cline 的 MCP 配置在 VS Code 的设置里点 MCPServers - Configure MCP Servers 会打开 cline_mcp_settings.json。qgis_mcp 项目 README 给的是 stdio 方式启动一个 Python 服务你需要把命令和参数填进去。下面是一个可复制的 JSON 片段路径按你本机实际解压位置改{ mcpServers: { qgis_mcp: { command: python, args: [ D:/qgis_mcp/src/qgis_mcp/server.py ], env: { QGIS_MCP_HOST: 127.0.0.1, QGIS_MCP_PORT: 9876 }, disabled: false, autoApprove: [] } } }注意 args 里的 server.py 路径要指向你实际解压出来的 qgis_mcp 源码目录Windows 下用正斜杠或双反斜杠都行单反斜杠会被 JSON 转义吃掉。env 里的 HOST 和 PORT 要和 QGIS 插件面板里 Start Server 的监听地址一致默认就是 127.0.0.1:9876。然后是模型 Provider 的接入配置。Cline 的 Settings 里选 API Provider如果你要用统一 Key 通道选 OpenAI Compatible 这类选项然后填三件套{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的TaoTokenKey, openAiModelId: 你确认过的ModelID }Base URL 填 https://taotoken.net/api 不要带结尾斜杠也不要带 UTM 参数。Key 就是你在 API Keys 页面创建的那串。Model ID 填你在模型对话页确认过的名字。这三件套写全缺一个都会在请求时报错。如果你用的是 Claude Code配置走的是 settings 文件Base URL 和 Key 的字段名不同但语义一样Model ID 同样要显式指定。Codex 的话看 auth.json里面 api_key 和 base_url 两个字段对应上即可。不管哪个客户端判断配置对不对的标准只有一个客户端能成功发起一次模型请求并拿到回复。配置写完保存回到 Cline 的 MCP Servers 面板Installed 标签页里应该能看到 qgis_mcp 处于 connected 状态。如果显示红色或一直转圈先别急着怀疑模型通道大概率是 server.py 路径不对或 Python 环境缺依赖。qgis_mcp 的 server.py 依赖 mcp 这个 Python 包你需要先在对应 Python 环境里 pip install mcp否则进程一起来就退出客户端自然连不上。这一步做完链路的两端就都配好了一端是 QGIS 插件在 9876 监听一端是 Cline 通过 stdio 拉起 MCP 服务端并连上统一 Key 通道。中间的数据流是你在 Cline 里说一句话 - 模型通过 TaoToken 通道返回工具调用意图 - MCP 服务端转成 QGIS 调用 - QGIS 执行 - 结果回传。下一节我们跑一次真实请求验证整条链路。4. 验证请求从一句话到图层分析结果配置对不对跑一次就知道。这一节用一个可复现的图层分析任务来验证任务本身不复杂但能覆盖「模型理解 - 工具调用 - QGIS 执行 - 结果回传」四个环节。先确保 QGIS 里已经加载了一个可分析的图层。你可以打开一个在线影像服务或者加载本地的一份矢量/栅格数据。为了验证稳定建议用本地数据避免在线服务网络波动干扰判断。假设你加载了一个名为 landuse 的矢量图层字段里有 type 和 area 两个属性。在 Cline 的对话框里输入这样一句话帮我统计 landuse 图层里每种 type 的面积总和按面积从大到小排序把结果用表格返回。发送之后观察三个地方。第一Cline 面板里应该出现工具调用记录显示它调用了 qgis_mcp 提供的某个工具比如 execute_processing 或 run_python。第二QGIS 界面会有反应可能是图层被读取、属性表被访问Processing 日志里能看到执行痕迹。第三Cline 最终返回一个表格列出每个 type 和对应的面积合计。如果这一步成功说明整条链路通了。你可以再试一个稍微复杂的让模型先对 landuse 做一次缓冲区分析再统计缓冲区内的 type 分布。这种多步任务能验证模型是否会连续调用多个工具以及 MCP 服务端是否能保持会话状态。验证时有个细节值得注意模型返回的工具调用参数是结构化的但 QGIS 的 Processing 算法参数名有固定写法。如果模型生成的参数名和算法实际参数名对不上QGIS 会报参数错误。这时候不要怪模型而是看 MCP 服务端有没有做参数映射。qgis_mcp 项目里通常会有一层适配把模型给的通用描述转成 QGIS 认识的参数。如果适配层没覆盖你用的算法你可以在服务端代码里补一个映射或者在提问时把参数名说清楚比如「用 qgis:buffer 算法DISTANCE 参数设为 100」。成功跑通一次之后建议把这次对话的配置和提问方式记下来形成你自己的模板。GIS 任务的描述越具体模型调用越准。比如「按 type 分组统计 area 总和」比「分析一下这个图层」要可靠得多。到这里从 QGIS 到模型调用的完整链路就验证完了。接下来把常见的坑列一下方便你对照排查。5. 常见报错排查401、local proxy failed 与 reading choices配置和验证过程中报错基本集中在几个固定位置。这一节按真实报错信息对照排查你遇到时可以直接定位。401 Unauthorized这个几乎都是 Key 的问题。检查三处TaoToken 的 API Key 是否复制完整有没有多空格客户端配置里 openAiApiKey 字段名是否写对Base URL 是否误填成了带 UTM 的地址。注意 API 基址是 https://taotoken.net/api 不要填成官网首页。如果 Key 刚创建就报 401去 API Keys 页面确认这个 Key 的状态是启用而不是禁用。local proxy failed / connection refused这个报错指向 MCP 服务端和 QGIS 插件之间的连接。先确认 QGIS 插件面板里 Start Server 是运行状态端口是 9876。然后在终端里测一下端口通不通Windows 用netstat -ano | findstr 9876macOS/Linux 用lsof -i :9876。如果端口没监听说明插件服务没起来重新点一次 Start Server。如果端口在监听但客户端还报 local proxy failed检查 cline_mcp_settings.json 里 env 的 HOST/PORT 是否和插件一致以及 server.py 路径是否正确。Error reading choices / 返回体解析失败这个通常出现在模型通道这一层。原因可能是 Model ID 写错请求发到了一个不存在的模型也可能是 Base URL 少了 /api 或者多了斜杠导致请求路径拼接错误。排查方法是在模型对话页用同一个 Model ID 发一条最简单的消息看能不能正常返回。如果对话页正常而 MCP 链路报错那就是客户端配置里的字段名和实际接口不匹配对照 OpenAI Compatible 的字段要求逐个核对。OAuth 相关报错如果你用的客户端默认走 OAuth 流程而统一 Key 通道走的是 API Key 鉴权两者会冲突。解决办法是在客户端里显式选择 API Key 模式不要让它走 OAuth 登录。Claude Code 和 Codex 都有对应的鉴权模式开关配置里指定用 api_key 而不是 oauth。插件安装后工具栏没图标回到 Manage and Install Plugins看 Installed 列表里 qgis_mcp_plugin 是否勾选启用。如果列表里根本没有说明 zip 结构不对重新按第 2 节的方式压缩确保 metadata.txt 在 zip 根目录。Python 依赖缺失导致服务端起不来server.py 启动即退出客户端连不上。在终端里手动跑一次python server.py看报什么 ModuleNotFoundError缺什么装什么最常见的是 mcp 包。排查的核心思路是分层先确认 QGIS 插件服务在监听再确认 MCP 服务端进程能起来再确认模型通道能返回最后确认工具调用参数能对上。一层一层往下查比一上来就改配置高效得多。6. 把统一 Key 通道固化进你的 GIS 工作流链路跑通之后真正有价值的是把它变成日常习惯。我自己的做法是把常用的 GIS 任务写成几个固定提问模板存在一个文本文件里需要时直接复制。比如「加载指定路径的矢量按字段 X 分组统计字段 Y 的总和」「对图层 A 做距离 D 的缓冲区统计缓冲区内的要素数量」这类。模板越固定模型调用越稳你也不用每次重新组织语言。另一个实用技巧是把 Model ID 和 Base URL 抽到一个环境变量或配置片段里客户端配置引用它。这样换模型时只改一处不用在多个配置文件里翻。统一 Key 通道的好处在这里体现得最明显你不需要为每个模型维护一套鉴权一个 Key 走到底。如果你打算长期用这套链路做编码或 Agent 任务可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用的场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段有疑问时对照文档比猜要快。Claude Code 相关的接入说明在 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 如果你用 Claude Code 驱动 QGIS MCP这份说明能帮你把鉴权模式配对。最后说一个我踩过的坑QGIS 插件启动的服务在 QGIS 关闭后不会自动清理有时候端口还占着下次启动会失败。养成习惯用完 QGIS 前先在插件面板点 Stop Server或者直接关 QGIS 后在终端确认端口释放。这个细节不影响功能但能省掉不少「明明配置没改怎么连不上」的困惑。
QGIS MCP 实战：把本地 GIS 工作流改到 TaoToken 统一 Key 通道
1. QGIS 接 MCP 到底解决什么问题QGIS 本身已经很强图层加载、栅格裁剪、矢量叠加、坐标转换这些操作都能做但它的短板在于「人机交互」这一层。你想让 QGIS 帮你完成一句自然语言描述的任务比如「把这份土地利用栅格按坡度重分类再统计各等级面积」传统做法是你自己拆解成 Processing Toolbox 里的一串算法手动配参数、手动跑、手动导出。QGIS MCP 要解决的就是把这段「拆解 调参 执行」的活交给模型你只负责说清楚要什么。MCP 是 Model Context Protocol 的缩写你可以把它理解成模型和本地软件之间的一根标准数据线。模型本身不会直接操作 QGIS它只能输出结构化的调用意图MCP 服务端负责把这些意图翻译成 QGIS 能执行的 Python 或 Processing 调用再把执行结果回传给模型。qgis_mcp 这个项目就是给 QGIS 装了一个 MCP 服务端插件让 QGIS 暴露出一组可被模型调用的工具接口。适合谁用三类人最直接受益。第一类是经常做重复性空间分析的人比如每周都要跑同一套缓冲区 叠加 统计的流程用 MCP 可以把这套流程固化成一两句指令。第二类是不太熟 QGIS Python API 但懂业务逻辑的人你描述需求模型帮你生成并执行调用。第三类是已经在用 Cline、Claude Code 这类编码 Agent 的人你希望 Agent 不只会写代码还能直接驱动本地 GIS 软件干活。这里有个关键点容易被忽略MCP 服务端和模型之间是要走网络请求的模型 API 的 endpoint 和鉴权方式决定了这条链路稳不稳、好不好管。默认很多教程会让你分别去各家模型厂商申请 Key一个项目里塞好几个 Key换模型就得改配置。把 endpoint 统一到 TaoToken 的 Key/API 通道之后QGIS MCP 这条链路只需要维护一份鉴权信息模型切换只改一个 Model ID这是本篇要重点落地的部分。我试过把 qgis_mcp 的默认模型通道换成统一 Key 通道整个配置改动量比想象中小核心就是三处MCP 服务端读的模型配置、客户端 Agent 的 Provider 设置、以及 QGIS 插件本身的启动参数。下面按可复现的顺序拆开讲。2. TaoToken 前置准备与 qgis_mcp 插件安装在动 QGIS 之前先把模型通道这层准备好否则后面配置 MCP 服务端时会来回改。TaoToken 的定位是统一 Key/API 通道你在这里拿到一个 Key就能通过兼容 OpenAI 风格的接口去调用不同模型。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填的就是这个干净地址。你需要做两件事注册后在控制台创建一个 API Key然后确认你要用的 Model ID。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Model ID 这块建议先在模型对话页确认一下当前可用的模型名地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 避免配置里写了一个不存在的名字导致后面 404。拿到 Key 之后回到 QGIS 侧。qgis_mcp 插件来自 GitHub 上的 jjsantos01/qgis_mcp 项目QGIS 本体从官网下载安装即可。插件安装有个小坑GitHub 上给的是源码目录不是打包好的 zip。你需要把 qgis_mcp_plugin 这个文件夹单独压缩成 qgis_mcp_plugin.zip压缩时注意是「压缩文件夹本身的内容」让 zip 根目录下直接能看到 metadata.txt 和init.py而不是多套一层 qgis_mcp_plugin 目录。套错一层QGIS 安装时会提示找不到插件元数据。安装路径是 QGIS 菜单 Plugins - Manage and Install Plugins切到 Install from ZIP 标签页选中你压好的 zip点 Install Plugin。装完工具栏会出现 QGIS_MCP 图标点开右侧浮动面板面板里有个 Start Server 按钮默认监听端口 9876。这个端口后面 MCP 客户端配置里要对应上如果你本机 9876 被占用可以在插件配置里改但改完记得同步改客户端。这里要提醒一句插件启动的服务是本机回环服务只在你自己的机器上监听不要把它暴露到公网。MCP 的设计前提就是本地可信环境模型通过客户端 Agent 间接调用不是让外部直接连你的 QGIS。前置准备做完你手上应该有三样东西TaoToken 的 API Key、确认可用的 Model ID、QGIS 里已经 Start Server 的 9876 端口。接下来进入配置环节。3. 可复制的 MCP 服务端与客户端配置这一节是整篇的核心配置写错一个字段后面验证就会卡住。qgis_mcp 的链路里有两个配置文件要动一个是 MCP 客户端以 Cline 为例的 cline_mcp_settings.json一个是模型 Provider 的接入配置。如果你用的是 Claude Code 或 Codex 这类 Agent配置位置不同但字段逻辑一致关键是 Base URL、Key、Model ID 三件套要写全。先看 MCP 客户端里注册 qgis_mcp 服务端的片段。Cline 的 MCP 配置在 VS Code 的设置里点 MCPServers - Configure MCP Servers 会打开 cline_mcp_settings.json。qgis_mcp 项目 README 给的是 stdio 方式启动一个 Python 服务你需要把命令和参数填进去。下面是一个可复制的 JSON 片段路径按你本机实际解压位置改{ mcpServers: { qgis_mcp: { command: python, args: [ D:/qgis_mcp/src/qgis_mcp/server.py ], env: { QGIS_MCP_HOST: 127.0.0.1, QGIS_MCP_PORT: 9876 }, disabled: false, autoApprove: [] } } }注意 args 里的 server.py 路径要指向你实际解压出来的 qgis_mcp 源码目录Windows 下用正斜杠或双反斜杠都行单反斜杠会被 JSON 转义吃掉。env 里的 HOST 和 PORT 要和 QGIS 插件面板里 Start Server 的监听地址一致默认就是 127.0.0.1:9876。然后是模型 Provider 的接入配置。Cline 的 Settings 里选 API Provider如果你要用统一 Key 通道选 OpenAI Compatible 这类选项然后填三件套{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的TaoTokenKey, openAiModelId: 你确认过的ModelID }Base URL 填 https://taotoken.net/api 不要带结尾斜杠也不要带 UTM 参数。Key 就是你在 API Keys 页面创建的那串。Model ID 填你在模型对话页确认过的名字。这三件套写全缺一个都会在请求时报错。如果你用的是 Claude Code配置走的是 settings 文件Base URL 和 Key 的字段名不同但语义一样Model ID 同样要显式指定。Codex 的话看 auth.json里面 api_key 和 base_url 两个字段对应上即可。不管哪个客户端判断配置对不对的标准只有一个客户端能成功发起一次模型请求并拿到回复。配置写完保存回到 Cline 的 MCP Servers 面板Installed 标签页里应该能看到 qgis_mcp 处于 connected 状态。如果显示红色或一直转圈先别急着怀疑模型通道大概率是 server.py 路径不对或 Python 环境缺依赖。qgis_mcp 的 server.py 依赖 mcp 这个 Python 包你需要先在对应 Python 环境里 pip install mcp否则进程一起来就退出客户端自然连不上。这一步做完链路的两端就都配好了一端是 QGIS 插件在 9876 监听一端是 Cline 通过 stdio 拉起 MCP 服务端并连上统一 Key 通道。中间的数据流是你在 Cline 里说一句话 - 模型通过 TaoToken 通道返回工具调用意图 - MCP 服务端转成 QGIS 调用 - QGIS 执行 - 结果回传。下一节我们跑一次真实请求验证整条链路。4. 验证请求从一句话到图层分析结果配置对不对跑一次就知道。这一节用一个可复现的图层分析任务来验证任务本身不复杂但能覆盖「模型理解 - 工具调用 - QGIS 执行 - 结果回传」四个环节。先确保 QGIS 里已经加载了一个可分析的图层。你可以打开一个在线影像服务或者加载本地的一份矢量/栅格数据。为了验证稳定建议用本地数据避免在线服务网络波动干扰判断。假设你加载了一个名为 landuse 的矢量图层字段里有 type 和 area 两个属性。在 Cline 的对话框里输入这样一句话帮我统计 landuse 图层里每种 type 的面积总和按面积从大到小排序把结果用表格返回。发送之后观察三个地方。第一Cline 面板里应该出现工具调用记录显示它调用了 qgis_mcp 提供的某个工具比如 execute_processing 或 run_python。第二QGIS 界面会有反应可能是图层被读取、属性表被访问Processing 日志里能看到执行痕迹。第三Cline 最终返回一个表格列出每个 type 和对应的面积合计。如果这一步成功说明整条链路通了。你可以再试一个稍微复杂的让模型先对 landuse 做一次缓冲区分析再统计缓冲区内的 type 分布。这种多步任务能验证模型是否会连续调用多个工具以及 MCP 服务端是否能保持会话状态。验证时有个细节值得注意模型返回的工具调用参数是结构化的但 QGIS 的 Processing 算法参数名有固定写法。如果模型生成的参数名和算法实际参数名对不上QGIS 会报参数错误。这时候不要怪模型而是看 MCP 服务端有没有做参数映射。qgis_mcp 项目里通常会有一层适配把模型给的通用描述转成 QGIS 认识的参数。如果适配层没覆盖你用的算法你可以在服务端代码里补一个映射或者在提问时把参数名说清楚比如「用 qgis:buffer 算法DISTANCE 参数设为 100」。成功跑通一次之后建议把这次对话的配置和提问方式记下来形成你自己的模板。GIS 任务的描述越具体模型调用越准。比如「按 type 分组统计 area 总和」比「分析一下这个图层」要可靠得多。到这里从 QGIS 到模型调用的完整链路就验证完了。接下来把常见的坑列一下方便你对照排查。5. 常见报错排查401、local proxy failed 与 reading choices配置和验证过程中报错基本集中在几个固定位置。这一节按真实报错信息对照排查你遇到时可以直接定位。401 Unauthorized这个几乎都是 Key 的问题。检查三处TaoToken 的 API Key 是否复制完整有没有多空格客户端配置里 openAiApiKey 字段名是否写对Base URL 是否误填成了带 UTM 的地址。注意 API 基址是 https://taotoken.net/api 不要填成官网首页。如果 Key 刚创建就报 401去 API Keys 页面确认这个 Key 的状态是启用而不是禁用。local proxy failed / connection refused这个报错指向 MCP 服务端和 QGIS 插件之间的连接。先确认 QGIS 插件面板里 Start Server 是运行状态端口是 9876。然后在终端里测一下端口通不通Windows 用netstat -ano | findstr 9876macOS/Linux 用lsof -i :9876。如果端口没监听说明插件服务没起来重新点一次 Start Server。如果端口在监听但客户端还报 local proxy failed检查 cline_mcp_settings.json 里 env 的 HOST/PORT 是否和插件一致以及 server.py 路径是否正确。Error reading choices / 返回体解析失败这个通常出现在模型通道这一层。原因可能是 Model ID 写错请求发到了一个不存在的模型也可能是 Base URL 少了 /api 或者多了斜杠导致请求路径拼接错误。排查方法是在模型对话页用同一个 Model ID 发一条最简单的消息看能不能正常返回。如果对话页正常而 MCP 链路报错那就是客户端配置里的字段名和实际接口不匹配对照 OpenAI Compatible 的字段要求逐个核对。OAuth 相关报错如果你用的客户端默认走 OAuth 流程而统一 Key 通道走的是 API Key 鉴权两者会冲突。解决办法是在客户端里显式选择 API Key 模式不要让它走 OAuth 登录。Claude Code 和 Codex 都有对应的鉴权模式开关配置里指定用 api_key 而不是 oauth。插件安装后工具栏没图标回到 Manage and Install Plugins看 Installed 列表里 qgis_mcp_plugin 是否勾选启用。如果列表里根本没有说明 zip 结构不对重新按第 2 节的方式压缩确保 metadata.txt 在 zip 根目录。Python 依赖缺失导致服务端起不来server.py 启动即退出客户端连不上。在终端里手动跑一次python server.py看报什么 ModuleNotFoundError缺什么装什么最常见的是 mcp 包。排查的核心思路是分层先确认 QGIS 插件服务在监听再确认 MCP 服务端进程能起来再确认模型通道能返回最后确认工具调用参数能对上。一层一层往下查比一上来就改配置高效得多。6. 把统一 Key 通道固化进你的 GIS 工作流链路跑通之后真正有价值的是把它变成日常习惯。我自己的做法是把常用的 GIS 任务写成几个固定提问模板存在一个文本文件里需要时直接复制。比如「加载指定路径的矢量按字段 X 分组统计字段 Y 的总和」「对图层 A 做距离 D 的缓冲区统计缓冲区内的要素数量」这类。模板越固定模型调用越稳你也不用每次重新组织语言。另一个实用技巧是把 Model ID 和 Base URL 抽到一个环境变量或配置片段里客户端配置引用它。这样换模型时只改一处不用在多个配置文件里翻。统一 Key 通道的好处在这里体现得最明显你不需要为每个模型维护一套鉴权一个 Key 走到底。如果你打算长期用这套链路做编码或 Agent 任务可以了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它更适合高频调用的场景。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段有疑问时对照文档比猜要快。Claude Code 相关的接入说明在 https://taotoken.net/claudecode?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 如果你用 Claude Code 驱动 QGIS MCP这份说明能帮你把鉴权模式配对。最后说一个我踩过的坑QGIS 插件启动的服务在 QGIS 关闭后不会自动清理有时候端口还占着下次启动会失败。养成习惯用完 QGIS 前先在插件面板点 Stop Server或者直接关 QGIS 后在终端确认端口释放。这个细节不影响功能但能省掉不少「明明配置没改怎么连不上」的困惑。
