QGIS MCP实战：让AI通过自然语言控制桌面GIS

最近在折腾 GIS 自动化时，发现一个新词频繁出现在 QGIS 社区里：MCP。很多人把 MCP 理解成“又一个人工智能接口”，但对 GIS 开发者来说，MCP 最大的价值在于：它能让 AI 助手直接操作桌面 GIS 软件，比如加载图层、统计要素、按条件过滤、导出结果。

这篇文章会以“QGIS-MCP 演示”为主线，从 MCP 协议的基本概念讲起，逐步带你搭建一个可运行的 QGIS MCP 服务，并把它接入 Claude Desktop、Codex 等 MCP 客户端。读完后，你不仅能理解 QGIS-MCP 背后的运行原理，还能动手在一个小示例项目里用自然语言控制 QGIS 完成数据查询和图层管理。

1. 背景与核心概念

1.1 MCP 是什么

MCP 的全称是 Model Context Protocol，也就是“模型上下文协议”。它由 Anthropic 在 2024 年提出，目标是为 AI 模型和外部工具之间建立一套标准化的通信方式。

在没有 MCP 之前，AI 模型只能基于训练数据回答，无法读取你本地的 GIS 数据，更不可能直接操作 QGIS。想让 AI 帮你加载图层、统计要素数量，往往需要你写脚本、留给 AI 一个 API 接口，或者人工复制结果给模型看。这种方式不仅链路长，而且每换一个工具就要重新对接一次。

MCP 改变了这种局面。它定义了三种角色：

一个 MCP Server 可以把多个能力暴露给 AI 模型，模型读到工具描述后，会决定何时调用哪个工具、传入什么参数。整个过程是标准化的，所以同一个 QGIS MCP Server 可以被多个支持 MCP 的客户端复用。

1.2 QGIS-MCP 解决什么问题

QGIS 是目前最常用的开源桌面 GIS 软件，功能覆盖地图浏览、图层管理、空间分析、制图输出等。但它的功能基本面向“人机交互”：点击、拖拽、选择工具、配置对话框。人工智能模型无法直接点击 QGIS 窗口，就需要一个中间层。

QGIS-MCP 要解决的核心问题有两个：

1. 让 AI 能读取 QGIS 当前工程中的图层、字段、要素数据。
2. 让 AI 能安全地执行 QGIS 操作，比如加载矢量文件、执行表达式过滤、统计要素数量。

用一句话概括：QGIS-MCP 把 QGIS 的能力“函数化”了。每个 GIS 操作都变成一个可被 AI 调用的工具函数，模型可以按需调用。

对普通用户来说，这意味着你可以用自然语言完成部分数据操作。例如：

• “加载 D:/data/城市边界.geojson”
• “统计这个图层里有多少个区县”
• “筛选人口大于 50 万的区域，返回前 10 条”

1.3 为什么值得学习 QGIS-MCP

MCP 并非 QGIS 独有。从最新的社区动态来看，Unreal Engine 5.8 相关 MCP 插件、调试器 x32dbg 的 MCP 插件、RuoYi-Vue-Pro 中的 MCP 功能、Codex 接入 Figma MCP 等都在快速出现。这说明 MCP 正在成为一种跨领域、跨软件的工具集成标准。

对 GIS 开发者来说，掌握 QGIS-MCP 有几点实际价值：

• 可以快速把现有 PyQGIS 脚本暴露给 AI 模型，复用已有数据处理逻辑。
• 可以结合自然语言交互，降低业务方使用 GIS 工具的门槛。
• 可以基于同一套协议，横向对接更多 MCP 客户端，而不是为每个客户端单独开发接口。

当然，MCP 并不是银弹。工具设计、权限控制、图层数据安全仍然需要开发者自己把关。这也是本文后半部分会重点讨论的内容。

2. 环境准备与版本说明

2.1 基础环境要求

本次 QGIS-MCP 演示采用“QGIS Python 环境 + MCP SDK + MCP 客户端”的方式运行，基础环境建议如下：

