Control QGIS with an AI Agent: Mapsuke Plugin

Introduction

Mapsuke is a plugin that lets an AI agent operate QGIS for you. You chat with the agent in a QGIS panel, in any language you speak, and it does the work. You can connect the Claude Code or Codex CLI you already use, as is.

Mapsuke is useful for experienced QGIS users, and just as useful if you know what you want to do but not which tool to use. This article walks through installation, your first chat, and making a map. If you already have Claude Code or Codex CLI, you can be chatting within a few minutes.

What is Mapsuke?

Mapsuke is a QGIS plugin developed by MIERUNE and published as open source (GPL v2). When you send a message in the chat, the agent writes Python code that operates QGIS, Mapsuke runs it, and the result goes back to the agent. This loop repeats, carrying the work forward from loading data and analyzing it to finishing the map.

Mapsuke supports QGIS 3.44 and later. You also need to install Claude Code or Codex CLI separately, and have a subscription to the service you use or an API key.

No MCP server setup required

Some approaches connect an AI agent to QGIS through an MCP (Model Context Protocol) server. Mapsuke works the other way around: it calls Claude Code or Codex CLI from the QGIS side, so you do not need to build a server or edit a configuration file.

Uses QGIS Processing tools first

The agent knows which Processing tools are installed in QGIS and prefers an existing tool to writing its own code. Tools from plugins you add are treated the same way, so you get the same results as when you work by hand.

Installation and initial setup

Before you start: install Claude Code or Codex CLI

Mapsuke works by calling the CLI installed on your PC, so install Claude Code or Codex CLI first. See each tool's official documentation for the steps.

• Claude Code
• Codex CLI

Each service requires a subscription (paid plan) or an API key, and the fees are yours to pay. This is the only step that uses the terminal; everything after that happens in the Mapsuke panel.

Install the plugin

Next, install the plugin in QGIS. From the menu bar, choose Plugins → Manage and Install Plugins. On the All tab, enter Mapsuke in the search field, select Mapsuke, and click Install Plugin.

For more on installing plugins, see the following article.

Start a new session and sign in

Open Mapsuke from the Plugins menu or the toolbar icon. At the top of the panel, click the New session button and choose the agent to use, Claude or Codex.

If you need to sign in, the panel tells you how. Sign in through your browser, and you return to QGIS automatically.

If the CLI is not found, or to use an API key

If Mapsuke cannot find the CLI, or you want to use an API key instead of a subscription, click the Settings button at the top of the panel. On the Claude or Codex tab, set the following in General.

1. Executable: click Browse… and select the CLI executable
2. Authentication: select Subscription (CLI sign-in) or API key
3. API key: enter your key if you chose API key as the Authentication method

Your first chat

Send a simple instruction

Start with a light instruction to see how Mapsuke works. Leave the approval mode, which is covered below, at its default, Ask. In the input field, enter Add 100 random points within Sapporo and press Enter to send it. Press Shift + Enter for a new line.

The agent replies and shows the Python code it wants to run in QGIS. Review the code, then click Approve and run at the bottom.

The agent works in several stages: checking the project state, getting the boundary of Sapporo, and generating the points. As you approve each stage, the points appear on the map and the panel explains the result.

Choose an approval mode

The Python code the agent writes runs with the same permissions as QGIS, so it can change or delete files and even send data outside your computer. For this reason, Mapsuke has an approval mode that sets how code is confirmed before it runs. You can switch modes with the drop-down below the input field.

With Auto and Full auto, code can run without confirmation on the AI's own judgment, and that judgment is not always right. Changes are not undone automatically, so stay with Ask until you are comfortable.

In Ask mode, Mapsuke asks for confirmation and you choose Approve and run, Always approve, or Stop. If you choose Always approve, Mapsuke switches to Full auto from then on.

Make a map

The maps and analysis results in this article are examples to show how Mapsuke works.Their accuracy has not been verified, so do not use them for business decisions.

From fetching data to color-coding

Next, use open data to make a map with a simple analysis: aggregate land prices by ward in Sapporo and color each ward by its average price (a choropleth map).

Send Aggregate prices by Sapporo ward from the latest land price survey data, and create a choropleth map based on the average price. The agent downloads the data from National Land Numerical Information, aggregates it by ward, and sets up the coloring. If anything is unclear, it asks you a question along the way.

Adjust the look and finish with a print layout

Once you see the result, continue the chat with Add a legend and a title and create a print layout. If needed, adjust colors and labels the same way. The agent looks at the map canvas and the print layout as images and corrects them as it checks the result.

For how to create a print layout, see the following article.

Check the results

Open Intermediate steps in the panel to see the Python code the agent ran and the Processing tools it used. Judging which processing is appropriate, and whether the result is valid, is up to you. Check the sources and the aggregation method before you use the map.

Conclusion

If you have Claude Code or Codex CLI, you can install Mapsuke and start using it right away. Open a project you work on every day and try typing your everyday tasks into the chat, such as Convert this layer to the Japan Plane Rectangular Coordinate System or Count the features in each municipality and color-code the result. In Ask mode, you can watch which tools the agent chooses, and how it uses them, as you go.

The next article covers more ways to get the most out of Mapsuke, such as handing off work that takes many steps and saving repeated work as a tool.

Mapsuke is developed as open source. Report bugs and request features in the Issues of the GitHub repository.

Data sources

• National Land Numerical Information “Prefectural Land Price Survey Data” and “Administrative Area Data” (Ministry of Land, Infrastructure, Transport and Tourism)
• GSI Elevation Tiles and GSI Tiles, published by the Geospatial Information Authority of Japan (GSI)
• © OpenStreetMap contributors