qgis_mcp

QGISMCP provides a Python-based MCP server that runs inside your environment and exposes a set of QGIS controls to Claude AI via the Model Context Protocol. The server communicates with a QGIS plugin that accepts commands over a socket, enabling Claude to create, load and save projects, manage layers, run Processing Toolbox algorithms, and even execute arbitrary Python (PyQGIS) code within the QGIS session. Tools exposed include operations like ping, get_qgis_info, load_project, create_new_project, 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. This setup enables prompt-driven GIS automation and rapid prototyping of geospatial workflows through Claude’s guidance.

Prerequisites:\n- QGIS 3.x installed (tested with 3.22)\n- Claude Desktop installed\n- Python 3.10 or newer\n- uv (uvx) installed as the MCP runtime helper\n\n1) Install uv (uvx) for your platform:\n - macOS: brew install uv\n - Windows: follow the Windows install script provided by uv (see the uv documentation)\n - Linux: follow the uv installation guide on the official website\n\n2) Clone the MCP repository and locate the server files:\n - git clone git@github.com:jjsantos01/qgis_mcp.git\n - The MCP server script is located at src/qgis_mcp/qgis_mcp_server.py and the QGIS plugin resides in qgis_mcp_plugin/\n\n3) Install the QGIS plugin into your QGIS profile:\n - Copy the folder qgis_mcp_plugin/ into your QGIS profile plugins directory. Example path (Windows): C:\Users\YourUser\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins. On Mac: ~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins.\n\n4) Configure Claude Desktop to connect to the MCP server:\n - In Claude, edit claude_desktop_config.json to include the following (see the repository README for exact syntax):\n\njson\n{\n "mcpServers": {\n "qgis": {\n "command": "uvx",\n "args": [\n "--directory",\n "/ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp",\n "run",\n "qgis_mcp_server.py"\n ]\n }\n }\n}\n\n\n5) Start the MCP server through the configured command (the uvx invocation from step 4):\n - uvx --directory /ABSOLUTE/PATH/TO/PARENT/REPO/FOLDER/qgis_mcp/src/qgis_mcp run qgis_mcp_server.py\n - Ensure QGIS is running and the qgis_mcp_plugin is loaded.\n\n6) Verify connectivity from Claude and begin issuing MCP commands.\n

Environment tips:\n- Ensure the absolute directory path in the uvx command points to the directory containing qgis_mcp_server.py.\n- The QGIS plugin must be loaded and listening on the socket expected by the MCP server.\n- For complex workflows, save intermediate QGIS projects to avoid data loss.\n- When using execute_code, be cautious: arbitrary PyQGIS code runs with the same privileges as the server.\n- If you modify the server, restart the MCP server so Claude reloads the API surface.\nCommon issues:\n- Mismatch between QGIS version and Processing toolbox availability.\n- Firewall or network restrictions blocking the MCP socket.\n- Incorrect path to the plugin folder or missing permissions.\n