如果你已经在使用 QGIS 3.28 或 3.36，操作思路完全一致，只是安装路径和 Python 版本目录可能不同。文章中的路径只是示例，请根据你自己的安装位置调整。

2.2 QGIS 安装与常见坑

最近看到不少人反馈“QGIS 不能安装”“卸载后无法安装”，这些问题通常集中在三个原因：

• 安装包下载不完整，导致安装过程中断。
• 安装路径含有中文或空格，导致环境变量异常。
• 旧版本卸载后残留配置文件，影响新版本安装。

建议从 QGIS 官网下载官方安装包，安装路径尽量使用英文目录，例如 C:\Program Files\QGIS 3.34.4。如果你之前安装过旧版本并卸载过，安装新版本前可以检查 %APPDATA%\QGIS 和 %LOCALAPPDATA%\QGIS 等目录，必要时备份后清理残留配置。

2.3 演示项目目录结构

在开始写代码前，先规划一个清晰的项目目录。本文演示工程的目录结构如下：

code复制D:\gis_demo
├── data
│   ├── 城市边界.geojson
│   └── 人口统计.xlsx
├── qgis_mcp_demo_server.py
├── requirements.txt
└── mcp_client_config.json

data 目录用来放测试数据；qgis_mcp_demo_server.py 是 QGIS MCP 服务端；mcp_client_config.json 是 MCP 客户端的接入配置。

3. MCP 与 QGIS 集成原理拆解

3.1 MCP 客户端—服务器模型

在本地 MCP 工具中，最常见的传输方式是 stdio。MCP 客户端启动一个子进程，并通过标准输入输出和 MCP Server 进行 JSON-RPC 通信。例如，你在 Claude Desktop 中配置了一个命令，Claude Desktop 启动该命令，同时建立 MCP 会话。

具体流程如下：

1. 客户端根据配置，启动一个带命令行参数的进程。
2. 进程内部创建 MCP Server，等待标准输入中的请求。
3. AI 模型接收到用户自然语言后，决定是否调用某个工具。
4. 客户端把工具调用请求发送给 MCP Server。
5. MCP Server 执行实际 GIS 操作，返回结构化结果。
6. 客户端把结果交给 AI 模型，由模型生成最终回答。

这种模式下，工具的定义、参数说明、返回值结构都会暴露给模型。因此，工具函数写得越清晰，AI 调用的正确率就越高。

3.2 QGIS-MCP 的运行架构

QGIS-MCP 的核心难点在于：MCP Server 需要运行在一个能够访问 QGIS API 的 Python 环境中。

QGIS 自带了一套完整的 Python 环境，支持导入 qgis.core、使用 QgsProject、QgsVectorLayer 等类。我们可以直接把 MCP Server 跑在 QGIS 的 Python 解释器里。

架构上可以这样理解：

• AI 客户端承载模型对话，暴露 MCP 工具列表给模型。
• MCP Server 做协议解析，把“调用某个工具”翻译成“执行某段 PyQGIS 代码”。
• PyQGIS 代码访问当前 QGIS 数据，把结果返回给 MCP Server。
• MCP Server 再以 JSON 格式回传给 AI 客户端。

在本文演示中，我们并没有提前在 QGIS 界面中打开工程，而是由一个自定义工具 load_vector 动态加载文件。这样可以让演示更独立，也更容易复现。

3.3 与 Browser Use MCP、Playwright MCP 的区别

很多人刚开始接触 MCP 时，会看到类似 Browser Use MCP、Playwright MCP 的工具。它们也是 MCP Server，但操作对象不同：

这些 MCP 工具的共同点是：把特定软件的操作“函数化”，交给 AI 模型调度。区别在于，你可以同时加载多个 MCP Server，让 AI 在一个会话里既操作浏览器，又操作 QGIS。这也是 MCP 协议最有想象力的地方。

4. 完整实战：在 QGIS 中实现 MCP 演示服务

