QGIS MCP

Connect QGIS to Claude AI through the Model Context Protocol (MCP), enabling Claude to directly control QGIS — manage layers, edit features, run processing algorithms, render maps, and more.

51 MCP tools covering layer management, feature editing, processing, rendering, styling, plugin development, and system management. Compatible with QGIS 3.28–4.x. Works with Claude Code, Codex CLI, Gemini CLI, opencode, Claude Desktop, Cursor, VS Code, Windsurf, Zed, and more.

Architecture

Claude ←→ MCP Server (FastMCP) ←→ TCP socket ←→ QGIS Plugin (QTimer) ←→ PyQGIS API

1. QGIS Plugin (qgis_mcp_plugin/) — Runs inside QGIS. Non-blocking TCP socket server that processes JSON commands within QGIS's event loop.

2. MCP Server (src/qgis_mcp/server.py) — Runs outside QGIS. Exposes QGIS operations as MCP tools via FastMCP.

Installation

No clone needed. Requires QGIS 3.28+ and uv.

1. Install the QGIS plugin

In QGIS: Plugins > Manage and Install Plugins > search QGIS MCP > Install.

Restart QGIS and click Start Server in the QGIS MCP dock widget.

2. Connect your coding agent

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

Scope reference:

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

Or edit ~/.codex/config.toml directly:

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

Add to ~/.gemini/settings.json:

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

Add to opencode.json at your project root:

{
  "mcp": {
    "qgis": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/nkarasiak/qgis-mcp", "qgis-mcp-server"],
      "enabled": true
    }
  }
}

Add to your client's MCP config file:

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

Usage

1. Start the plugin — In QGIS, click the MCP toolbar button (or Plugins > QGIS MCP) and click "Start Server"

2. Talk to Claude — The MCP tools will appear automatically. Ask Claude to work with your QGIS project.

Example prompt

You have access to QGIS tools. Do the following:
1. Ping to check the connection
2. Create a new project and save it at "/tmp/my_project.qgz"
3. Load the vector layer "world_map.gpkg" available in Qgis ("resources/data/world_map.gpkg")
4. Filter "USA" from the field "adm0_a3"
6. Render the map and show me the result
7. Save the project

Tools (51)

All tools are async with human-readable titles and annotations (readOnly, destructive, idempotent). Destructive tools ask for confirmation via MCP elicitation when supported; clients without elicitation proceed normally (fail-open) since tools are already gated by ToolAnnotations. Long-running tools report progress via MCP logging.

Compound tool mode

Set QGIS_MCP_TOOL_MODE=compound to reduce the 51 granular tools to ~19 grouped tools, cutting schema overhead per LLM turn. Each compound tool takes an action parameter:

QGIS_MCP_TOOL_MODE=compound uv run --no-sync src/qgis_mcp/server.py

Groups: system, project, layer, features, selection, style, canvas, render, processing, code, batch, layer_tree, plugins, variables, settings, expression, transform, message_log, layer_property.

Configuration

Contributing

git clone https://github.com/nkarasiak/qgis-mcp.git
cd qgis-mcp
python install.py   # symlinks plugin + configures your MCP client

install.py options: --clients claude-desktop,cursor, --remote (uvx instead of uv run), --profile myprofile, --uninstall.

# Unit tests (no QGIS needed — mocked socket)
uv run --no-sync pytest tests/test_mcp_tools.py -v

# Integration tests (requires QGIS plugin running)
uv run --no-sync pytest tests/test_qgis_live.py -v

License

This project is licensed under the GNU GPL v2 or later.