QGIS MCP Server

How to use

You connect an MCP client (Claude) to the QGIS MCP server, then issue high‑level actions that are translated into QGIS operations. Use the available tools to ping the server, inspect the QGIS installation, manage projects and layers, run processing algorithms, render maps, and execute PyQGIS code. Start with a simple test to confirm connectivity, then perform common tasks like creating a new project, loading layers, and saving your work.

How to install

Prerequisites you must have before installing and running the MCP server.

QGIS 3.X (tested with 3.22) installed on your system.

Claude Desktop installed on your machine.

Python 3.10 or newer.

UV package manager installed and available in your terminal or PowerShell.

If you're on Mac, install UV with the following command.

brew install uv

If you're on Windows using PowerShell, install UV with this command.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

For other platforms, follow the UV installation guidance from its website. Do not proceed until UV is installed.

Clone the MCP project repository to your machine.

git clone [email protected]:jjsantos01/qgis_mcp.git

Install and configure the QGIS MCP plugin by placing its folder in your QGIS profile plugins directory. Find your active profile folder in QGIS under Settings → User profiles → Open active profile folder, then copy the folder qgis_mcp_plugin into Python/plugins. The typical paths are shown here.

# Windows
C:\Users\USER\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins

# Mac
~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins

Reload QGIS, then enable the QGIS MCP plugin from Plugins → Installing and Managing Plugins, ensuring it is activated.

Configure Claude Desktop to connect to the MCP server by editing claude_desktop_config.json with the MCP entry that starts the local UV-based server. The example below starts the server inside the qgis_mcp source tree using UV to run a Python script.

{
  "mcpServers": {
    "qgis": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
        "run",
        "qgis_mcp_server.py"
      ]
    }

  }
}

Additional setup notes

The MCP server provides two-way communication via a socket with the Claude client, enabling project and layer management, processing execution, and code evaluation inside QGIS. Exercise caution when enabling execute_code, as running arbitrary PyQGIS code can affect your project and data.

Usage examples and capabilities

You can perform the following actions through the Claude MCP interface: ping, get_qgis_info, load_project, create_new_project, get_project_info, add_vector_layer, add_raster_layer, get_layers, remove_layer, zoom_to_layer, get_layer_features, execute_processing, save_project, render_map, and execute_code. These tools map to corresponding QGIS operations such as manipulating projects, adding/removing layers, running Processing Toolbox algorithms, rendering maps, and executing PyQGIS code.

Tools and endpoints

- ping — Check server connectivity.

- get_qgis_info — Retrieve information about the QGIS installation.

- load_project — Load a GIS project from a specified path.

- create_new_project — Create a new project and save it.

- get_project_info — Get details about the current project.

- add_vector_layer — Add a vector layer to the current project.

- add_raster_layer — Add a raster layer to the current project.

- get_layers — List all layers in the active project.

- remove_layer — Remove a layer by its ID.

- zoom_to_layer — Zoom the map view to a specific layer’s extent.

- get_layer_features — Retrieve features from a vector layer with an optional limit.

- execute_processing — Run a Processing Toolbox algorithm with given parameters.

- save_project — Save the current project to a path.

- render_map — Render the current map view to an image file.

- execute_code — Run arbitrary PyQGIS code provided as a string.

Security and cautions

Only run code you trust and validate the impact of each operation before executing it in a live project. Keep backups of important projects and data.

ping

Check server connectivity to ensure the MCP link is active.

get_qgis_info

Retrieve information about the currently installed QGIS environment and version.

load_project

Load a QGIS project from a specified filesystem path.

create_new_project

Create a new QGIS project and save it to a path.

get_project_info

Return details about the currently loaded project.

add_vector_layer

Add a vector layer to the active project from a file path.

add_raster_layer

Add a raster layer to the active project from a file path.

get_layers

List all layers present in the current project.

remove_layer

Remove a layer from the project by its ID.

zoom_to_layer

Adjust the map view to the extent of the specified layer.

get_layer_features

Fetch features from a vector layer with an optional limit.

execute_processing

Run a Processing Toolbox algorithm with provided parameters.

save_project

Save the current project to a target path.

render_map

Render the current map view to an image file.

execute_code

Execute arbitrary PyQGIS code provided as a string.