这一节是全文重点。我们会创建一个 QGIS MCP Demo Server，实现加载矢量文件、列出图层、统计要素数量、按表达式过滤等功能。然后把它接入 Claude Desktop，演示自然语言交互。

4.1 创建项目目录并准备数据

首先在 D:\gis_demo 目录下创建子目录 data。准备一个测试用的 GeoJSON 文件，放在 D:\gis_demo\data\demo_points.geojson。

你可以用任意 GIS 工具导出测试数据，也可以从公开数据源下载。下面是一个最小的 GeoJSON 示例：

json复制{
  "type": "FeatureCollection",
  "name": "demo_points",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 1,
        "name": "A点",
        "population": 120000
      },
      "geometry": {
        "type": "Point",
        "coordinates": [120.1, 30.2]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 2,
        "name": "B点",
        "population": 80000
      },
      "geometry": {
        "type": "Point",
        "coordinates": [120.3, 30.4]
      }
    }
  ]
}

4.2 安装 MCP 依赖

在 QGIS 自带的 Python 环境中安装 mcp 包。Windows 下可以先打开命令行，进入 QGIS 安装目录，然后执行：

bash复制cd "C:\Program Files\QGIS 3.34.4\bin"
python-qgis.bat -m pip install mcp -i https://pypi.tuna.tsinghua.edu.cn/simple

如果你使用的是更早的 QGIS 版本，可能没有 python-qgis.bat，请直接使用 QGIS 目录下对应的 Python 解释器安装。安装成功后，可以用下面命令验证：

bash复制python-qgis.bat -m pip show mcp

如果输出中包含 MCP 版本号，就说明依赖已经安装完成。

4.3 编写 QGIS MCP 服务端

下面创建 D:\gis_demo\qgis_mcp_demo_server.py。这个文件会在 QGIS Python 环境中运行，导入 qgis.core，并通过 mcp.server.fastmcp.FastMCP 暴露工具。

完整代码如下：

python复制# -*- coding: utf-8 -*-
"""
QGIS MCP Demo Server

通过 MCP 协议，把 QGIS 的图层加载、要素统计、表达式过滤能力
暴露给 AI 客户端。

运行方式:
    1. 安装 mcp 到 QGIS Python 环境
    2. 执行: python-qgis.bat qgis_mcp_demo_server.py
    3. 在 Claude Desktop / Codex 中配置 MCP Server
"""

from __future__ import annotations

import atexit
import sys
from pathlib import Path

# ========== 按实际 QGIS 安装路径调整 ==========
QGIS_ROOT = Path(r"C:\Program Files\QGIS 3.34.4")
QGIS_LTR_PREFIX = QGIS_ROOT / "apps/qgis-ltr"
PYTHON_SITE_PACKAGES = QGIS_ROOT / "apps/Python39/Lib/site-packages"

for p in [
    QGIS_ROOT / "bin",
    QGIS_LTR_PREFIX / "python",
    QGIS_LTR_PREFIX / "python/qgis",
    PYTHON_SITE_PACKAGES,
]:
    if p.exists():
        sys.path.append(str(p))

# ========== 初始化 QGIS 应用 ==========
from qgis.core import (
    QgsApplication,
    QgsExpression,
    QgsProject,
    QgsVectorLayer,
)

QgsApplication.setPrefixPath(str(QGIS_LTR_PREFIX), True)
QgsApplication.initQgis()
atexit.register(QgsApplication.exitQgis)

# ========== MCP 服务定义 ==========
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("qgis-mcp-demo")


def _find_layer(layer_name: str):
    """按名称在当前工程中查找图层，找不到返回 None。"""
    layers = QgsProject.instance().mapLayersByName(layer_name)
    if not layers:
        return None
    return layers[0]


