QGIS MCP, published by Nicolas Karasiak, connects QGIS Desktop to AI assistants through the Model Context Protocol. The nkarasiak/qgis-mcp repository presents it as a QGIS integration using a FastMCP server, TCP socket, and QGIS plugin. In the GitHub check on August 26, 2026, the repository was GPL-2.0 licensed, had 257 stars and 68 forks, and pyproject listed qgis-mcp 0.11.0 with Python 3.12 or newer for the server.
For Educasium, QGIS MCP is the core GIS connector in this series. Mapbox MCP is faster for access maps and routes; QGIS MCP is better when the user needs to manipulate layers, inspect features, run processing algorithms, render maps, and work inside a real QGIS project.
Contents
- What QGIS MCP does
- Client, server, and plugin architecture
- Installation and verification
- Exposed GIS tools
- Python versions and QGIS compatibility
- Comparison with Mapbox and EnergyPlus
- Security, limits, and production use
- Educasium position
What QGIS MCP Does
Key point: QGIS MCP gives an AI assistant controlled access to an open QGIS project, including layers, features, styles, processing, rendering, and layouts. The README announces 118 tools and support for QGIS 3.28 through 4.x.
A bridge into desktop GIS
QGIS is open-source desktop GIS software. QGIS MCP does not try to replace the graphical interface; it adds a conversational and programmable layer on top of the project. An assistant can list layers, inspect an attribute table, modify features, run a processing algorithm, or generate a visual output.
This positioning matters. In GIS, project context is decisive: coordinate reference system, data sources, styles, file paths, temporary layers, filters, and selections. QGIS MCP can access that live context, while an API-first mapping tool like Mapbox MCP mainly works from requests and coordinates.
What not to promise
The README describes broad coverage, but a serious article should not turn that into a promise to replace a GIS specialist. Results still depend on loaded layers, data quality, projections, file permissions, and installed QGIS plugins.
For territorial or regulatory decisions, the assistant can accelerate exploration, but it cannot validate the data alone. Official layers, methodology, and final cartographic outputs still need review.
Client, Server, And Plugin Architecture
Key point: QGIS MCP runs through three pieces: AI client, FastMCP server, and QGIS plugin communicating over a TCP socket. The README diagrams a flow from client to MCP server, TCP socket, QGIS plugin using QTimer, and the PyQGIS API.
Why this architecture
QGIS is not just a web API. The plugin runs inside QGIS, so it can access the open project and PyQGIS functions. The MCP server provides the standard interface for AI clients. The socket communication separates the MCP client from the desktop application while keeping actions inside QGIS.
This separation has a practical advantage: the AI client can be Claude Desktop, Claude Code, Codex CLI, VS Code, Cursor, Gemini CLI, Qwen, Kimi, LM Studio, or other clients listed in the README. The same QGIS plugin can be driven by different environments if configured correctly.
User impact
The user needs QGIS open and the plugin server started. If QGIS is closed, the plugin is not running, or the socket is not reachable, the MCP server cannot act on the project. That is normal for a bridge into a desktop application.
In training, show the system state: QGIS open, project loaded, QGIS MCP dock visible, server started, and MCP client connected. Otherwise failures look like AI problems when they often come from application lifecycle.
Installation And Verification
Key point: installation should be verified with the ping tool returning a pong JSON response. This small check prevents starting a workshop with a broken QGIS bridge.
QGIS-side install
The README describes installation through the QGIS plugin manager: open Plugins, Manage and Install Plugins, search for QGIS MCP, install, restart QGIS if needed, then start the server from the dock widget. This part happens inside QGIS and depends on the local version.
The client side uses uvx from the GitHub repository, with qgis-mcp-server defined in pyproject.toml. The verified pyproject declares qgis-mcp 0.11.0, Python >=3.12, mcp[cli] >=1.20.0,<3, and pydantic >=2.11,<3.
Minimal verification
The documented check is the ping tool, which should return {"pong": true}. It is a good control because it validates the MCP client, Python server, and communication with QGIS.
After ping, the next check should be non-destructive: list project layers, read project metadata, or inspect the map extent. First write operations, such as editing features or styles, should be tested on a copy of the project.
Exposed GIS Tools
Key point: coverage spans layers, features, processing, rendering, style, project, connections, and layouts. The announced 118 tools should be understood as a broad surface, not a guarantee that every QGIS plugin workflow is covered.
Families found in code
The repository check found plugin handlers for canvas, connections, features, layers, layout, processing, project, style, and system. On the server side, src/qgis_mcp/client.py, compound_tools.py, helpers.py, protocol.py, and server.py structure the MCP interface.
In practice, this covers opening and describing a project, manipulating layers, reading and modifying features, running QGIS processing, styling, rendering, managing layouts, and querying the environment. The strength of the project is its anchoring inside QGIS: it works with data already present in the project.
Teaching examples
A useful workshop can start with a simple project: parcels, public facilities, and transport. The assistant lists layers, filters an area, computes an intersection, applies a style, produces a map, then explains the assumptions.
The value is not only automation. It is traceability: the learner sees which layer is used, which algorithm runs, and which result is created. The teacher can then separate time saved, data error, and reasoning error.
Python Versions And QGIS Compatibility
Key point: the server requires Python 3.12+, but the plugin must remain compatible with QGIS's bundled interpreter, which can still be Python 3.9. This nuance is explicitly documented in pyproject.toml comments.
A constraint to explain
pyproject declares requires-python >=3.12 for the server package. Its Ruff rules also note that the plugin runs inside QGIS's bundled interpreter, and QGIS releases beyond the 3.28 minimum can still ship Python 3.9. The comments cite QGIS 3.42 shipping Python 3.9.
That means two Python environments matter: the Python that launches the MCP server and the Python embedded in QGIS for the plugin. An article that only says Python 3.12+ is incomplete. An article that only says QGIS 3.28 to 4.x is incomplete too.
Installation discipline
Before training or integration, record the QGIS version, embedded Python version, plugin version, server version, and MCP client. If a command fails, that matrix helps identify whether the issue comes from the server, the plugin, QGIS, or the open project.
This is especially important on Windows, where paths, user profiles, uv environments, and QGIS installations vary significantly between machines.
Comparison With Mapbox And EnergyPlus
Key point: QGIS MCP is the right choice when geographic data already exists as layers, files, or a GIS project. Mapbox MCP is more direct for location APIs, and EnergyPlus MCP works on energy models.
| Need | QGIS MCP | Mapbox MCP | EnergyPlus MCP |
|---|---|---|---|
| Work inside a GIS project | Strong fit | Limited | Out of scope |
| List and modify layers | Strong fit | Not central | Out of scope |
| Geocode or calculate quick routes | Possible depending on data | Strong fit | Out of scope |
| Simulate a building | Out of scope | Out of scope | Strong fit |
| Teach GIS method | Strong fit | Good complement | Energy complement |
Coherent workflow
A realistic workflow can start with Mapbox MCP to locate a site and create a first access hypothesis. QGIS MCP then handles official layers, zoning, constraints, and facilities. EnergyPlus MCP only enters when a building energy model needs to be loaded, modified, or simulated.
This separation avoids a common mistake: choosing the most spectacular tool instead of the one that matches the data. QGIS MCP is less immediate than an API map, but it is more serious for a real GIS dossier.
Security, Limits, And Production Use
Key point: an assistant controlling QGIS can modify data and projects, so work on copies, log actions, and review outputs. The power of GIS increases the risk of silent mistakes.
Main risks
The risks are not only technical. A wrong projection, outdated layer, misunderstood filter, or feature edit on the wrong file can produce a false but convincing result. When the assistant runs processing tools, the user needs to know where outputs are written and which temporary layers were created.
Client projects should be opened as copies or under version control where possible. Destructive actions should be separated from inspection actions. The first use of a new tool should be non-destructive.
Production governance
For a professional team, QGIS MCP needs project profiles, naming conventions, output folders, and human validation of final maps. The assistant can produce a first map, but publishing a plan, regulatory analysis, or client map remains a professional responsibility.
That limit should be clear on Educasium. The reader should leave with a method: verify connection, inspect data, run processing, control the result, and document assumptions.
Educasium Position
Key point: Educasium should present QGIS MCP as augmented GIS method, not conversational magic. It is useful precisely because it forces discussion of layers, processing, and evidence.
What to teach
The best angle is a guided exercise: load a QGIS project, list layers, ask a territorial question, ask the assistant to choose a processing step, execute it, and verify in QGIS. The learner should see the result and understand the data chain.
This fits Educasium's promise: learning to work with AI inside professional software without losing methodological control. QGIS MCP is a strong resource page because it shows both MCP potential and the need for expert validation.
Next step
The natural next step connects QGIS MCP to Mapbox MCP for fast maps and to EnergyPlus MCP for building simulation. Official layers, coordinate systems, and processing assumptions still matter as much as the assistant's answer.