What Is QGIS MCP? Setup, Limits, Easier Option

QGIS MCP is a free QGIS plugin plus a small program on your computer that let an AI app outside QGIS, usually Claude Desktop or Claude Code, control QGIS. You type in the AI app, it sends commands to QGIS over a local connection, and QGIS runs them: load layers, run Processing tools, style the map, or run Python code.

The idea is good and the plugin is well made. Nicolas Karasiak maintains the version in the official QGIS repository, which had 52,575 downloads on 26 September 2026. What tutorials skip is how much it takes to get running, and where it stops. I set it up from scratch, then gave the same task to it and to an agent that lives inside QGIS. We build that second one, AI Agent, so weigh my conclusions knowing that.

What MCP is, in one paragraph

MCP, the Model Context Protocol, is an open standard started by Anthropic that lets AI apps use outside tools. The official introduction calls it "a USB-C port for AI applications". The AI app is called the client. A server offers tools to it. QGIS MCP is a server whose tools are QGIS actions. The protocol states the risk plainly: "Tools represent arbitrary code execution and must be treated with appropriate caution."

How QGIS MCP works

Four pieces have to be installed and running at the same time:

1. An MCP client: the AI app where you type, such as Claude Desktop, Claude Code, Cursor, VS Code, Codex CLI or Gemini CLI.
2. The MCP server: a small Python program the client starts in the background through uv, a tool that installs and runs Python programs. You install uv first.
3. The QGIS MCP plugin: inside QGIS, it listens for commands on a local network port, number 9876. You click Run MCP on its toolbar button to start it.
4. QGIS itself, with your project open.

When you type a request, the AI model picks a QGIS tool, the server passes the call to the plugin, and the plugin runs it in QGIS and sends back the result. The model doesn't see your screen. It sees the map only when it asks QGIS for a picture of it.

What you need before you start

A widely read setup guide says you need a paid Claude Pro account. You don't. Anthropic's documentation for local MCP servers names no plan, and a GIS blogger ran QGIS MCP on Claude's free tier in August 2026, only hitting the daily message cap. ChatGPT is harder. OpenAI's help centre says it connects only to MCP servers on the internet, not to one on your computer, and the developer mode it needs is for paid plans.

Setting up QGIS MCP, timed

I installed QGIS MCP 0.15.0 on QGIS 3.44 on 26 September 2026 and noted every step. The plugin's own page is upfront about it: "This plugin is only one half of the setup. You also need the qgis-mcp MCP server, which your MCP client runs to talk to QGIS."

The Configurator in the screenshot below is where you pick your client and copy the terminal command.

My run took about three minutes, but uv and a client were already installed and a script did the clicking. The first time, a person also reads the docs, installs uv and a client, and types the command.

Part of it comes back every day. After a QGIS restart, the server stays off unless you tick auto-start in the Configurator. The AI app then only says "Error executing tool ping", and you have to guess that the fix is to click Run MCP again.

The same task, both ways

I gave both tools the same request, in a fresh QGIS project: "Load the buildings of the historic centre of Porto, Portugal from OpenStreetMap, colour them by building type, add a satellite basemap underneath, and tell me how many buildings there are."

Both counts are right for the area each tool chose, which is why they differ. How they got there is what differs. QGIS MCP has no data tool, so the model wrote Python to download OpenStreetMap data. When the download servers were slow, its retries froze QGIS for up to a minute at a time. To its credit, it caught its own bug that had dropped 37 buildings, and fixed it.

AI Agent used its built-in OpenStreetMap tool, looked up the real boundary of the historic centre, clipped the buildings to it and styled them, without writing any code. Its satellite basemap is blurrier at this zoom than the one QGIS MCP picked.

How we measured this. Same computer, QGIS 3.44.7, same request, fresh project and default settings, with QGIS MCP 0.15.0 driven by Claude Code on Claude Sonnet, and AI Agent 1.4.1. We checked both counts ourselves, against OpenStreetMap for the rectangle and by counting the final layer for the boundary. The download servers were overloaded during the QGIS MCP run, which cost it time, and a first AI Agent attempt crashed QGIS, a bug we have logged, so its figures come from the rerun.

You can send the same request in your own QGIS in a few minutes: install the plugin, sign in, and paste it into the panel.

Try AI Agent free in QGIS, no card needed

Where QGIS MCP falls short

These are the limits I hit or found documented, each with its source:

