Skip to main content
Version: 1.1.3

Install the QGIS MCP

The QGIS MCP connects an AI assistant (Claude, ChatGPT via compatible clients, Cursor, etc.) directly to QGIS Desktop. You describe what you want in natural language — "load this GeoPackage and apply the styles", "select the paid on-street parking on Street X", "export an A3 layout" — and the assistant does it in QGIS.

Configurations verified on June 9, 2026 (2026-06-09)

The commands and configuration files below were verified on this date. AI clients evolve quickly: if anything differs, refer to the MCP server repository (links at the bottom of the page).

Why MCP, and why it matters​

QGIS is powerful but dense: hundreds of menus, processing algorithms, and styling options. The MCP turns that complexity into a conversation.

  • Speed: loading a dataset, applying a .qml style, running a process, or building a map takes a single sentence — no digging through menus, no hand-writing PyQGIS.
  • Onboarding: a new user becomes productive immediately — the assistant knows QGIS for you.
  • Repetitive tasks: tedious operations (joins, filters, batch exports) are delegated.
  • Paired with our documentation: combine the MCP with our AI assistant and our llms.txt files — the assistant then knows the schema of your CartograFit data and knows exactly which fields to work with.

In short: the MCP turns QGIS from a tool you drive with a mouse into a tool you drive with your assistant's voice. It is a major time saver for data exploration and preparation.

Prerequisites​

  • QGIS 3.28 or newer (compatible up to the 4.x releases).
  • uv — the Python package manager that provides the uvx command.
  • An MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI…).

Step 1 — Install the QGIS plugin​

The plugin creates a small server inside QGIS (TCP socket, port 9876 by default) that the AI client connects to.

  1. Open QGIS.
  2. Menu Plugins → Manage and Install Plugins.
  3. Search for QGIS MCP, install the plugin, then restart QGIS.
  4. Open the QGIS MCP panel and click Start Server.
Alternative install (source repository)

You can also clone the repository and run the install script, which sets up the plugin and configures your client automatically:

git clone https://github.com/nkarasiak/qgis-mcp.git
cd qgis-mcp
python install.py

Handy options: --clients claude-desktop,cursor, --profile <QGIS profile>, --uninstall.

Step 2 — Connect your AI assistant​

The MCP server is launched through uvx (provided by uv). Pick the procedure that matches your client.

Claude Code​

claude mcp add -s user qgis -- uvx --from git+https://github.com/nkarasiak/qgis-mcp qgis-mcp-server

Claude Desktop · Cursor · VS Code · Windsurf​

Add this block to your client's MCP configuration file:

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/nkarasiak/qgis-mcp",
        "qgis-mcp-server"
      ]
    }
  }
}

Claude Desktop file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Codex CLI​

codex mcp add qgis -- uvx --from git+https://github.com/nkarasiak/qgis-mcp qgis-mcp-server

Gemini CLI​

In ~/.gemini/settings.json:

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nkarasiak/qgis-mcp", "qgis-mcp-server"]
    }
  }
}

Environment variables (optional)​

VariableDefaultRole
QGIS_MCP_PORT9876QGIS socket port
QGIS_MCP_HOSTlocalhostSocket host
QGIS_MCP_TOOL_MODEgranulargranular (detailed toolset) or compound (condensed toolset)

Step 3 — Verify the connection​

  1. QGIS open, plugin Start Server active.
  2. Start (or restart) your AI client — it should list the QGIS tools.
  3. Ask, for example: "Ping QGIS" or "Give me the QGIS installation info".

CartograFit example workflow​

Once connected, a typical use case:

  1. Download a GeoPackage dataset from the platform (see Download your data).
  2. "Load this .gpkg file and apply the embedded styles."
  3. "Select the paid parking areas along Street X."
  4. "Cross the parking layer with my own data and export a print-ready A3 layout."

The assistant chains loading, styling, filtering, and exporting — while you stay in control of the result.

Security

The QGIS MCP can run arbitrary PyQGIS code locally to drive QGIS. Only connect trusted AI clients, and keep the server stopped when you are not using it.

Sources​

✉️Need help connecting QGIS?