QGIS MCP 是什么?安装步骤、局限与更简单的替代方案
发布于 更新于
QGIS MCP 是一个免费的 QGIS 插件,加上您电脑上的一个小程序,让 QGIS 之外的 AI 应用(通常是 Claude Desktop 或 Claude Code)可以控制 QGIS。您在 AI 应用里输入需求,它通过本地连接把命令发给 QGIS,由 QGIS 执行:加载图层、运行数据处理工具、设置地图样式,或者运行 Python 代码。

这个思路很好,插件也做得不错。官方 QGIS 插件仓库中的版本由 Nicolas Karasiak 维护,截至 2026 年 9 月 26 日已有 52,575 次下载。教程通常不会提到的,是让它跑起来要花多少功夫,以及它在哪些地方会卡住。我从零开始安装了一遍,然后把同一个任务分别交给它和一个运行在 QGIS 内部的智能体。后者是我们开发的 AI Agent,所以请带着这一点来看我的结论。
一段话讲清 MCP
MCP(Model Context Protocol,模型上下文协议)是 Anthropic 发起的开放标准,让 AI 应用可以调用外部工具。官方介绍把它比作“AI 应用的 USB-C 接口”。AI 应用称为客户端,向客户端提供工具的叫服务器。QGIS MCP 就是一个服务器,它提供的工具就是 QGIS 的各种操作。协议文档直接写明了风险:“工具代表任意代码执行,必须谨慎对待。”
QGIS MCP 的工作原理
下面四个部分必须同时安装并运行:
- MCP 客户端:您输入需求的 AI 应用,例如 Claude Desktop、Claude Code、Cursor、VS Code、Codex CLI 或 Gemini CLI。
- MCP 服务器:客户端通过
uv在后台启动的一个小型 Python 程序。uv是用来安装和运行 Python 程序的工具,需要您先装好。 - QGIS MCP 插件:在 QGIS 内部通过本地网络端口 9876 监听命令。点击工具栏上插件的按钮,选择 Run MCP 即可启动。
- QGIS 本身,并且已经打开了您的工程。
您输入需求后,AI 模型选择一个 QGIS 工具,服务器把调用转给插件,插件在 QGIS 中执行并返回结果。模型看不到您的屏幕,只有向 QGIS 索要地图截图时才能看到地图。
开始之前需要准备什么
| 需求 | 用途 | 费用 |
|---|---|---|
| QGIS 3.28 或更高版本 | 插件的最低要求 | 免费 |
| 一个 MCP 客户端应用 | 与模型对话的地方 | 有每日额度限制的免费版,或付费套餐 |
uv(Python 包运行器) | 启动 MCP 服务器 | 免费,终端里一条命令即可安装 |
| 一条终端命令或一行配置文件 | 告诉客户端服务器在哪里 | 免费,但要手动操作 |
| QGIS MCP 插件 | 连接的 QGIS 一侧 | 免费 |
一篇流传很广的安装指南说必须有付费的 Claude Pro 账户,其实不需要。Anthropic 关于本地 MCP 服务器的文档没有指定任何套餐,一位 GIS 博主在 2026 年 8 月就在 Claude 免费版上跑通了 QGIS MCP,只是碰到了每日消息数上限。ChatGPT 则麻烦得多:OpenAI 的帮助中心写明,它只能连接互联网上的 MCP 服务器,不能连接您电脑上的服务器,而且所需的开发者模式只对付费套餐开放。
安装 QGIS MCP,全程计时
我在 2026 年 9 月 26 日于 QGIS 3.44 上安装了 QGIS MCP 0.15.0,并记录了每一步。插件自己的页面也说得很坦率:“这个插件只是整套配置的一半。您还需要 qgis-mcp MCP 服务器,由您的 MCP 客户端运行,用来与 QGIS 通信。”
安装插件
插件 > 管理并安装插件...(Plugins > Manage and Install Plugins),搜索 QGIS MCP,点击 安装插件。这一步很快:加载只用了 2.7 秒,无需重启。
安装 uv
服务器通过
uv运行,而 Windows 和 macOS 都没有自带。您需要在终端里用一条命令安装。获取 MCP 客户端
Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI,或其他支持 MCP 的应用,各自有自己的账户和套餐。
让客户端连接 QGIS
插件的 Configurator(配置器)会给出一条要粘贴到终端的命令,例如
claude mcp add -s user qgis -- uvx ... qgis-mcp-server。有些客户端则需要在设置文件里加一行。在 QGIS 中启动服务器
点击插件工具栏按钮上的 Run MCP。启动时 QGIS 会记录 “Token authentication disabled (open)”(令牌认证已关闭,开放访问)。
发送第一条消息
第一次调用会下载服务器(约 90 MB)然后连接。我的测试用了 16 秒,客户端识别出 125 个 QGIS 工具。
下面截图中的 Configurator 就是选择客户端、复制终端命令的地方。

