Skip to content
Back to search

qgis-mcp

Connect QGIS to AI agent through the Model Context Protocol (MCP)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nkarasiak/qgis-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nkarasiak/qgis-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nkarasiak--qgis-mcp/badge.svg)](/listings/nkarasiak--qgis-mcp)

HTML

<a href="/listings/nkarasiak--qgis-mcp"><img src="/api/listings/nkarasiak--qgis-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

No clone needed. Requires QGIS 3.28+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).

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

<details> <summary>Claude Code</summary>

claude mcp add -s user qgis -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server

Scope reference:

| Flag | Stored in | Visible to | |------|-----------|-----------| | `-s local` (default) | `.mcp.json` (gitignored) | You, this project | | `-s project` | `.mcp.json` (committed) | Whole team, this project | | `-s user` | `~/.claude.json` | You, every project |

</details>

<details> <summary>Codex CLI</summary>

codex mcp add qgis -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server

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

[mcp_servers.qgis]
command = "uvx"
args = ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]

</details>

<details> <summary>Gemini CLI</summary>

Add to `~/.gemini/settings.json`:

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
    }
  }
}

</details>

<details> <summary>Qwen Code</summary>

Same layout as Gemini CLI. Add to `~/.qwen/settings.json`:

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
    }
  }
}

</details>

<details> <summary>Kimi Code CLI</summary>

Add to `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.json`). A `.kimi-code/mcp.json` in the working directory overrides it for that project.

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
    }
  }
}

Kimi has no `mcp add` subcommand - edit the JSON or use the `/mcp-config` TUI.

</details>

<details> <summary>GitHub Copilot CLI</summary>

Add to `~/.copilot/mcp-config.json` (directory overridable via `$COPILOT_HOME`):

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
    }
  }
}

</details>

<details> <summary>LM Studio</summary>

Add to `~/.lmstudio/mcp.json` (`%USERPROFILE%\.lmstudio\mcp.json` on Windows):

{
  "mcpServers": {
    "qgis": {
      "command": "uvx",
      "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
    }
  }
}

</details>

<details> <summary>opencode</summary>

Add to `opencode.json` at your project root:

{
  "mcp": {
    "qgis": {
      "type": "local",
      "command": ["uvx", "--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"],
      "enabled": true
    }
  }
}

</details>

<details> <summary>Hermes desktop app (Windows)</summary>

Hermes stores MCP servers in `config.yaml` under an `mcpServers` block. A standalone `mcp.json` is **ignored**. You also need a small `.bat` launcher - running `uvx` directly inside Hermes causes a venv conflict (`ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'`).

**Step 1 - Create `%APPDATA%\Hermes\qgis-mcp-launch.bat`:**

@echo off
REM Clears Hermes's venv vars so uvx uses a clean Python environment.
set VIRTUAL_ENV=
set PYTHONPATH=
set PYTHONHOME=
uvx --from "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip" qgis-mcp-server

**Step 2 - Add to `%APPDATA%\Hermes\config.yaml`:**

