Server facts
QGISMCP MCP Server
Project
- Author
- jjsantos01
- Repository
- github.com/jjsantos01/qgis_mcp
- License
- Not specified
- Category
- Maps & Travel
Tech
- Runtime / language
- pythonPython
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 1,125
- Last commit
- Data as of
Tags
- Geospatial
- Gis
- Map Rendering
- Pyqgis
- Qgis
Overview
QGISMCP connects Claude Desktop to a running QGIS application for prompt-assisted GIS work. It has two components: a QGIS plugin that hosts a socket server and a Python MCP server that forwards requests to that plugin. Tools expose project creation, loading, inspection, and saving. Layer operations add vector or raster data, list existing layers, remove selected layers, inspect vector features, and zoom to a layer's extent. Processing algorithms can run with supplied parameters, and the current map view can be rendered to an image file. A separate tool executes arbitrary PyQGIS code for operations outside the more focused interfaces.
Setup requires QGIS 3.x, Python 3.10 or later, uv, and Claude Desktop. The README notes that testing was performed only with QGIS 3.22 rather than asserting compatibility with every release. Users install the plugin by copying its folder into the active QGIS profile, restarting QGIS, and enabling the plugin. The assistant configuration then launches the Python server from an absolute checkout directory. Before using tools, the plugin's server must be started inside QGIS. The example workflow combines project creation, vector and raster loading, centroid processing, thematic styling through code, image rendering, and saving. Because arbitrary code execution is available, the README explicitly urges caution when granting the assistant that capability.
Install & configure
Requirements
- QGIS 3.x; README testing was limited to 3.22
- Python 3.10 or later
- uv
- Claude Desktop
- The enabled QGIS MCP plugin and its running socket server
uv --directory /ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp run qgis_mcp_server.pyReplace the documented absolute-path placeholder with the checkout location. Copy qgis_mcp_plugin into the active profile's plugins directory, restart QGIS, enable it, then use its Start Server action. No required environment variables are stated.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"qgis_mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
"run",
"qgis_mcp_server.py"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"qgis_mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
"run",
"qgis_mcp_server.py"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"qgis_mcp": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
"run",
"qgis_mcp_server.py"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"qgis_mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
"run",
"qgis_mcp_server.py"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"qgis_mcp": {
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",
"run",
"qgis_mcp_server.py"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| ping | Check connectivity with the QGIS plugin server. |
| get_qgis_info | Inspect details of the running QGIS installation. |
| load_project | Open a project from a supplied filesystem path. |
| create_new_project | Create and save a new QGIS project. |
| get_project_info | Inspect information about the active project. |
| add_vector_layer | Load vector data as a project layer. |
| add_raster_layer | Load raster data as a project layer. |
| get_layers | Enumerate layers in the active project. |
| remove_layer | Remove a layer using its identifier. |
| zoom_to_layer | Set the map view to a layer's extent. |
| get_layer_features | Read vector-layer features with an optional result limit. |
| execute_processing | Run a Processing Toolbox algorithm using supplied parameters. |
| save_project | Save the active project at a requested path. |
| render_map | Export the current map view as an image file. |
| execute_code | Run arbitrary PyQGIS source supplied as a string. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Create and save GIS projects through Claude.
- Load vector and raster layers and inspect their contents.
- Run Processing Toolbox algorithms with selected parameters.
- Render map images after assisted styling or analysis.
Strengths
- Connects project, layer, processing, and rendering operations.
- Offers focused tools as well as direct PyQGIS execution.
- Works with a live QGIS application through a dedicated plugin.
Limitations
- Requires manual plugin installation and starting its server in QGIS.
- The README reports testing only on QGIS 3.22.
- Arbitrary Python execution carries an explicit caution in the README.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