我的这次安装大约用了三分钟,但 uv 和客户端已经装好,点击操作也由脚本完成。第一次安装的人还要读文档、装 uv 和客户端、自己输入命令。
其中一部分麻烦每天都会重来。QGIS 重启后,服务器不会自动开启,除非您在 Configurator 里勾选自动启动。此时 AI 应用只会提示 “Error executing tool ping”(执行工具 ping 出错),您得自己猜到该重新点击 Run MCP。
同一个任务,两种做法
我给两个工具下达了同样的请求,同一时间在同一台电脑上,各自在全新的 QGIS 工程中进行:“在法国里昂,找出离有轨电车站点 300 米以内的学校,把它们和有轨电车线路一起显示在地图上,并告诉我一共有多少所。”
| QGIS MCP(配合 Claude Code) | AI Agent | |
|---|---|---|
| 得出答案的时间 | 9 分 28 秒 | 5 分 35 秒 |
| 步骤 | 10 步,其中 6 步是 Python 代码 | 40 步,其中 2 步是 Python 代码 |
| 使用的数据 | OpenStreetMap,由它自己写的 Python 下载 | Métropole de Lyon 官方的小学、初中和高中(lycée)图层,加上 OpenStreetMap 的有轨电车站点和轨道 |
| 统计的学校数 | 87 | 80(52 所小学、14 所初中、14 所高中) |
两个数字不同,是因为两个工具用的数据不同。QGIS MCP 统计的是靠近有轨电车站点的 OpenStreetMap 学校,站点取自里昂周围的一个方框,所以城外紧邻边界的几个站点也被算了进去,而且它自己也说明这 87 所没有去重。AI Agent 用的是该市官方的学校名录和里昂市行政边界。
它们是怎么得出结果的,差别更大。QGIS MCP 没有数据工具,模型只能自己写 Python 去查询 OpenStreetMap 的 Overpass 服务器。服务器返回了错误(406、504,然后两次 502),它就重试。这段 Python 跑在 QGIS 的主线程上,所以 QGIS 卡住了大约七分钟,地图在 7 分 22 秒之前一直是空的。

AI Agent 先搜索了自己的数据目录,加载了该市官方的学校图层。当全国公共交通数据源没有标出里昂的有轨电车时,它改用 OpenStreetMap 获取有轨电车站点和轨道。它写了两次 Python,用来测量每所学校到最近站点的距离。

