内容
# QGIS MCP 服务器
<div align="center">
<img src="assets/banner.png" alt="QGIS MCP Banner" width="100%" style="border-radius: 8px; margin: 20px 0;">
<p><strong>通过模型上下文协议（MCP）为 LLM 控制暴露 QGIS API（适用于 Claude、Antigravity、Gemini）</strong></p>
[](https://github.com/LeoDev2p/mcp_qgis)
[](https://qgis.org/)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
</div>
## 连接 QGIS 到 Claude AI、Antigravity 和 Gemini
通过模型上下文协议（MCP）将 [QGIS](https://qgis.org/) 连接到 [Claude AI](https://claude.ai/)、[Antigravity](https://antigravity.ai/) 和 [Gemini](https://gemini.google.com/)，这允许 LLM 直接控制 QGIS：管理图层、编辑要素、运行处理算法、生成地图等。
## 架构
- **无 GUI：** 使用自然语言命令
- **无 REST API：** 本地 TCP 套接字通信
- **安全：** 仅在 localhost 上可访问
- **强大：** 完全访问地理处理、分析和可视化
## MCP 架构
```
Claude ←→ MCP 服务器 (FastMCP) ←→ TCP 套接字 ←→ QGIS 插件 (QTimer) ←→ PyQGIS API
(LLM) (localhost:9876) (异步) (事件监听器) (桌面)
```
**详细说明：**
- **Claude：** 请求工具（"加载 cities.shp"）
- **MCP 服务器：** 接收请求，翻译成 JSON-RPC，通过 TCP 发送
- **TCP 套接字：** 在端口 9876 上进行异步双向通信
- **QGIS 插件：** 使用 QTimer 监听，执行命令，返回结果
- **PyQGIS API：** 原生访问 QgsProject、处理、渲染
## 使用的技术
- **QGIS** 3.22 LTR+ - 桌面 GIS 应用程序
- **FastMCP** - Python 中的模型上下文协议实现
- **Python** 3.10+ - 核心语言
- **uv** - 快速 Python 包管理器
- **PyQt/Qt** - QGIS 插件 UI
- **AsyncIO** - TCP 异步 JSON-RPC 通信
## 安装 uv
**uv** 是此项目的包管理器。为您的操作系统安装它：
### Windows
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### macOS / Linux
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 验证安装
```bash
uv --version
```
[官方 uv 文档](https://docs.astral.sh/uv/getting-started/installation/)
## 先决条件
| 组件 | 版本 | 备注 |
|-----------|---------|-------|
| **QGIS** | 3.22 LTR+ | 桌面应用程序（非服务器） |
| **Python** | 3.12 | 包含在 QGIS 中 |
| **uv** | 最新 | 包管理器 |
| **Git** | 最新 | 版本控制 |
| **操作系统** | Windows / macOS / Linux | 任意 |
**安装 QGIS：**
- Windows：[从 qgis.org 下载](https://qgis.org/download/) 或 `winget install QGIS`
- macOS：[从 qgis.org 下载](https://qgis.org/download/) 或 `brew install qgis`
- Linux：`apt install qgis`（Ubuntu/Debian）或 `dnf install qgis`（Fedora）
## 仓库安装和配置
### 1. 克隆仓库
```bash
git clone https://github.com/LeoDev2p/mcp_qgis.git
cd mcp_qgis
```
### 2. 使用 uv 同步依赖项
```bash
uv sync
```
### 3. 在 QGIS 中安装插件
```bash
# Linux/macOS
cp -r plugin_mcp_qgis ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/
# Windows (PowerShell)
Copy-Item plugin_mcp_qgis -Destination "$env:APPDATA\QGIS\QGIS3\profiles\default\python\plugins" -Recurse
```
### 4. 在 QGIS 中激活和配置插件
1. **打开 QGIS 桌面版**
2. **菜单：** 插件 → 管理和安装插件
3. **搜索：** "QGIS MCP 服务器"
4. **勾选：** 启用
5. **关闭窗口**
6. 在工具栏中，点击 🔌 **"QGIS MCP 服务器"** 图标激活 TCP 服务器
**验证：**
- 您将看到：”QGIS MCP 服务器已在 localhost:9876 启动“
- 日志文件：`mcp_qgis/log/mcp_qgis.log`
- 实时查看：`tail -f log/mcp_qgis.log`
**环境变量（可选）：**
```bash
set QGIS_MCP_PORT=9876 # 端口（默认 9876）
set QGIS_MCP_HOST=localhost # 主机（始终为 localhost，版本 0.1.0）
set PYTHONPATH=C:\path\to\mcp_qgis # QGIS 库路径
set PATH_SKILLS: c:\\path\\to\\skills # 技能路径
```
**就绪。** 服务器正在 `localhost:9876` 上监听
## LLM 配置
### Claude 桌面版
**配置文件：**
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
**添加此配置：**
```json
{
"mcpServers": {
"qgis": {
"command": "uv",
"args": [
"--directory",
"C:\\path\\to\\mcp_qgis",
"run",
"python",
"-m",
"src.mcp_qgis.server"
],
"env": {
"PYTHONPATH": "C:\\path\\to\\mcp_qgis",
// 可选
"PATH_SKILLS": "c:\\path\\to\\skills",
"QGIS_MCP_HOST": "localhost",
"QGIS_MCP_PORT": "9876"
}
}
}
}
```
### Antigravity
**添加到您的 MCP 配置：**
```json
{
"qgis": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_qgis",
"run",
"python",
"-m",
"src.mcp_qgis.server"
],
"env": {
"PYTHONPATH": "/path/to/mcp_qgis",
// 可选
"PATH_SKILLS": "c:\\path\\to\\skills",
"QGIS_MCP_HOST": "localhost",
"QGIS_MCP_PORT": "9876"
}
}
}
```
### Gemini / Google
**类似配置：** 使用与 Claude 桌面版相同的模式。查看 Google 文档以获取确切的配置文件位置。
**⚠️ 重要：** 替换 `/path/to/mcp_qgis` 为您的目录的**完整绝对路径**（Windows：使用路径 `C:\`，Linux/macOS：使用 `~` 或完整路径）。
## 可用工具
### 图层管理
| 工具 | 描述 | 参数 |
|------|-------------|-----------|
| **load_layer_from_path** | 加载地理空间文件 | `path`（字符串），`name`（字符串，可选） |
| **remove_layer** | 从项目中删除图层 | `layer_id`（字符串） |
| **get_project_context** | 获取图层、CRS、元数据 | - |
### 地理处理
| 工具 | 描述 | 参数 |
|------|-------------|-----------|
| **search_geoprocessing_tools** | 搜索 QGIS/GRASS/SAGA 算法 | `query`（字符串） |
| **get_algorithm_details** | 检查算法参数 | `algorithm_id`（字符串） |
| **run_processing** | 执行算法 | `algorithm_id`，`params`（字典） |
### 分析和读取
| 工具 | 描述 | 参数 |
|------|-------------|-----------|
| **get_layer_features** | 读取要素、属性、几何图形 | `layer_id`，`limit`，`offset` |
| **execute_code** | 在 QGIS 上下文中执行 Python | `code`（字符串，⚠️ 危险） |
| **ping** | 检查连接性 | - |
### 实用工具
| 工具 | 描述 | 参数 |
|------|-------------|-----------|
| **show_message** | 在 QGIS 中显示对话框 | `text`（字符串），`level`（信息/警告/错误） |
| **delete_file** | 从磁盘中删除文件 | `path`（字符串，⚠️ 永久） |
**在 Claude 中的使用示例：**
```
"将文件 /data/cities.shp 加载为 'Cities' 并告诉我它有多少个要素"
```
Claude 将使用：`load_layer_from_path()` → `get_layer_features()`
## 技能（扩展功能）
### 什么是技能？
**技能** 是用于常见地理空间任务的预定义自动化（配方/工作流程）。它们以 Markdown 编写，LLM 可以自动发现、阅读和实施它们。
**技能示例：**
- 从 Landsat 图像计算 NDVI
- 创建点缓冲区
- 空间插值（克里金法）
- 森林砍伐分析
- 多个图层的批量处理
### 下载技能
```bash
# 克隆技能仓库
git clone https://github.com/LeoDev2p/skills_gis.git
# 将技能复制到 LLM 配置中的环境变量
"PATH_SKILLS": "c:\\path\\to\\skills"
# 查看 LLM 设置部分
```
### 与技能交互的工具
| 工具 | 描述 | 参数 |
|------|-------------|-----------|
| **list_skills** | 发现所有可用技能 | - |
| **read_skill** | 读取技能的 Markdown 说明 | `skill_name`（字符串） |
**使用示例：**
```
Claude: “我有哪些可用的技能？”
→ list_skills() 返回：[“ndvi_calculator”, “buffer_analysis”, “kriging_interpolation”]
Claude: “解释如何使用 ndvi_calculator”
→ read_skill("ndvi_calculator") 返回带有步骤的 Markdown 内容
```
## 安全
### 关键警告
- **仅限本地使用：** 不要在共享网络上暴露
- **`execute_code` 很强大：** 无限制执行 Python
- **`delete_file` 是破坏性的：** 永久删除数据（无回收站）
### 当前缓解措施（v0.1.0）
- TCP 连接仅在 `localhost` 上（非远程）
- 需要手动插件激活
- 以当前用户身份运行（无提升）
- 所有命令都已记录
### 计划改进（v0.3.0+）
- [ ] `execute_code` 的 RestrictedPython 沙盒
- [ ] 令牌身份验证
- [ ] TLS 加密
**查看 [SECURITY.md](SECURITY.md) 以获取完整详细信息和责任披露。**
## 贡献和资源
### 贡献者
- [CONTRIBUTING.md](CONTRIBUTING.md) - 开发指南
- 使用 uv 设置
- 代码标准
- 拉取请求工作流程
### 安全
- [SECURITY.md](SECURITY.md) - 安全策略
- 记录的风险
- 责任披露
- 补丁 SLA
### 其他资源
- [模型上下文协议](https://modelcontextprotocol.io/)
- [QGIS 文档](https://docs.qgis.org/)
- [FastMCP GitHub](https://github.com/modelcontextprotocol/python-sdk)
- [uv 文档](https://docs.astral.sh/uv/)
## 许可证
MIT 许可证 - 查看 [LICENSE](LICENSE)
