QGIS MCP – AI‑driven control of QGIS

What it is – A two‑part open‑source tool that lets any AI model that supports the Model Context Protocol (MCP) talk directly to QGIS. A lightweight TCP server (the MCP server) runs outside QGIS and exposes 118 JSON‑based commands (layer management, editing, processing, rendering, etc.). Inside QGIS a non‑blocking plugin receives those commands and calls the PyQGIS API, so an LLM can create projects, edit features, run processing algorithms, render maps, and more – all from a normal coding‑assistant client (Claude Code, Codex CLI, Gemini, etc.).

Core components

Component	Role
QGIS plugin (`qgis_mcp_plugin/`)	Runs inside QGIS, hosts a TCP socket that accepts MCP JSON commands and maps them to PyQGIS calls.
MCP server (`src/qgis_mcp/server.py`)	Runs as a separate process (started via `uvx`). It implements the 118 MCP tools and forwards them to the plugin over the socket.

The architecture is:

AI agent ⇄ MCP server (FastMCP) ⇄ TCP socket ⇄ QGIS plugin ⇄ PyQGIS API

Highlights (selected tools)

Project – create, load, save, query CRS.
Layers – add/remove vector, raster, web layers; set visibility; query extents.
Features – list, add, update geometry, delete, select, compute statistics.
Styling – apply QML, set categorized/graded styles, label settings.
Processing – run any QGIS processing algorithm, batch execution, model handling.
Rendering – produce map images, 3‑D screenshots, canvas screenshots.
Layouts & Atlas – create layout, add map/legend/scalebar, export PDFs, run atlas.
System – ping, diagnostics, execute arbitrary Python code, batch commands.

All tools are asynchronous, carry human‑readable titles, and include annotations (readOnly, destructive, idempotent). Destructive actions respect the client’s confirmation UI; the server can be forced to ask again with QGIS_MCP_AUTO_CONFIRM=0.

Installation & setup

QGIS plugin – In QGIS go to Plugins → Manage and Install Plugins, search for QGIS MCP, install, restart, and click Start Server in the new dock widget.
MCP server – Requires the Python package manager uv. From any terminal run one of the client‑specific snippets, e.g. for Claude Code:
```
claude mcp add -s user qgis \
    -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server
```
(Similar uvx commands are provided for Codex, Gemini, Kimi, Copilot CLI, LM Studio, Opencode, Hermes, etc.)
The server is launched automatically by the client when you issue an MCP call; it downloads the archive, caches it, and runs qgis-mcp-server.

Optional configuration – environment variables let you change host/port, enable a shared secret (QGIS_MCP_TOKEN), run multiple QGIS instances, choose between granular (118) or compound (27) tool sets, and control logging.

Quick usage example

You have access to QGIS tools. Do the following:
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

When sent to the LLM‑client, the model will invoke the corresponding MCP tools, and the QGIS window will end up with a rendered map of the United States.

Updating

Plugin – Updated through QGIS’s plugin manager (or by reinstalling the zip via the manager).

Server – Refresh the cached package with:

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

Then restart the client.

Contributing & testing

git clone https://github.com/nkarasiak/qgis-mcp.git
cd qgis-mcp
python install.py   # symlinks the plugin and writes MCP client configs

Unit tests (no QGIS needed) run with uv run pytest tests/test_mcp_tools.py. Integration tests that require a running QGIS instance use uv run pytest tests/test_qgis_live.py.

License

QGIS plugin – GNU GPL v2 or later.
MCP server – MIT.

Bottom line – QGIS MCP turns any MCP‑compatible LLM into a full‑featured GIS assistant, letting developers and analysts script QGIS entirely through natural‑language prompts or code‑completion tools.

nkarasiak/qgis-mcp

QGIS MCP – AI‑driven control of QGIS