@mcp.tool()
def load_vector(file_path: str, layer_name: str = "") -> dict:
    """加载一个矢量文件（GeoJSON/Shapefile/GeoPackage）到当前 QGIS 工程。

    Args:
        file_path: 矢量文件的绝对路径。
        layer_name: 可选，加载后显示的图层名称，默认使用文件名。
    """
    path = Path(file_path)
    if not path.exists():
        return {"success": False, "error": f"文件不存在: {path}"}

    name = layer_name if layer_name else path.stem
    layer = QgsVectorLayer(str(path), name, "ogr")
    if not layer.isValid():
        return {"success": False, "error": f"图层无效: {layer.lastError()}"}

    QgsProject.instance().addMapLayer(layer)
    return {
        "success": True,
        "layer_name": name,
        "feature_count": layer.featureCount(),
    }


@mcp.tool()
def list_layers() -> list[str]:
    """返回当前 QGIS 工程中的所有图层名称。"""
    layers = QgsProject.instance().mapLayers().values()
    return [layer.name() for layer in layers]


@mcp.tool()
def count_features(layer_name: str) -> dict:
    """统计指定图层的要素数量。

    Args:
        layer_name: 图层名称。
    """
    layer = _find_layer(layer_name)
    if layer is None:
        return {"success": False, "error": f"找不到图层: {layer_name}"}

    return {
        "success": True,
        "layer": layer_name,
        "feature_count": layer.featureCount(),
    }


@mcp.tool()
def get_layer_summary(layer_name: str) -> dict:
    """获取图层的字段信息、空间范围和坐标系。

    Args:
        layer_name: 图层名称。
    """
    layer = _find_layer(layer_name)
    if layer is None:
        return {"success": False, "error": f"找不到图层: {layer_name}"}

    fields = [
        {
            "name": field.name(),
            "type_name": field.typeName(),
        }
        for field in layer.fields()
    ]

    extent = layer.extent()
    return {
        "success": True,
        "layer": layer_name,
        "feature_count": layer.featureCount(),
        "fields": fields,
        "extent": {
            "x_min": extent.xMinimum(),
            "y_min": extent.yMinimum(),
            "x_max": extent.xMaximum(),
            "y_max": extent.yMaximum(),
        },
        "crs": layer.crs().authid(),
    }


@mcp.tool()
def filter_by_expression(layer_name: str, expression: str, limit: int = 20) -> dict:
    """按 QGIS 表达式过滤图层，返回匹配要素的属性字段。

    Args:
        layer_name: 图层名称。
        expression: QGIS 表达式，例如 "population" > 100000。
        limit: 最多返回的要素条数，默认 20 条。
    """
    layer = _find_layer(layer_name)
    if layer is None:
        return {"success": False, "error": f"找不到图层: {layer_name}"}

    expr = QgsExpression(expression)
    if expr.hasParserError():
        return {
            "success": False,
            "error": f"表达式解析错误: {expr.parserError()}",
        }

    fields = layer.fields()
    matched_features = []
    total_count = 0

    for feature in layer.getFeatures():
        if expr.evaluate(feature):
            total_count += 1
            if len(matched_features) < limit:
                attrs = {
                    field.name(): feature.attribute(field.name())
                    for field in fields
                }
                attrs["__id__"] = feature.id()
                matched_features.append(attrs)

    return {
        "success": True,
        "layer": layer_name,
        "match_count": total_count,
        "sample_features": matched_features,
    }


if __name__ == "__main__":
    mcp.run(transport="stdio")

代码说明：

• load_vector 用来加载本地矢量文件，是演示中最先被调用的工具。
• list_layers 和 count_features 帮助 AI 了解当前工程状态。
• get_layer_summary 返回字段、范围、坐标系，适合模型做进一步决策。
• filter_by_expression 是查询能力，支持 QGIS 表达式，返回匹配要素属性。

注意，工具函数的 docstring 和参数名会影响模型的调用准确率，建议描述得具体一些。

4.4 配置 MCP 客户端

以 Claude Desktop 为例，配置文件中增加一个 qgis-mcp-demo Server。文件位置通常在：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

参考配置如下：

