WAI QGIS MCP

WAI QGIS MCP lets a trusted AI assistant work directly in QGIS. Use it to inspect projects and layers, load data, run Processing algorithms, style maps, render images, and automate PyQGIS tasks by describing what you want.

It connects an MCP-compatible assistant such as Codex or Claude to the QGIS desktop application. The assistant can execute arbitrary PyQGIS code, so only connect assistants you trust.

Install

You need to install the QGIS plugin and connect your AI assistant.

1. Install the QGIS plugin

The plugin supports QGIS 3.28 and later and is available in the QGIS plugin repository.

1. In QGIS, choose Plugins → Manage and Install Plugins.
2. In Settings, enable Show also Experimental Plugins.
3. In All, search for WAI QGIS MCP, select it, and click Install Experimental Plugin.
4. Choose Plugins → WAI QGIS MCP → WAI QGIS MCP.
5. Click Start Server. Optionally enable Start server automatically when QGIS opens.

Alternatively, install the release ZIP directly:

1. Open the latest GitHub release and download qgis-mcp-plugin-<version>.zip. Do not extract it or download GitHub's similarly named Source code (zip) archive.
2. In QGIS, choose Plugins → Manage and Install Plugins → Install from ZIP.
3. Select the downloaded ZIP and click Install Plugin. QGIS warns that installing a plugin from an untrusted source can harm your computer; choose Yes to continue.
4. Open the plugin panel and start the server as above.

2. Connect your AI assistant

Choose one setup method for your assistant. Keep QGIS running on the same computer as the assistant.

| Assistant | Setup | Separate Node.js installation | | --- | --- | --- | | Claude Desktop | Install the .mcpb extension | No; Claude Desktop supplies Node.js | | Claude Code | Install the marketplace plugin or use the CLI command below | Yes, Node.js 18+ | | Codex / ChatGPT desktop app | Add an MCP server in Settings or use the Codex CLI | Yes, Node.js 18+ |

For methods that require Node.js, install it with npm and confirm that node --version and npx --version work in a terminal. You do not need to clone this repository or install qgis-mcp globally.

Claude Desktop

Download qgis-mcp-<version>.mcpb from the latest release, then double-click it. You can also install it from Settings → Extensions → Advanced settings → Install Extension….

Claude Desktop shows a warning that the extension is not verified by Anthropic and will have access to your computer, then asks you to confirm a second time. Accept both, then make sure the extension's toggle reads Enabled. The bundle includes the server and its dependencies; Claude Desktop supplies the Node.js runtime.

Leave the extension's QGIS port setting blank unless you need to override it. Blank means the port is detected from the running plugin.

Claude Code

With Node.js installed, run these commands inside Claude Code:

/plugin marketplace add wiseman/qgis_mcp
/plugin install qgis-mcp@qgis-mcp
/reload-plugins

Alternatively, with the Claude Code CLI installed, run this in a terminal:

claude mcp add --transport stdio --scope user qgis -- npx -y qgis-mcp@latest

Restart Claude Code after using the CLI method. Run /mcp to check the connection. Both methods launch the same server; choose one to avoid duplicate connections. If a server named qgis already exists, claude mcp add refuses to replace it, so remove it first with claude mcp remove qgis -s user. See Claude Code's MCP documentation.

Codex / ChatGPT desktop app

With Node.js installed, open the desktop app's settings and go to Settings → Plugins → MCPs → Add → Add MCP server, then enter:

| Field | Value | | --- | --- | | Name | qgis | | Type | STDIO | | Command to launch | npx | | Arguments | -y, qgis-mcp@latest (added one at a time with Add argument) |

Select Save. The server is usable immediately; you do not need to restart the app. Older versions of the app put this screen under Settings → MCP servers instead.

In the ChatGPT desktop app, use Work mode. Local MCP servers are not available in Chat mode, where the assistant will tell you the server is not exposed and offer to continue in Work mode. Select the Work tab before asking it to do anything in QGIS.

Alternatively, if you have the Codex CLI installed, run this in a terminal:

codex mcp add qgis -- npx -y qgis-mcp@latest

Note that codex mcp add overwrites an existing server of the same name without warning. The desktop app, Codex CLI, and IDE extension share MCP configuration on the same host, so configure it only once. Run /mcp to check the connection.

These instructions are for local desktop/CLI sessions. ChatGPT web does not read this local configuration.

Other local MCP assistants

Add a STDIO server with command npx and arguments -y, qgis-mcp@latest. This also requires Node.js 18+ with npm. The QGIS panel's port (9876 by default) is used by the bridge; it is not an HTTP MCP URL.

On Windows, some clients cannot launch npx directly. If the server fails to start, use npx.cmd, or set the command to cmd with arguments /c, npx, -y, qgis-mcp@latest. Windows support is untested.

3. Keeping it up to date

The QGIS plugin and the MCP server are installed separately and can be updated independently. They interoperate as long as the wire protocol matches, and the assistant shows a note when their versions differ.

• QGIS plugin: Plugins → Manage and Install Plugins → Upgradeable, or install a newer release ZIP over the old one.
• Claude Code, Codex, other npx setups: nothing to do. The @latest specifier fetches the current server each time the assistant starts it.
• Claude Desktop: download the new .mcpb from the latest release and open it again. The bundle is version-pinned, so it does not update itself.

4. Removing or switching methods

If you configured more than one method and want to undo one:

claude mcp remove qgis -s user          # Claude Code, CLI method
codex mcp remove qgis                   # Codex CLI and ChatGPT desktop app

Inside Claude Code, remove the marketplace plugin with /plugin uninstall qgis-mcp@qgis-mcp. In Claude Desktop, open the extension and select Uninstall. In QGIS, remove the plugin with Plugins → Manage and Install Plugins → Installed → Uninstall Plugin.

Use it

Open QGIS and your AI assistant, then ask the assistant to inspect the current QGIS project. For example:

Inspect my current QGIS project and summarize its layers, coordinate reference systems, and visible extent.

You can then ask it to load data, style a layer, run a Processing algorithm, save the project, or render the map. Be specific about layer names, fields, output paths, and whether changes should be saved.

If it does not connect

• Confirm that the WAI QGIS MCP panel says the server is running.
• Confirm that QGIS and the AI assistant are running on the same computer.
• Restart the AI assistant after installing or configuring the connection.
• In the ChatGPT desktop app, use Work mode. Chat mode cannot see local MCP servers, so the setup looks broken when it is not.
• If the assistant lists the server as connected but the first request fails, the assistant reached this bridge but the bridge could not reach QGIS. Check that the panel says the server is running.
• If the assistant cannot find npx, confirm Node.js and npm are installed, then restart the assistant so it picks up the updated PATH. If needed, use the full path to npx in the server configuration.
• The port is detected automatically from the running plugin, so changing it in QGIS normally needs no client change. Set QGIS_MCP_PORT only to override that, or when running more than one QGIS instance at once.
• Click Assistant setup help… in the plugin panel for the setup command for each assistant.
• Enable Log diagnostics to the QGIS Message Log in the plugin panel for connection and error details.

If the assistant reports that the plugin and server versions differ, that is a note rather than an error and the session still works. Update both when convenient, using the upgrade steps above.

WAI QGIS MCP is a fork of jjsantos01/qgis_mcp.