QGIS MCP – 基于模型上下文协议的AI驱动QGIS控制

是什么 – 一个两部分的开源工具，允许任何支持 模型上下文协议（MCP）的AI模型直接与QGIS通信。一个轻量级TCP服务器（MCP服务器）在QGIS外部运行，暴露118个基于JSON的命令（图层管理、编辑、处理、渲染等）。在QGIS内部，一个非阻塞插件接收这些命令并调用PyQGIS API，因此LLM可以从常规的编码助手客户端（Claude Code、Codex CLI、Gemini等）创建项目、编辑要素、运行处理算法、渲染地图等。

核心组件

组件	作用
QGIS插件 (`qgis_mcp_plugin/`)	在QGIS内部运行，托管一个TCP套接字，接收MCP JSON命令并映射到PyQGIS调用。
MCP服务器 (`src/qgis_mcp/server.py`)	作为独立进程运行（通过`uvx`启动）。实现118个MCP工具并通过套接字转发给插件。

架构如下：

AI代理 ⇄ MCP服务器 (FastMCP) ⇄ TCP套接字 ⇄ QGIS插件 ⇄ PyQGIS API

主要功能（精选工具）

项目 – 创建、加载、保存、查询CRS。
图层 – 添加/移除矢量、栅格、网络图层；设置可见性；查询范围。
要素 – 列出、添加、更新几何、删除、选择、计算统计信息。
样式 – 应用QML、设置分类/分级样式、标签设置。
处理 – 运行任何QGIS处理算法、批量执行、模型处理。
渲染 – 生成地图图像、3D截图、画布截图。
布局与图册 – 创建布局、添加地图/图例/比例尺、导出PDF、运行图册。
系统 – ping、诊断、执行任意Python代码、批量命令。

所有工具均为异步，具有人类可读的标题，并包含注解（readOnly、destructive、idempotent）。破坏性操作尊重客户端的确认UI；可通过设置QGIS_MCP_AUTO_CONFIRM=0强制服务器再次请求确认。

安装与设置

QGIS插件 – 在QGIS中进入 插件 → 管理和安装插件，搜索 QGIS MCP，安装并重启，点击新停靠窗口中的 启动服务器。
MCP服务器 – 需要Python包管理器 uv。在任意终端运行客户端特定的代码片段，例如Claude Code：
```
claude mcp add -s user qgis \
    -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server
```
（为Codex、Gemini、Kimi、Copilot CLI、LM Studio、Opencode、Hermes等也提供了类似的uvx命令。）
当您发出MCP调用时，客户端会自动启动服务器；它会下载归档文件，缓存并运行qgis-mcp-server。

可选配置 – 环境变量可更改主机/端口、启用共享密钥（QGIS_MCP_TOKEN）、运行多个QGIS实例、在细粒度（118）或复合（27）工具集中选择，以及控制日志记录。

快速使用示例

您可访问QGIS工具。请执行以下操作：
1. ping
2. create_new_project path="/tmp/my_project.qgz"
3. add_vector_layer path="resources/data/world_map.gpkg"
4. filter features where adm0_a3 = "USA"
5. render_map width=800 height=600
6. save_project

发送到LLM客户端后，模型将调用相应的MCP工具，QGIS窗口最终将显示美国的渲染地图。

更新

插件 – 通过QGIS插件管理器更新（或通过管理器重新安装ZIP文件）。

服务器 – 刷新缓存的包：

uvx --refresh-package qgis-mcp \
    --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server

然后重启客户端。

贡献与测试

git clone https://github.com/nkarasiak/qgis-mcp.git
cd qgis-mcp
python install.py   # 链接插件并写入MCP客户端配置

无需QGIS的单元测试通过 uv run pytest tests/test_mcp_tools.py 运行。需要运行中QGIS实例的集成测试使用 uv run pytest tests/test_qgis_live.py。

许可证

QGIS插件 – GNU GPL v2 或更高版本。
MCP服务器 – MIT。

总结 – QGIS MCP将任何MCP兼容的LLM转变为功能齐全的GIS助手，使开发者和分析师能够通过自然语言提示或代码补全工具完全脚本化QGIS。

nkarasiak/qgis-mcp

QGIS MCP – 基于模型上下文协议的AI驱动QGIS控制