mcpServers:
  qgis:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 449 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # QGIS MCP
  2. Connect [QGIS](https://qgis.org/) to any AI agent that speaks the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), so the agent drives QGIS directly: manage layers, edit features, run processing algorithms, render maps, and more.
  3. 125 MCP tools covering layer management, feature editing, processing, rendering, styling, layout & atlas authoring, cross-layer SQL, plugin development, and system management. Compatible with QGIS 3.28–4.x. Model and client agnostic: any MCP client works, among them Claude Code, Codex CLI, Gemini CLI, Qwen Code, Kimi Code CLI, GitHub Copilot CLI, opencode, LM Studio, Claude Desktop, Cursor, VS Code, Windsurf, Zed, and more.
  4. ## Architecture
  5. ```
  6. AI agent ←→ MCP Server (FastMCP) ←→ TCP socket ←→ QGIS Plugin (QTimer) ←→ PyQGIS API
  7. ```
  8. 1. **QGIS Plugin** (`qgis_mcp_plugin/`) - Runs inside QGIS. Non-blocking TCP socket server that processes JSON commands within QGIS's event loop.
  9. 2. **MCP Server** (`src/qgis_mcp/server.py`) - Runs outside QGIS. Exposes QGIS operations as MCP tools via [FastMCP](https://gofastmcp.com/).
  10. ## Installation
  11. No clone needed. Requires QGIS 3.28+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
  12. ### 1. Install the QGIS plugin
  13. In QGIS: `Plugins` > `Manage and Install Plugins` > search **QGIS MCP** > Install.
  14. Restart QGIS and click **Start Server** in the QGIS MCP dock widget.
  15. ### 2. Connect your coding agent
  16. <details>
  17. <summary>Claude Code</summary>
  18. ```bash
  19. claude mcp add -s user qgis -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server
  20. ```
  21. Scope reference:
  22. | Flag | Stored in | Visible to |
  23. |------|-----------|-----------|
  24. | `-s local` (default) | `.mcp.json` (gitignored) | You, this project |
  25. | `-s project` | `.mcp.json` (committed) | Whole team, this project |
  26. | `-s user` | `~/.claude.json` | You, every project |
  27. </details>
  28. <details>
  29. <summary>Codex CLI</summary>
  30. ```bash
  31. codex mcp add qgis -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server
  32. ```
  33. Or edit `~/.codex/config.toml` directly:
  34. ```toml
  35. [mcp_servers.qgis]
  36. command = "uvx"
  37. args = ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
  38. ```
  39. </details>
  40. <details>
  41. <summary>Gemini CLI</summary>
  42. Add to `~/.gemini/settings.json`:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "qgis": {
  47. "command": "uvx",
  48. "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
  49. }
  50. }
  51. }
  52. ```
  53. </details>
  54. <details>
  55. <summary>Qwen Code</summary>
  56. Same layout as Gemini CLI. Add to `~/.qwen/settings.json`:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "qgis": {
  61. "command": "uvx",
  62. "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
  63. }
  64. }
  65. }
  66. ```
  67. </details>
  68. <details>
  69. <summary>Kimi Code CLI</summary>
  70. Add to `~/.kimi-code/mcp.json` (or `$KIMI_CODE_HOME/mcp.json`). A `.kimi-code/mcp.json`
  71. in the working directory overrides it for that project.
  72. ```json
  73. {
  74. "mcpServers": {
  75. "qgis": {
  76. "command": "uvx",
  77. "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
  78. }
  79. }
  80. }
  81. ```
  82. Kimi has no `mcp add` subcommand - edit the JSON or use the `/mcp-config` TUI.
  83. </details>
  84. <details>
  85. <summary>GitHub Copilot CLI</summary>
  86. Add to `~/.copilot/mcp-config.json` (directory overridable via `$COPILOT_HOME`):
  87. ```json
  88. {
  89. "mcpServers": {
  90. "qgis": {
  91. "command": "uvx",
  92. "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
  93. }
  94. }
  95. }
  96. ```
  97. </details>
  98. <details>
  99. <summary>LM Studio</summary>
  100. Add to `~/.lmstudio/mcp.json` (`%USERPROFILE%\.lmstudio\mcp.json` on Windows):
  101. ```json
  102. {
  103. "mcpServers": {
  104. "qgis": {
  105. "command": "uvx",
  106. "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"]
  107. }
  108. }
  109. }
  110. ```
  111. </details>
  112. <details>
  113. <summary>opencode</summary>
  114. Add to `opencode.json` at your project root:
  115. ```json
  116. {
  117. "mcp": {
  118. "qgis": {
  119. "type": "local",
  120. "command": ["uvx", "--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"],
  121. "enabled": true
  122. }
  123. }
  124. }
  125. ```
  126. </details>
  127. <details>
  128. <summary>Hermes desktop app (Windows)</summary>
  129. Hermes stores MCP servers in `config.yaml` under an `mcpServers` block. A standalone `mcp.json` is **ignored**. You also need a small `.bat` launcher - running `uvx` directly inside Hermes causes a venv conflict (`ModuleNotFoundError: No module named 'pydantic_core._pydantic_core'`).
  130. **Step 1 - Create `%APPDATA%\Hermes\qgis-mcp-launch.bat`:**
  131. ```batch
  132. @echo off
  133. REM Clears Hermes's venv vars so uvx uses a clean Python environment.
  134. set VIRTUAL_ENV=
  135. set PYTHONPATH=
  136. set PYTHONHOME=
  137. uvx --from "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip" qgis-mcp-server
  138. ```
  139. **Step 2 - Add to `%APPDATA%\Hermes\config.yaml`:**
  140. ```yaml
  141. mcpServers:
  142. qgis:
  143. command: "C:\\Users\\<you>\\AppData\\Roaming\\Hermes\\qgis-mcp-launch.bat"
  144. args: []
  145. ```
  146. Replace `<you>` with your Windows username. Restart Hermes, then verify with:
  147. ```
  148. Call the QGIS ping tool.
  149. ```
  150. > **Tip:** The QGIS plugin's **Setup & Configurator** dialog has a **hermes** entry in the
  151. > client dropdown. Select it and click **Copy** to get the bat file and YAML pre-filled
  152. > with your local paths.
  153. For the full guide see [`docs/agent-integration.md`](docs/agent-integration.md).
  154. </details>
  155. <details>
  156. <summary>Nous / Hermes-style agents and other MCP-compatible clients (opencode, …)</summary>
  157. **opencode** (which runs Nous/Hermes and other models) is supported directly by the installer:
  158. ```bash
  159. python install.py --non-interactive --clients opencode
  160. ```
  161. This writes the correct config block to `~/.config/opencode/config.json`
  162. (`%APPDATA%\opencode\config.json` on Windows).
  163. To configure manually, add to your `opencode.json` or global opencode config:
  164. ```json
  165. {
  166. "$schema": "https://opencode.ai/config.json",
  167. "mcp": {
  168. "qgis": {
  169. "type": "local",
  170. "command": [
  171. "uvx",
  172. "--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip",
  173. "qgis-mcp-server"
  174. ]
  175. }
  176. }
  177. }
  178. ```
  179. Any other agent or client that supports the MCP stdio transport can also use this server.
  180. Generic config (exact key names vary by client - see your agent's docs):
  181. ```json
  182. {
  183. "mcpServers": {
  184. "qgis": {
  185. "command": "uvx",
  186. "args": [
  187. "--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip",
  188. "qgis-mcp-server"
  189. ]
  190. }
  191. }
  192. }
  193. ```
  194. After starting the agent, verify by asking it to call the `ping` tool - it
  195. should return `{"pong": true}` when the QGIS plugin is running.
  196. For a full setup guide, troubleshooting steps, and compound-tool mode configuration see
  197. [`docs/agent-integration.md`](docs/agent-integration.md).
  198. </details>
  199. <details>
  200. <summary>Claude Desktop, Cursor, VS Code, Windsurf, and others</summary>
  201. Add to your client's MCP config file:
  202. ```json
  203. {
  204. "mcpServers": {
  205. "qgis": {
  206. "command": "uvx",
  207. "args": [
  208. "--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip",
  209. "qgis-mcp-server"
  210. ]
  211. }
  212. }
  213. }
  214. ```
  215. </details>
  216. ## Usage
  217. 1. **Start the plugin** - In QGIS, click the MCP toolbar button (or `Plugins` > `QGIS MCP`) and click "Start Server"
  218. 2. **Talk to your agent** - The MCP tools appear automatically. Ask the agent to work with your QGIS project.
  219. ### Example prompt
  220. ```
  221. You have access to QGIS tools. Do the following:
  222. 1. Ping to check the connection
  223. 2. Create a new project and save it at "/tmp/my_project.qgz"
  224. 3. Load the vector layer "world_map.gpkg" available in Qgis ("resources/data/world_map.gpkg")
  225. 4. Filter "USA" from the field "adm0_a3"
  226. 6. Render the map and show me the result
  227. 7. Save the project
  228. ```
  229. ## Updating
  230. The plugin (inside QGIS) and the MCP server (outside QGIS) must stay in sync - a newer server sending a command the older plugin doesn't know will return an error. Run `diagnose` after any update to verify both sides match.
  231. | Component | Remote install | Local install (`git clone`) |
  232. |-----------|---------------|----------------------------|
  233. | **QGIS plugin** | `Plugins` > `Manage and Install Plugins` > Update | Same - Plugin Manager picks up the new version from QGIS Hub |
  234. | **MCP server** | uvx caches the downloaded archive - force an update with `uvx --refresh-package qgis-mcp --from https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip qgis-mcp-server`, then restart your MCP client | `git pull` then restart the MCP server process |
  235. To auto-update instead, add `--refresh-package qgis-mcp` before `--from` in the configs above: uvx then re-resolves this package from GitHub on every launch. **Warning:** this requires network at launch - the MCP server fails to start when offline - and adds ~1–3s to startup. The plain configs above use the cached version and work offline.
  236. After updating the plugin, click **Stop / Start** in the QGIS MCP dock widget (or reload via `Plugins` > `QGIS MCP` > `Reload Plugin`) to load the new code without restarting QGIS.
  237. ## Tools (125)
  238. | Category | Tools |
  239. |----------|-------|
  240. | **Project** | `load_project`, `create_new_project`, `save_project`, `get_project_info`, `set_project_crs` |
  241. | **Layers** | `get_layers`, `add_vector_layer`, `add_raster_layer`, `add_web_layer`, `remove_layer`, `find_layer`, `create_memory_layer`, `set_layer_visibility`, `zoom_to_layer`, `get_layer_extent`, `set_layer_property`, `get_layer_crs`, `set_layer_crs`, `get_active_layer`, `set_active_layer`, `add_table_join`, `export_layer` |
  242. | **Features** | `get_layer_features`, `add_features`, `update_features`, `update_feature_geometry`, `delete_features`, `select_features`, `get_selection`, `clear_selection`, `get_field_statistics`, `get_unique_values` |
  243. | **Fields** | `add_field`, `delete_field`, `rename_field`, `field_calculator` |
  244. | **Editing** | `start_editing`, `commit_edits`, `rollback_edits`, `get_edit_status`, `undo_edits`, `redo_edits` |
  245. | **Styling** | `set_layer_style` (single, categorized, graduated), `set_raster_style` (pseudocolor, gray, RGB, hillshade), `apply_style_qml`, `save_style_qml`, `get_layer_labeling`, `set_layer_labeling` |
  246. | **Connections** | `list_connections`, `create_postgresql_connection`, `list_connection_tables`, `add_layer_from_connection`, `import_layer_to_connection`, `execute_connection_sql` |
  247. | **Rendering** | `render_map`, `get_canvas_screenshot`, `get_3d_screenshot`, `get_canvas_extent`, `set_canvas_extent`, `get_canvas_scale`, `set_canvas_scale` |
  248. | **Bookmarks & themes** | `add_bookmark`, `get_bookmarks`, `remove_bookmark`, `add_map_theme`, `get_map_themes`, `apply_map_theme`, `remove_map_theme` |
  249. | **Processing** | `execute_processing`, `execute_processing_batch`, `list_processing_algorithms`, `get_algorithm_help`, `get_processing_providers`, `create_processing_model`, `list_processing_models`, `run_model`, `start_processing_job`, `get_processing_job`, `cancel_processing_job` |
  250. | **Session** | `create_checkpoint`, `list_checkpoints`, `restore_checkpoint`, `export_session` |
  251. | **Analysis** | `raster_calculator`, `zonal_statistics`, `sample_raster_values`, `spatial_join` |
  252. | **Layouts** | `list_layouts`, `export_layout`, `create_layout`, `add_layout_map`, `add_layout_label`, `add_layout_legend`, `add_layout_scalebar`, `add_layout_picture`, `add_layout_table`, `get_layout_info`, `remove_layout` |
  253. | **Atlas** | `configure_atlas`, `export_atlas` |
  254. | **Query** | `execute_sql`, `evaluate_expression`, `identify_features` |
  255. | **Layer tree** | `get_layer_tree`, `create_layer_group`, `move_layer_to_group`, `duplicate_layer`, `set_layer_order` |
  256. | **Plugins** | `list_plugins`, `get_plugin_info`, `reload_plugin` |
  257. | **System** | `ping`, `diagnose`, `list_qgis_instances`, `get_qgis_info`, `get_raster_info`, `get_message_log`, `execute_code`, `batch_commands`, `validate_expression`, `get_project_variables`, `set_project_variable`, `get_setting`, `set_setting`, `transform_coordinates` |
  258. All tools are async with human-readable titles and annotations (`readOnly`, `destructive`, `idempotent`). Destructive tools rely on your client's own confirmation gate, which reads the `destructive` annotation; set `QGIS_MCP_AUTO_CONFIRM=0` to have the server elicit a second confirmation as well. Long-running tools report progress via MCP logging.
  259. ### Compound tool mode
  260. Set `QGIS_MCP_TOOL_MODE=compound` to reduce the granular tools to 27 grouped tools (every granular command stays reachable), cutting schema overhead per LLM turn. Each compound tool takes an `action` parameter plus a `params` object holding that action's parameters:
  261. ```bash
  262. QGIS_MCP_TOOL_MODE=compound uv run --no-sync src/qgis_mcp/server.py
  263. ```
  264. ```json
  265. { "action": "load", "params": { "path": "/data/city.qgz" } }
  266. ```
  267. Omit `params` for actions that take none (`{"action": "ping"}`).
  268. Groups: `system`, `project`, `layer`, `features`, `selection`, `style`, `canvas`, `render`, `processing`, `code`, `batch`, `layer_tree`, `plugins`, `variables`, `settings`, `expression`, `query`, `transform`, `message_log`, `layer_property`, `field`, `analysis`, `bookmarks`, `map_themes`, `active_layer`.
  269. ## Configuration
  270. | Environment variable | Default | Description |
  271. |---------------------|---------|-------------|
  272. | `QGIS_MCP_HOST` | `localhost` | Host for socket connection |
  273. | `QGIS_MCP_PORT` | `9876` | Port for socket connection. The QGIS plugin reads it too: set in the environment QGIS is launched from, it overrides the port saved in the plugin's dropdown for that window. |
  274. | `QGIS_MCP_INSTANCES` | _(unset)_ | Address several running QGIS windows from one server. See [Multiple QGIS instances](#multiple-qgis-instances). |
  275. | `QGIS_MCP_TOKEN` | _(unset)_ | Optional shared secret. When set, the plugin rejects any command without a matching token. See [Authentication](#authentication). |
  276. | `QGIS_MCP_TRANSPORT` | `stdio` | MCP transport: `stdio` or `streamable-http` |
  277. | `QGIS_MCP_LOG_FILE` | `~/.local/share/qgis-mcp/server.log` | Log file path (empty to disable) |
  278. | `QGIS_MCP_LOG_LEVEL` | `INFO` | File log level |
  279. | `QGIS_MCP_TOOL_MODE` | `granular` | `granular` (125 tools) or `compound` (27 grouped) |
  280. | `QGIS_MCP_AUTO_CONFIRM` | on | Confirmation elicitation on destructive tools (`execute_code`, `remove_layer`, `delete_features`, ...) is skipped by default: your client already asks before running them, so it was a second prompt for the same call. Set to `0`/`false`/`no`/`off` to elicit anyway - worth it only for a client that runs tools unattended. |
  281. ### Authentication
  282. By default the socket has **no authentication** - it binds to `localhost` only, but any process on the machine that can reach the port can drive QGIS (including `execute_code`, which runs arbitrary PyQGIS). For shared or multi-user machines, set a shared secret so only callers that know it can connect:
  283. 1. Set `QGIS_MCP_TOKEN` in the **environment QGIS runs in** (so the plugin enforces it), then Stop/Start the server in the dock. The QGIS log shows `Token authentication ENABLED`.
  284. 2. Set the **same** value in the MCP server's environment - add it to the `env` block of your MCP client config:
  285. ```json
  286. {
  287. "mcpServers": {
  288. "qgis": {
  289. "command": "uvx",
  290. "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"],
  291. "env": { "QGIS_MCP_TOKEN": "your-long-random-secret" }
  292. }
  293. }
  294. }
  295. ```
  296. The token is compared in constant time. When `QGIS_MCP_TOKEN` is unset (the default), behaviour is unchanged. This raises the bar against other local users/processes; a process running as the same user can still read the token from your config, so it is not a sandbox.
  297. One exception: binding the plugin to a **non-loopback address** requires a token. Exposing arbitrary PyQGIS execution to the network without authentication is not a state you should be able to reach by accident, so the plugin refuses to start on such an address until `QGIS_MCP_TOKEN` is set (in QGIS and in the MCP server).
  298. ### Multiple QGIS instances
  299. One server registration can drive several running QGIS windows. Start each QGIS with the plugin on its own port, then list them in `QGIS_MCP_INSTANCES` as comma-separated `name=port` or `name=host:port` entries.
  300. Set a window's port in the dropdown next to the MCP toolbar button (the arrow beside the logo) before starting the server. That choice is saved per QGIS profile, so two windows on the same profile would both start on it; launch each with its own `QGIS_MCP_PORT` instead (for example `QGIS_MCP_PORT=9877 qgis`), which overrides the saved port without changing it. The same applies when another program already listens on 9876 (Blender's MCP add-on does by default).
  301. ```json
  302. {
  303. "mcpServers": {
  304. "qgis": {
  305. "command": "uvx",
  306. "args": ["--from", "https://github.com/nkarasiak/qgis-mcp/archive/refs/heads/main.zip", "qgis-mcp-server"],
  307. "env": { "QGIS_MCP_INSTANCES": "default=9876,planning=9877,archive=lab-box:9878" }
  308. }
  309. }
  310. }
  311. ```
  312. - Every tool takes an optional `instance` argument (`get_layers(instance="planning")`). Omitting it targets the entry named `default`, or - when no entry is called `default` - the **first** entry listed, so `planning=9877,archive=9878` works without renaming anything.
  313. - `list_qgis_instances` returns the configured names with their host, port, and current reachability. An unknown name is rejected with the list of valid names.
  314. - Instance names match `[A-Za-z0-9_-]+`; entries without a host use `QGIS_MCP_HOST` (default `localhost`).
  315. - Each instance has its own pooled connection and its own lock, so two QGIS windows can be driven concurrently.
  316. - **Not supported with `QGIS_MCP_TOOL_MODE=compound`.** Compound tools carry no `instance` argument, so every call would silently hit one instance; configuring more than one instance in compound mode refuses to start rather than routing writes to the wrong QGIS.
  317. - When `QGIS_MCP_INSTANCES` is unset, exactly one instance named `default` is defined from `QGIS_MCP_HOST`/`QGIS_MCP_PORT` - existing setups are unaffected.
  318. - `QGIS_MCP_TOKEN` is shared across instances: the same secret must be set in every QGIS.
  319. ## Contributing
  320. ```bash
  321. git clone https://github.com/nkarasiak/qgis-mcp.git
  322. cd qgis-mcp
  323. python install.py # symlinks plugin + configures your MCP client
  324. ```
  325. `install.py` options: `--clients claude-desktop,cursor`, `--remote` (uvx instead of uv run), `--profile myprofile`, `--uninstall`.
  326. Known client names: `claude-desktop`, `cursor`, `vscode`, `windsurf`, `zed`, `claude-code`, `codex`, `opencode`, `hermes`, `kimi`, `gemini`, `qwen`, `copilot-cli`, `lmstudio`.
  327. > **Windows (Microsoft Store / MSIX Claude Desktop):** `install.py` uses `--directory` instead of `cwd` in generated configs. This is required for Store-installed Claude Desktop, which runs MCP servers in an MSIX sandbox that silently drops `cwd`. If you configure manually, use `uv --directory "/path/to/qgis-mcp" run --no-sync src/qgis_mcp/server.py` - this works on both MSIX and standalone installs. You can identify a Store install when the config file is under `%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\` instead of `%APPDATA%\Claude\`.
  328. ```bash
  329. # Unit tests (no QGIS needed - mocked socket)
  330. uv run --no-sync pytest tests/test_mcp_tools.py -v
  331. # Integration tests (requires QGIS plugin running)
  332. uv run --no-sync pytest tests/test_qgis_live.py -v
  333. ```
  334. ## License
  335. This project is dual-licensed. Each component is distributed under its own license:
  336. - **QGIS Plugin** (`qgis_mcp_plugin/`) - [GNU GPL v2 or later](qgis_mcp_plugin/LICENSE)
  337. - **MCP Server** (`src/qgis_mcp/`) - [MIT](src/qgis_mcp/LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.