QGIS MCP: How to Set It Up With Claude, and Where It Breaks

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, at the same time on the same computer, each in a fresh QGIS project: "In Lyon, France, find the schools within 300 metres of a tram stop, show them on a map with the tram lines, and tell me how many there are."

The counts differ because the two tools used different data. QGIS MCP counted OpenStreetMap schools near tram stops taken from a box around Lyon, so a few stops just outside the city count too, and it said itself that the 87 was not deduplicated. AI Agent used the city's official school registers and the Lyon commune boundary.

How they got there is the bigger difference. QGIS MCP has no data tool, so the model wrote Python to query OpenStreetMap's Overpass servers. They answered with errors (406, 504, then 502 twice), and it retried. That Python ran on QGIS's main thread, so QGIS was frozen for about seven minutes, and the map stayed empty until 7 min 22 s.

AI Agent searched its data catalogue first and loaded the city's official school layers. When the national transit feed did not label Lyon's trams, it switched to OpenStreetMap for the tram stops and tracks. It wrote Python twice, to measure the distance from each school to its nearest stop.

Three more tasks, and one where QGIS MCP was faster

One race proves little, so I timed three more tasks the same way. They don't all go our way:

When the data is one OpenStreetMap download away, QGIS MCP keeps up, and on the PDF layout it was about twice as quick. Its own answer warned that it exported the PDF without checking that the satellite tiles had loaded. The gap opens when the model has to find and download the data itself, as in Lyon. Neither tool finished the York flood task in 15 minutes. A first Porto run on 26 September took QGIS MCP 8 min 29 s because the download servers were overloaded that day, so I timed everything again.

How we measured this. Same computer, both tools running at the same time, QGIS 3.44.15, a fresh project and default settings except AI Agent's effort, set to Medium. One run each, no retries: QGIS MCP 0.15.2 driven by Claude Code on Claude Sonnet 5.5 with only the QGIS tools allowed, and AI Agent 1.9.0 in Balanced mode. QGIS MCP's time is Claude Code's own run time, which leaves out the 52 seconds the client took to start. The computer was heavily loaded and the OpenStreetMap servers were failing for both tools during the Lyon race. We filmed every run.

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.

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 the Lyon test, 6 of its 10 steps were Python, and the downloads froze QGIS for about seven minutes.
• 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.

Other ways to connect Claude to QGIS

The plugin above is the one most guides mean, but three other projects also put Claude in QGIS. Read on their own pages on 23 October 2026:

• piatkowski/qgis-mcp: a separate project with the same name, built for Claude Desktop. It installs from a ZIP on its GitHub releases page, not from the plugin manager, needs Python 3.12 or later for its server, and starts listening on port 9876 as soon as the plugin is enabled. The plugin above uses port 9876 too, so run one at a time.
• ClaudIA QGIS: derived from the plugin above, with the local port replaced by a connection to the agrônomo10X community over HTTPS, so there is no Python to install. It needs an agrônomo10X account, and its 0.2.3 release of 15 September 2026 is marked experimental.
• QGIS Agent: a chat panel inside QGIS on your own LLM key, with an optional local MCP server that Claude Desktop or Cursor can drive.

Six QGIS MCP alternatives compares these routes on setup, model, price and safety.

A QGIS MCP alternative: 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. On Google's GeoKTools and GeoExpertQueries benchmarks, Claude Sonnet 5.5 driving QGIS through this MCP plugin (version 0.15.1, in Claude Code) scored 24.9 out of 100 on 41 held-out questions, and AI Agent at Low effort (GPT-6 Luna) scored 43.8 (the benchmark results).

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 190 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 Pro free for 7 days: add a card, cancel before the end and nothing is charged.

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.

If what you want is GIS data inside the assistant, with no QGIS running at all, that's a third option: TerraLab MCP brings geodata for any place into Claude, ChatGPT, Claude Code, Codex, Cursor or VS Code: open map data, terrain, routes, satellite images and GIS file conversion, after one sign-in with a TerraLab account.

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 Lyon task, AI Agent answered in 5 min 35 s from the city's official school layers. QGIS MCP took 9 min 28 s and wrote Python for 6 of its 10 steps. On simpler tasks the gap shrinks, and on a PDF layout QGIS MCP was faster.

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, 190 open data sources and one-click undo, with a free plan. Our page of QGIS MCP alternatives compares six of them on setup, model, price and safety.

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 five real tasks with their prompts, and PyQGIS measures how often chatbot-written code runs first time. The QGIS AI hub compares the wider field.

Read nextClaude and QGIS: 3 Ways to Connect Them, Tested on One Task