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 Socket，接收MCP JSON指令並對應至PyQGIS呼叫。
MCP伺服器 (`src/qgis_mcp/server.py`)	作為獨立程序執行（透過`uvx`啟動）。實作118個MCP工具並透過Socket轉送至插件。

架構如下：

AI代理 ⇄ MCP伺服器 (FastMCP) ⇄ TCP Socket ⇄ 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控制