json复制{
  "mcpServers": {
    "qgis-mcp-demo": {
      "command": "C:/Program Files/QGIS 3.34.4/bin/python-qgis.bat",
      "args": [
        "D:/gis_demo/qgis_mcp_demo_server.py"
      ]
    }
  }
}

如果你使用的是 Codex、VS Code 或其他 MCP 客户端，核心配置方式相同，只是“如何加载 MCP Server”的入口不一样。Codex 可以通过命令行配置 MCP，IDE 插件通常也提供 MCP Server 配置面板。

配置完成后，重启客户端。如果连接正常，客户端会读取到 load_vector、list_layers、count_features 等工具。

4.5 运行与验证

在 Claude Desktop 中打开一个新对话，直接输入：

“请加载 D:/gis_demo/data/demo_points.geojson，并告诉我这个图层有多少个要素。”

模型会调用 load_vector 和 count_features，最终回答类似：

“已加载 demo_points 图层，共 2 个要素。”

接着输入：

“过滤出 population 大于 100000 的要素，并返回所有属性。”

模型会调用 filter_by_expression，传入表达式 "population" > 100000，得到：

json复制{
  "success": true,
  "layer": "demo_points",
  "match_count": 1,
  "sample_features": [
    {
      "id": 1,
      "name": "A点",
      "population": 120000,
      "__id__": 0
    }
  ]
}

这一步验证了从自然语言到 PyQGIS 调用，再到结构化返回的完整链路。

如果你希望让 AI 直接操作当前桌面 QGIS 工程中的图层，可以基于同样的思路，把 MCP Server 嵌入到 QGIS 插件中，通过插件启动独立的 MCP 服务进程。这里不再展开，但核心工具函数完全可以复用。

5. 常见问题与排查思路

5.1 QGIS 安装相关问题

5.2 MCP 连接与 Python 环境问题

5.3 地图与图层加载问题

经常有人问“QGIS 如何下载百度或高德地图”。本质上，QGIS 支持通过 XYZ 瓦片 URL 加载在线地图。常见高德地图瓦片地址如下：

text复制https://webrd0{1-4}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}

在 QGIS 中可以通过“XYZ Tiles”新建连接，然后填入上面的 URL。需要注意的是，在线底图服务通常有使用条款，请阅读服务商说明后再用于正式项目。

加载天地图时，必须在 URL 中携带合法的密钥。如果加载失败，优先检查密钥是否有效，以及请求域名是否被服务商允许。高德、百度等国内地图还可能涉及坐标系差异，建议结合具体需求选择相匹配的坐标参考系。

5.4 QGIS 表达式过滤异常

如果你在调用 filter_by_expression 时看到“表达式解析错误”，通常是因为字段名没有加双引号，或者字符串值没有加单引号。

正确示例：

text复制"population" > 100000
"province" = '浙江'

错误示例：

text复制population > 100000
province = 浙江

QGIS 表达式中的字段名必须用双引号包裹，字符串字面量用单引号包裹。这也是 AI 模型最容易犯的错误之一，建议在工具描述中明确写出示例。

6. 最佳实践与工程建议

6.1 安全边界：先只读，再写操作

QGIS-MCP 的最大风险不是技术，而是权限。如果 AI 客户端能够通过 MCP 调用 QGIS 工具，那么任何能控制客户端的人，都可能间接控制 GIS 数据。

推荐的安全策略如下：

• 第一个版本只暴露只读工具，比如查询、统计、图层信息读取。
• 不暴露删除要素、修改字段、覆盖文件等高风险工具。
• 如果确有写操作需求，增加二次确认步骤，比如要求 AI 先返回待执行 SQL 或操作说明，由人工确认后再执行。
• 所有工具调用都写入日志，方便回溯。

如果你后续把 MCP 用于数据库操作，比如通过 IDE 插件中的 MCP 连接 Oracle，同样要遵循最小权限原则。数据库账号只授予查询权限，使用预编译 SQL 模板，避免 AI 生成危险语句。

6.2 工具定义要清晰

MCP 模型会根据工具名称、参数名、docstring 来决定调用方式。命名混乱的工具会让 AI 频繁选错。