• The chat is outside QGIS. You switch between two windows. The model works from tool results, and sees the map only when it asks QGIS for a picture of it.
• Four moving parts. When nothing happens, the fault can be in the client settings, uv, the server, the port or the plugin. The project's troubleshooting page lists "No response from QGIS", Connection refused and ModuleNotFoundError as the usual errors.
• A Windows trap. The README warns that Claude Desktop installed from the Microsoft Store runs servers in a sandbox that breaks the usual setup, so a config that works elsewhere fails there.
• Any Python, no password by default. The execute_code tool runs any PyQGIS (QGIS's Python code) the model writes. The README says so: "By default the socket has no authentication... any process on the machine that can reach the port can drive QGIS (including execute_code, which runs arbitrary PyQGIS)." One fork, QGIS Agent MCP, exists mostly to remove that tool.
• No data of its own. It drives QGIS, but finding and downloading data is up to the model, usually by writing Python. In my test, 17 of its 28 actions were Python, and its download retries froze QGIS for 40 to 62 seconds at a time.
• No undo for a whole request. QGIS's undo covers edits, not layers added or files written.
• The most-starred copy is not the maintained one. The original on GitHub, jjsantos01/qgis_mcp, has 1,099 stars, no code change since 1 October 2025, and an open issue titled "Broken plugin for QGIS version 4.01". The maintained version, nkarasiak/qgis-mcp, is the one in the QGIS plugin repository.

Where the web gets this wrong

"You need Claude Pro." Local MCP servers work on Claude's free plan, within its daily limits. The paid-plan gate is on ChatGPT, which can't reach a server on your computer directly anyway.

"Restart your computer after editing the config." Restarting the client app is enough. On Windows, make sure it has fully quit, since it keeps running in the system tray.

"Install the repository with the most stars." Install from the QGIS plugin manager instead, which gives you the maintained version.

The easier option: an agent inside QGIS

We build AI Agent, so this section is about our own plugin. It does the same job as QGIS MCP from inside QGIS: the chat is a panel docked next to your map, and the model comes with the plugin.

The differences that matter day to day:

• One install. Plugins > Manage and Install Plugins, search AI Agent by TerraLab, install, sign in. No uv, no config file, no separate app, no server to start each session.
• It sees your project. Layer names, fields, CRS, extent and selection go with every request, and it renders the map to check its own work.
• Data built in. A catalogue of 55 open data sources, from OpenStreetMap to Sentinel-2 and national mapping agencies, so the model doesn't write download code.
• It asks first. On the default setting it stops before deleting or overwriting, and Python that changes your project always needs your click.
• Undo per message. Every message leaves a checkpoint, and one click returns the project to it.

It needs an internet connection and sends a description of your project, never your data files, to a service hosted in the EU. There's a free plan with no card needed, and one message counts as one task however many steps it takes.

Try AI Agent free in QGIS, no card needed

QGIS MCP vs an agent inside QGIS, side by side

Which one should you use?

If you already work in Claude Code or Cursor, write Python, and want QGIS as one more tool there, QGIS MCP is a good fit, and it costs nothing on top of the AI plan you already pay for. If you want to type a GIS task and get the result in your project, without a terminal, uv or a second app, an agent inside QGIS gets you there with less to set up and maintain. That second case is most GIS users I know.

What to remember

QGIS MCP connects an AI app outside QGIS, such as Claude Desktop, to QGIS through a local connection, so the app's model can run QGIS tools and Python.

It needs four parts running together: the client app, uv and the MCP server, the QGIS MCP plugin with its server started, and QGIS.

The QGIS side installs in seconds. The rest happens outside QGIS: installing uv, an AI app, a terminal command, and clicking Run MCP again after each restart.

On the same Porto task, AI Agent answered in 1 min 11 s with 15 actions and no code. QGIS MCP took 8 min 29 s and wrote Python for 17 of its 28 actions.

ChatGPT can't use a local MCP server directly. Claude's free plan works, within its daily limits.

An agent inside QGIS, such as AI Agent, does the same job from one plugin, with the model, a data catalogue and one-click undo included.

Questions people ask

What is QGIS MCP?

A QGIS plugin and a local MCP server that let an AI app control QGIS through the Model Context Protocol. You chat in the app, usually Claude Desktop or Claude Code, and the model calls QGIS tools: loading layers, running Processing, styling, rendering the map and running Python.

How do I connect Claude to QGIS?

Install the QGIS MCP plugin from the plugin manager and click Run MCP, install uv, then add the QGIS MCP server to Claude Desktop's config file, or run the claude mcp add command in Claude Code, and restart the client. Or install an agent plugin that runs inside QGIS with its own model, such as AI Agent, which skips the client, uv and the config.

Can ChatGPT use QGIS MCP?

Not directly. OpenAI's help centre says ChatGPT connects to MCP servers on the internet, so a server on your computer, such as QGIS MCP, would need a tunnel to be reachable. Developer mode, which MCP requires, is limited to paid ChatGPT plans.

Is QGIS MCP safe?

It can run any Python the model writes inside QGIS, and by default the local socket has no authentication, as its README states. Use it on a machine you trust, set the shared-secret token if others share the machine, stop the server when you're done, and keep backups of important projects.

Why is QGIS MCP not connecting?

The usual causes, from the project's troubleshooting guide: the server isn't started in QGIS (Connection refused, click Run MCP), uv isn't installed or can't be found (ModuleNotFoundError), or the port isn't 9876. After a QGIS restart, the server is off again unless auto-start is ticked. On Windows, a Microsoft Store install of Claude Desktop needs the --directory form of the config.

Is there an alternative to QGIS MCP?

Yes. Agent plugins run inside QGIS as a chat panel, with no outside app or local server. We counted 38 agent and assistant plugins in the official repository in September 2026. Ours, AI Agent, includes the model, 55 open data sources and one-click undo, with a free plan.

What an AI agent in QGIS is counts all 38 agent and assistant plugins in the official repository, MCP bridges included. The AI Agent guide shows ten real runs with their prompts, and PyQGIS measures how often chatbot-written code runs first time. The QGIS AI hub compares the wider field.