跳转到内容
AI Agent
QGIS
指南

QGIS MCP 是什么?安装步骤、局限与更简单的替代方案

发布于 更新于

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

两行对比架构。上一行是 QGIS MCP,需要安装、配置并启动四个部分:AI 客户端(如 Claude Desktop、Claude Code 或 Cursor,各有自己的套餐),通过 stdio 连接 MCP 服务器(用 uv 启动的 Python 进程,命令为 uvx qgis-mcp-server),再通过 TCP 9876 端口连接 QGIS MCP 插件(QGIS 内部的套接字服务器,每次使用都要点击 Run MCP),最后控制您的 QGIS 工程。下一行是 AI Agent,只有一个插件:停靠在 QGIS 中的 AI Agent 面板,从插件管理器安装,能看到图层、字段、CRS、范围和选择集,通过 HTTPS 连接运行在欧盟的智能体服务,无需 API 密钥或客户端应用,最后控制您的 QGIS 工程。
上:QGIS MCP 需要同时运行的四个部分。下:直接运行在 QGIS 内部的智能体插件,这里是我们的 AI Agent。

这个思路很好,插件也做得不错。官方 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 的工作原理

下面四个部分必须同时安装并运行:

  1. MCP 客户端:您输入需求的 AI 应用,例如 Claude Desktop、Claude Code、Cursor、VS Code、Codex CLI 或 Gemini CLI。
  2. MCP 服务器:客户端通过 uv 在后台启动的一个小型 Python 程序。uv 是用来安装和运行 Python 程序的工具,需要您先装好。
  3. QGIS MCP 插件:在 QGIS 内部通过本地网络端口 9876 监听命令。点击工具栏上插件的按钮,选择 Run MCP 即可启动。
  4. 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 通信。”

  1. 安装插件

    插件 > 管理并安装插件...(Plugins > Manage and Install Plugins),搜索 QGIS MCP,点击 安装插件。这一步很快:加载只用了 2.7 秒,无需重启。

  2. 安装 uv

    服务器通过 uv 运行,而 Windows 和 macOS 都没有自带。您需要在终端里用一条命令安装。

  3. 获取 MCP 客户端

    Claude Code、Claude Desktop、Cursor、Codex、Gemini CLI,或其他支持 MCP 的应用,各自有自己的账户和套餐。

  4. 让客户端连接 QGIS

    插件的 Configurator(配置器)会给出一条要粘贴到终端的命令,例如 claude mcp add -s user qgis -- uvx ... qgis-mcp-server。有些客户端则需要在设置文件里加一行。

  5. 在 QGIS 中启动服务器

    点击插件工具栏按钮上的 Run MCP。启动时 QGIS 会记录 “Token authentication disabled (open)”(令牌认证已关闭,开放访问)。

  6. 发送第一条消息

    第一次调用会下载服务器(约 90 MB)然后连接。我的测试用了 16 秒,客户端识别出 125 个 QGIS 工具。

下面截图中的 Configurator 就是选择客户端、复制终端命令的地方。

左:QGIS 插件管理器中 Nicolas Karasiak 开发的 QGIS MCP 0.15.0 页面,387 票、52,575 次下载,说明文字写着这个插件只是整套配置的一半,还需要 qgis-mcp MCP 服务器。右:插件的 Setup and Configurator 窗口,客户端选择 claude-code,状态为 Server running on port 9876,下方是以 claude mcp add 开头、需要在终端中运行的命令。
插件页面和它的 Configurator。QGIS 一侧很快,其余工作都在终端和另一个应用里完成。

我的这次安装大约用了三分钟,但 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 的有轨电车站点和轨道
统计的学校数8780(52 所小学、14 所初中、14 所高中)

两个数字不同,是因为两个工具用的数据不同。QGIS MCP 统计的是靠近有轨电车站点的 OpenStreetMap 学校,站点取自里昂周围的一个方框,所以城外紧邻边界的几个站点也被算了进去,而且它自己也说明这 87 所没有去重。AI Agent 用的是该市官方的学校名录和里昂市行政边界。

它们是怎么得出结果的,差别更大。QGIS MCP 没有数据工具,模型只能自己写 Python 去查询 OpenStreetMap 的 Overpass 服务器。服务器返回了错误(406、504,然后两次 502),它就重试。这段 Python 跑在 QGIS 的主线程上,所以 QGIS 卡住了大约七分钟,地图在 7 分 22 秒之前一直是空的。

QGIS MCP 在里昂运行后的 QGIS:红点是离有轨电车站点 300 米以内的学校,蓝线是有轨电车线路,灰点是有轨电车站点,背景是白色,没有底图。图层面板中有 schools_within_300m、tram_lines、tram_stops 和一个隐藏的 schools_all 图层。
QGIS MCP 配合 Claude Code:9 分 28 秒,87 所学校,所有下载都靠 Python 写成。

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

右侧为 AI Agent 面板的 QGIS。地图上显示里昂市行政边界、有轨电车轨道,以及离站点 300 米以内的学校,学校按名称标注,并按小学、初中和高中着色。智能体的回答里有一张统计卡片:80 所学校(52 所小学、14 所初中、14 所高中),到最近站点的距离为 14.6 至 297.2 米;随后列出数据来源:Métropole de Lyon 学校数据、OpenStreetMap 有轨电车站点和轨道、里昂边界和一份 GTFS 摘录。
AI Agent:5 分 35 秒,80 所学校,来自该市自己的学校图层。

再测三个任务,其中一个 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 中免费试用 AI Agent,无需信用卡

QGIS MCP 与 QGIS 内置智能体对比

QGIS MCPAI 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 中的 AI 智能体一文统计了官方仓库中全部 38 个智能体和助手类插件,包括各种 MCP 桥接插件。AI Agent 指南展示了十次真实运行及其提示词,PyQGIS 一文则测量了聊天机器人写出的代码有多大比例一次就能运行。QGIS AI 中心对比了更广泛的同类工具。

在 QGIS 里,说一句就能完成

AI Agent 会在你自己的 QGIS 项目中,完成你描述的任务。免费使用,无需绑卡。

免费试用 AI Agent
由以下作者撰写Yvann Barbot
·7 min read

继续阅读

QGIS 中的 AI Agent:浦那各选区的学校数量分级统计图,附有请求内容,共统计 58 个选区的 256 所学校。
AI AgentQGIS指南

Claude 怎么连接 QGIS?3 种方法同一任务实测

QGIS 没有官方的 Claude 插件。本文介绍在 QGIS 中使用 Claude 的三种方法:MCP、PyQGIS 代码和 QGIS 内的智能体,用同一项制图任务逐一实测,并告诉您该选哪一种。

Yvann BarbotYvann Barbot
·
并排的两张导出的 A4 打印布局。左边是聊天机器人的第一次回答:标题、图例和指北针围着一个空白的地图框,旁边写着“Ran without an error, the map frame is empty”。右边是 AI Agent 生成的安纳西学校布局,包含街区、按类型着色的学校、图例和比例尺,旁边写着“One message”。
AI AgentQGIS指南

ChatGPT 能做 QGIS 吗?三项 PyQGIS 实测

ChatGPT 能写 PyQGIS 代码,但看不到您的 QGIS 工程,也无法自己运行。我们让 GPT-5.5 完成三项真实任务,并在 QGIS 3.44 中逐个运行脚本:两项一次做对,一项没有报错却导出了空白地图,原因是坐标参照系猜错了。

Yvann BarbotYvann Barbot
·