QGISMCP - QGIS Model Context Protocol Integration

1# QGISMCP - QGIS Model Context Protocol Integration
2 
3QGISMCP connects [QGIS](https://qgis.org/) to [Claude AI](https://claude.ai/chat) through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro), allowing Claude to directly interact with and control QGIS. This integration enables prompt assisted project creation, layer loading, code execution and more.
4 
5This project is strongly based on the [BlenderMCP](https://github.com/ahujasid/blender-mcp/tree/main) project by [Siddharth Ahuja](https://x.com/sidahuj)
6 
7## Features
8 
9- **Two-way communication**: Connect Claude AI to QGIS through a socket-based server.
10- **Project manipulation**: Create, load and save projects in QGIS.
11- **Layer manipulation**: Add and remove vector or raster layers to a project.
12- **Execute processing**: Execute processing algorithms ([Processing Toolbox](https://docs.qgis.org/3.40/en/docs/user_manual/processing/toolbox.html)).
13- **Code execution**: Run arbitrary Python code in QGIS from Claude. Very powerful, but also be very cautious using this tool.
14 
15## Components
16 
17The system consists of two main components:
18 
191. **[QGIS plugin](/qgis_mcp_plugin/)**: A QGIS plugin that creates a socket server within QGIS to receive and execute commands.
202. **[MCP Server](/src/qgis_mcp/qgis_mcp_server.py)**: A Python server that implements the Model Context Protocol and connects to the QGIS plugin.
21 
22## Installation
23 
24### Prerequisites
25 
26- QGIS 3.X (only tested on 3.22)
27- Claude desktop
28- Python 3.10 or newer
29- uv package manager:
30 
31If you're on Mac, please install uv as
32 
33```bash
34brew install uv
35```
36 
37On Windows Powershell
38 
39```bash
40powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
41```
42 
43Otherwise installation instructions are on their website: [Install uv](https://docs.astral.sh/uv/getting-started/installation/)
44 
45**⚠️ Do not proceed before installing UV**
46 
47### Download code
48 
49Download this repo to your computer. You can clone it with:
50 
51```bash
52git clone git@github.com:jjsantos01/qgis_mcp.git
53```
54 
55### QGIS plugin
56 
57You need to copy the folder [qgis_mcp_plugin](/qgis_mcp_plugin/) and its content on your QGIS profile plugins folder.
58 
59You can get your profile folder in QGIS going to menu `Settings` -> `User profiles` -> `Open active profile folder` Then, go to `Python/plugins` and paste the folder `qgis_mcp_plugin`.
60 
61> On a Windows machine the plugins folder is usually located at: `C:\Users\USER\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins` 
62 
63and on MacOS: `~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins`
64 
65 Then close QGIS and open it again. Go to the menu option `Plugins` > `Installing and Managing Plugins`, select the `All` tab and search for "QGIS MCP", then mark the QGIS MCP checkbox.
66 
67### Claude for Desktop Integration
68 
69Go to `Claude` > `Settings` > `Developer` > `Edit Config` > `claude_desktop_config.json` to include the following:
70 
71> If you can't find the "Developers tab" or the `claude_desktop_config.json` look at this [documentation](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server).
72 
73```json
74{
75    "mcpServers": {
76        "qgis": {
77            "command": "uv",
78            "args": [
79                "--directory",
80                "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
81                "run",
82                "qgis_mcp_server.py"
83            ]
84        }
85 
86    }
87}
88```
89 
90## Usage
91 
92### Starting the Connection
93 
941. In QGIS, go to `plugins` > `QGIS MCP` > `QGIS MCP`
95    ![plugins menu](/assets/imgs/qgis-plugins-menu.png)
962. Click "Start Server"
97    ![start server](/assets/imgs/qgis-mcp-start-server.png)
98 
99### Using with Claude
100 
101Once the config file has been set on Claude, and the server is running on QGIS, you will see a hammer icon with tools for the QGIS MCP.
102 
103![Claude tools](assets/imgs/claude-available-tools.png)
104 
105#### Tools
106 
107- `ping` - Simple ping command to check server connectivity
108- `get_qgis_info` - Get QGIS information about the current installation
109- `load_project` - Load a QGIS project from the specified path
110- `create_new_project` - Create a new project and save it
111- `get_project_info` - Get current project information
112- `add_vector_layer` - Add a vector layer to the project
113- `add_raster_layer` - Add a raster layer to the project
114- `get_layers` - Retrieve all layers in the current project
115- `remove_layer` - Remove a layer from the project by its ID
116- `zoom_to_layer` - Zoom to the extent of a specified layer
117- `get_layer_features` - Retrieve features from a vector layer with an optional limit
118- `execute_processing` - Execute a processing algorithm with the given parameters
119- `save_project` - Save the current project to the given path
120- `render_map` - Render the current map view to an image file
121- `execute_code` - Execute arbitrary PyQGIS code provided as a string
122 
123### Example Commands
124 
125This is the example I used for the [demo](https://x.com/jjsantoso/status/1900293848271667395):
126 
127```plain
128You have access to the tools to work with QGIS. You will do the following:
129	1. Ping to check the connection. If it works, continue with the following steps.
130	2. Create a new project and save it at: "C:/Users/USER/GitHub/qgis_mcp/data/cdmx.qgz"
131	3. Load the vector layer: ""C:/Users/USER/GitHub/qgis_mcp/data/cdmx/mgpc_2019.shp" and name it "Colonias".
132	4. Load the raster layer: "C:/Users/USER/GitHub/qgis_mcp/data/09014.tif" and name it "BJ"
133	5. Zoom to the "BJ" layer.
134	6. Execute the centroid algorithm on the "Colonias" layer. Skip the geometry check. Save the output to "colonias_centroids.geojson".
135	7. Execute code to create a choropleth map using the "POB2010" field in the "Colonias" layer. Use the quantile classification method with 5 classes and the Spectral color ramp.
136	8. Render the map to "C:/Users/USER/GitHub/qgis_mcp/data/cdmx.png"
137	9. Save the project.
138```
139