建议：

• 工具名使用动词开头，例如 load_vector、filter_by_expression。
• 参数名尽量见名知意，例如 file_path、layer_name。
• docstring 中给出表达式示例，降低 AI 试错成本。
• 返回值统一用字典，包含 success 字段，便于模型判断执行结果。

6.3 坐标系与数据规范

QGIS 中跨图层分析时，坐标系不一致是最常见的坑。在 MCP 工具中，建议返回每个图层的 CRS 信息，例如 EPSG:4326 或 EPSG:3857。

如果 AI 需要做空间关联或距离计算，优先让它先将图层转换到统一坐标系，再进行后续操作。不要在原始数据上直接做有空间单位依赖的计算，尤其是涉及经纬度坐标时。

6.4 日志与性能控制

MCP Server 启动在本地，但工具可能处理大数据量。建议在每个函数入口和出口记录日志，包含：

• 调用时间。
• 工具名称。
• 传入参数。
• 返回结果大小。
• 耗时。

对于图层查询，设置合理的结果上限非常重要。本文示例中的 limit 参数默认 20，是为了避免 AI 一次性获取海量要素，导致上下文窗口溢出。

6.5 在线地图服务注意事项

如果你在 QGIS 中加载国内在线地图服务，比如天地图、高德、百度，需要注意：

• 天地图需要注册开发者账号并申请密钥，密钥会绑定域名或 IP。
• 高德、百度地图服务有并发和调用量限制，不适合作为高并发数据处理底座。
• 在线底图可能存在坐标偏移，叠加本地矢量数据前要先检查 CRS 是否匹配。

在实际项目中，更推荐将在线底图作为“背景参考”，核心空间分析仍然基于本地矢量数据完成。

7. 从演示到生产：下一步学习路线

本文的 QGIS-MCP 演示项目已经完成了“AI 调工具、工具调 QGIS”的闭环。如果你是第一次接触这一组合，可以按下面的路线继续深入。

7.1 扩展 PyQGIS 工具集

MCP 只是通信协议，真正的业务能力来自 PyQGIS。下一步可以尝试增加更多工具，例如：

• 按字段分组统计，返回汇总结果。
• 图层缓冲区分析，生成新的结果图层。
• 坐标转换，把图层在 WGS84 和 Web Mercator 之间切换。
• 地图视图导出，把当前画布输出为 PNG。

每增加一个工具，都要考虑参数校验、异常捕获和返回值结构。

7.2 把演示服务插件化

目前演示服务器是独立进程，与用户在 QGIS 界面中看到的图层并不完全同步。更贴近实际使用的方式，是把 MCP Server 做成 QGIS 插件。

插件启动时，后台拉起一个 MCP 服务进程；工具函数通过 QGIS 内部通信，直接操作插件所在工程的图层。这样 AI 就能操作“你正在看的那个 QGIS 工程”，而不是一个独立的数据副本。

7.3 接入更多数据类型

GIS 数据不可能只有 GeoJSON。你可以继续扩展：

• 连接 PostGIS 数据库，读取空间表。
• 支持 MapInfo TAB、GML、KML 等格式。
• 接入手腕影像、DEM、栅格数据。
• 结合 QGIS Processing 算法，实现空间分析自动化。

每一步扩展，都需要在工具描述中写清楚输入输出，否则 AI 模型很难正确使用。

7.4 关注 MCP 生态变化

MCP 协议还处在快速发展期，新的客户端、SDK 和周边工具几乎每周都会出现。从项目实践角度看，不要追着每一个新客户端跑，而是把 MCP Server 的工具定义做规范、做稳定。这样无论客户端怎么换，你的 GIS 能力层都可以复用。

如果你也在折腾 QGIS 与 MCP 的联动，建议先用本地小数据跑通全流程，再逐步把真实业务数据接入进来。工具权限、日志审计、表达式测试这三件事做到位，QGIS-MCP 才能真正从“演示”走向“可用”。