再测三个任务,其中一个 QGIS MCP 更快
一场比赛说明不了什么,所以我用同样的方法又给三个任务计了时。结果并不都对我们有利:
| 任务 | QGIS MCP(配合 Claude Code) | AI Agent |
|---|---|---|
| 波尔图历史中心的建筑物按类型着色,加卫星底图 | 1 分 44 秒 | 1 分 21 秒 |
| 同上,再加一个 A4 PDF 版面,含标题、图例、比例尺和指北针 | 2 分 48 秒 | 5 分 26 秒 |
| 约克因河流洪水而有风险的建筑物,使用 Environment Agency 的数据 | 15 分钟后仍未完成,地图上什么都没有 | 15 分钟后仍未完成,加载了部分洪水数据,没有统计结果 |
当数据只需一次 OpenStreetMap 下载就能拿到时,QGIS MCP 跟得上,在 PDF 版面这个任务上还快了大约一倍。它自己的回答提醒说,导出 PDF 时没有检查卫星瓦片是否加载完成。差距出现在模型必须自己找数据并下载的时候,比如里昂这个任务。两个工具都没能在 15 分钟内完成约克的洪水任务。9 月 26 日第一次跑波尔图时,QGIS MCP 用了 8 分 29 秒,因为那天下载服务器过载,所以我把所有任务重新计了时。
我们是怎么测量的。 同一台电脑,两个工具同时运行,QGIS 3.44.15,全新工程,默认设置,只有 AI Agent 的强度设为 Medium。每个任务各跑一次,不重试:QGIS MCP 0.15.2 由 Claude Code 驱动,使用 Claude Sonnet 5.5,只允许使用 QGIS 工具;AI Agent 为 1.9.0,Balanced 模式。QGIS MCP 的用时是 Claude Code 自己的运行时间,不含客户端启动所花的 52 秒。里昂这场比赛期间,电脑负载很高,OpenStreetMap 服务器对两个工具都在报错。我们给每次运行都录了屏。
您可以在自己的 QGIS 里用几分钟复现同一个请求:安装插件,登录,把请求粘贴到面板里。
QGIS MCP 的不足
下面是我实际碰到或在文档中查到的限制,每一条都有来源:
- 聊天窗口在 QGIS 之外。 您要在两个窗口之间来回切换。模型依据工具返回的结果工作,只有向 QGIS 索要地图截图时才能看到地图。
- 四个环节。 一旦没有反应,问题可能出在客户端设置、
uv、服务器、端口或插件上。项目的故障排查页把 “No response from QGIS”(QGIS 无响应)、Connection refused(连接被拒绝)和ModuleNotFoundError(找不到模块)列为常见错误。 - Windows 上的一个坑。 README 提醒,从 Microsoft Store 安装的 Claude Desktop 会在沙盒中运行服务器,这会破坏常规配置,所以在别处能用的配置在这里会失败。
- 能运行任意 Python,默认没有密码。
execute_code工具会运行模型写出的任意 PyQGIS(QGIS 的 Python 代码)。README 里写得很清楚:“默认情况下套接字没有认证……本机上任何能访问该端口的进程都可以驱动 QGIS(包括能执行任意 PyQGIS 的 execute_code)。”有一个分支项目 QGIS Agent MCP,主要目的就是去掉这个工具。 - 没有自己的数据。 它只负责驱动 QGIS,查找和下载数据要靠模型,通常是自己写 Python。在里昂的测试里,10 步中有 6 步是 Python,下载让 QGIS 卡住了大约七分钟。
- 整个请求无法一次撤销。 QGIS 自带的撤销只覆盖编辑操作,不包括已添加的图层或已写入的文件。
- 星标最多的版本并不是在维护的版本。 GitHub 上的原版 jjsantos01/qgis_mcp 有 1,099 个星标,自 2025 年 10 月 1 日起没有代码更新,还有一个未关闭的 issue,标题是 “Broken plugin for QGIS version 4.01”(QGIS 4.01 版本上的插件已损坏)。真正在维护的是 nkarasiak/qgis-mcp,也就是 QGIS 插件仓库里的那个版本。
网上流传的几处错误说法
“您需要 Claude Pro。” 本地 MCP 服务器在 Claude 免费版上也能用,只是受每日额度限制。设有付费门槛的是 ChatGPT,而它本来就无法直接连接您电脑上的服务器。
“编辑完配置后要重启电脑。” 重启客户端应用就够了。在 Windows 上,请确认它已经完全退出,因为它会继续驻留在系统托盘中。
“安装星标最多的那个仓库。” 请改从 QGIS 插件管理器安装,得到的才是仍在维护的版本。
把 Claude 连接到 QGIS 的其他方式
上面这个插件是大多数指南所指的那一个,但另外还有三个项目也能把 Claude 放进 QGIS。以下内容均读取自它们各自的页面,日期为 2026 年 10 月 23 日:
- piatkowski/qgis-mcp: 一个同名的独立项目,为 Claude Desktop 而做。它从 GitHub 发布页下载 ZIP 安装,而不是通过插件管理器,其服务器需要 Python 3.12 或更高版本,插件一启用就会开始监听 9876 端口。上面那个插件同样使用 9876 端口,所以一次只运行其中一个。
- ClaudIA QGIS: 派生自上面那个插件,把本地端口换成了通过 HTTPS 连接 agrônomo10X 社区,因此无需安装 Python。它需要一个 agrônomo10X 账号,其 2026 年 9 月 15 日发布的 0.2.3 版本被标记为实验性。
- QGIS Agent: QGIS 内的聊天面板,使用您自己的 LLM 密钥,另有一个可选的本地 MCP 服务器,Claude Desktop 或 Cursor 可以驱动它。
QGIS MCP 的另一种选择:运行在 QGIS 内部的智能体
我们开发了 AI Agent,所以这一节讲的是我们自己的插件。它能完成与 QGIS MCP 同样的工作,但整个过程都在 QGIS 里:聊天是停靠在地图旁边的一个面板,模型随插件一起提供。在 Google 的 GeoKTools 和 GeoExpertQueries 基准测试中,通过这个 MCP 插件(版本 0.15.1,在 Claude Code 中)驱动 QGIS 的 Claude Sonnet 5.5,对 41 道保留题得分 24.9(满分 100),而 Low 强度(GPT-6 Luna)的 AI Agent 得分 43.8(基准测试结果)。
日常使用中最有感的差别:
- 只需安装一次。 插件 > 管理并安装插件...,搜索 AI Agent by TerraLab,安装,登录。不需要
uv,不需要配置文件,不需要另一个应用,也不需要每次使用都启动服务器。 - 它能看到您的工程。 每次请求都会带上图层名称、字段、CRS、范围和选择集,它还会渲染地图来检查自己的成果。
- 内置数据。 目录收录 190 个开放数据源,从 OpenStreetMap 到 Sentinel-2,再到各国测绘机构,模型不必再写下载代码。
- 先询问再动手。 在默认设置下,删除或覆盖之前它会先停下来,而会改动您工程的 Python 代码始终需要您点击确认。
- 每条消息都能撤销。 每条消息都会留下一个检查点,点击一下就能让工程回到那个状态。
它需要联网,发送给托管在欧盟的服务的是您工程的描述,绝不会发送您的数据文件。提供无需信用卡的免费套餐,而且无论一条消息包含多少步骤,都只算一项任务。免费试用 Pro 7 天:绑定银行卡,试用期结束前取消则不会扣费。
QGIS MCP 与 QGIS 内置智能体对比
| QGIS MCP | AI Agent | |
|---|---|---|
| 在哪里聊天 | 外部应用(Claude Desktop、Cursor、Claude Code) | QGIS 内部的面板 |
| 需要安装什么 | 插件、uv、一个 MCP 客户端、一行配置 | 一个插件 |
| 每次使用 | 在 QGIS 中启动服务器,两个应用都要开着 | 打开面板 |
| 模型 | 客户端用什么就是什么,费用算在您的套餐里 | 已包含 |
| 开放数据目录 | 无 | 190 个数据源 |
| 运行 Python | 可以,默认不询问 | 会改动工程的代码会先询问 |
| 撤销整个请求 | 不能 | 可以,点击一下 |
| 价格 | 插件免费,另加您的 AI 套餐费用 | 免费套餐,之后 Pro 套餐每月 €49 |
| 最适合 | 已经在 Claude Code 或 Cursor 中工作的开发者 | 想直接在 QGIS 里得到结果的 GIS 用户 |
该选哪一个?
如果您本来就在用 Claude Code 或 Cursor,会写 Python,想把 QGIS 当作其中又一个工具,QGIS MCP 很合适,而且除了您已经在付的 AI 套餐外不用再花钱。如果您想直接输入一个 GIS 任务、在工程里拿到结果,不想碰终端、uv 或第二个应用,运行在 QGIS 内部的智能体需要配置和维护的东西更少。我认识的大多数 GIS 用户都属于后一种。
要点回顾
QGIS MCP 通过本地连接,把 QGIS 之外的 AI 应用(例如 Claude Desktop)接到 QGIS 上,这样该应用的模型就能运行 QGIS 工具和 Python。
它需要四个部分同时运行:客户端应用、uv 和 MCP 服务器、已启动服务器的 QGIS MCP 插件,以及 QGIS。
QGIS 一侧几秒钟就能装好。其余都在 QGIS 之外:安装 uv、安装 AI 应用、输入终端命令,以及每次重启后再点击一次 Run MCP。
在里昂这个任务上,AI Agent 用 5 分 35 秒、基于该市官方学校图层给出了答案;QGIS MCP 用了 9 分 28 秒,10 步中有 6 步是写 Python。任务更简单时差距会缩小,在 PDF 版面任务上 QGIS MCP 更快。
ChatGPT 无法直接使用本地 MCP 服务器。Claude 免费版可以,受每日额度限制。
像 AI Agent 这样运行在 QGIS 内部的智能体,用一个插件就能完成同样的工作,并且已包含模型、数据目录和一键撤销。
常见问题
QGIS MCP 是一个 QGIS 插件加一个本地 MCP 服务器,让 AI 应用通过模型上下文协议(MCP)控制 QGIS。您在应用(通常是 Claude Desktop 或 Claude Code)中对话,模型调用 QGIS 工具:加载图层、运行数据处理、设置样式、渲染地图和运行 Python。
从插件管理器安装 QGIS MCP 插件并点击 Run MCP,安装 uv,然后把 QGIS MCP 服务器加入 Claude Desktop 的配置文件,或者在 Claude Code 中运行 claude mcp add 命令,最后重启客户端。也可以改装一个运行在 QGIS 内部、自带模型的智能体插件,例如 AI Agent,这样就不需要客户端、uv 和配置文件。
不能直接使用。OpenAI 的帮助中心写明,ChatGPT 连接的是互联网上的 MCP 服务器,所以像 QGIS MCP 这样位于您电脑上的服务器,需要通过隧道才能被访问到。MCP 所需的开发者模式仅限 ChatGPT 付费套餐。
它可以在 QGIS 中运行模型写出的任意 Python,而且按 README 所述,本地套接字默认没有认证。请在您信任的机器上使用;如果机器有其他人共用,请设置共享密钥令牌;用完后停止服务器,并为重要工程做好备份。
项目故障排查指南列出的常见原因有:QGIS 中没有启动服务器(出现 Connection refused,点击 Run MCP 即可),uv 没装或找不到(出现 ModuleNotFoundError),或者端口不是 9876。QGIS 重启后,除非勾选了自动启动,服务器会再次关闭。在 Windows 上,如果 Claude Desktop 是从 Microsoft Store 安装的,配置需要使用 --directory 的写法。
有。智能体插件直接作为聊天面板运行在 QGIS 内部,不需要外部应用,也不需要本地服务器。2026 年 9 月,我们在官方仓库中统计到 38 个智能体和助手类插件。我们的 AI Agent 已包含模型、190 个开放数据源和一键撤销,并提供免费套餐。
什么是 QGIS 中的 AI 智能体一文统计了官方仓库中全部 38 个智能体和助手类插件,包括各种 MCP 桥接插件。AI Agent 指南展示了十次真实运行及其提示词,PyQGIS 一文则测量了聊天机器人写出的代码有多大比例一次就能运行。QGIS AI 中心对比了更广泛的同类工具。


