QGISMCP - Geospatial Model Context Protocol Integration Framework (Enhanced Iteration)

This framework establishes a robust bridge between the QGIS GIS platform and Claude AI through the Model Context Protocol (MCP), empowering Claude to exert direct control and perform complex operations within the QGIS environment. It supports prompt-driven lifecycle management for projects, automated data layer ingestion, remote execution of geoprocessing workflows, and on-demand Python scripting.

The core architecture builds upon the foundation laid by the original (https://github.com/jjsantos01/qgis_mcp), with subsequent enhancements focusing on stability and expanded capability based on encountered operational challenges.

This initiative draws significant structural inspiration from the pioneering work demonstrated in the BlenderMCP project by Siddharth Ahuja.

Core Capabilities

• Bidirectional Communication Channel: Utilizes a resilient socket server mechanism embedded within QGIS to ensure continuous, real-time data exchange with the Claude AI interface.
• Project Lifecycle Management: Capabilities to initiate new QGIS projects, open existing ones, and persist changes reliably.
• Geospatial Asset Handling: Tools for the seamless introduction and removal of both vector and raster data layers into the active project workspace.
• Processing Workflow Invocation: Ability to trigger any algorithm available within the standard QGIS Processing Toolbox.
• Arbitrary Code Execution: Secure mechanism to inject and execute custom Python (PyQGIS) instructions directly within the QGIS environment. Caution is paramount when leveraging this highly flexible feature.

System Architecture

The operational system is composed of two principal software modules:

1. QGIS Extension Module: Deployed inside QGIS, this plugin establishes and manages the local socket endpoint responsible for receiving and interpreting MCP commands.
2. MCP Orchestration Server: A dedicated Python application that fully adheres to the Model Context Protocol specification, acting as the intermediary between Claude and the QGIS plugin.

Deployment Instructions

Prerequisites

• A functional installation of QGIS (Compatibility verified primarily across 3.22 and 3.34 versions of the 3.X branch).
• Access to a capable desktop environment running Claude.
• Python version 3.10 or later.
• The uv package manager utility.

Installation guide for uv:

If operating on macOS:

bash brew install uv

If using Windows PowerShell:

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

General installation details are available at: Install uv

🛑 Critical Warning: Do not proceed with the following steps until uv is successfully installed.

Source Code Retrieval

Acquire the repository contents onto your local machine. Cloning via Git is recommended:

bash https://github.com/syauqi-uqi/qgis_mcp_modify1.git

QGIS Extension Setup

Transfer the contents of the qgis_mcp_plugin directory into your active QGIS user profile's plugin directory.

To locate your profile folder in QGIS, navigate to Settings -> User profiles -> Open active profile folder. Within that path, navigate to Python/plugins and place the entire qgis_mcp_plugin folder there.

(Typical Windows Path Example: C:\Users\USER\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins) (Typical macOS Path Example: ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins)

After placement, restart QGIS. Access the plugin manager via the menu: Plugins -> Installing and Managing Plugins. Switch to the All tab, search for "QGIS MCP", and activate the corresponding checkbox.

Claude Desktop Configuration

Modify the configuration file within the Claude application: Navigate to Claude > Settings > Developer > Edit Config and locate claude_desktop_config.json to incorporate the following server definition:

Note: If the 'Developers tab' or the configuration file is inaccessible, consult this guide: documentation.

{ "mcpServers": { "qgis": { "command": "uv", "args": [ "--directory", "#Replace this placeholder with your actual server script path#", "run", "qgis_mcp_server.py" ] }

}

}

Operational Workflow

Initiating Connectivity

1. Within the QGIS application, access the extension via the main menu: plugins -> QGIS MCP-> QGIS MCP.
2. Activate the "Start Server" control.

Interaction with Claude

Once the configuration JSON in Claude is updated and the QGIS socket server is active, a dedicated tool icon (resembling a hammer) will appear in the Claude interface, granting access to the QGIS MCP toolset.

Available Toolset Functions

• ping: Verifies the operational status and reachability of the server.
• get_qgis_info: Retrieves detailed metadata regarding the active QGIS installation.
• load_project: Opens and initializes a QGIS project file from a specified file location.
• create_new_project: Generates a completely new project workspace and saves it immediately.
• get_project_info: Fetches current contextual data about the active project.
• add_vector_layer: Injects a vector dataset into the project map canvas.
• add_raster_layer: Injects a raster dataset into the project map canvas.
• get_layers: Returns a comprehensive inventory of all layers currently loaded.
• remove_layer: Deletes a specified layer based on its unique identifier.
• zoom_to_layer: Adjusts the map viewport to encompass the full extent of a designated layer.
• get_layer_features: Extracts feature geometries and attributes from a vector layer, optionally with row limiting.
• execute_processing: Runs any specified QGIS processing algorithm using provided parameter mappings.
• save_project: Persists the current project state to the defined file path.
• render_map: Generates a static image (e.g., PNG) output of the current map view extent.
• execute_code: Executes arbitrary, user-supplied strings of PyQGIS commands.

Command Sequence Demonstrations

This demonstrates the sequence used in the initial proof-of-concept demo: (https://x.com/jjsantoso/status/1900293848271667395). For testing the capabilities of this revised version, refer to: (https://www.linkedin.com/posts/syauqi-arka-yudisti-73b236288_qgis-ai-vibemapping-activity-7316248625045483524-hQdB?utm_source=share&utm_medium=member_android&rcm=ACoAAEXNN58BLMyjf4iZIy1KZZJBUFyiNlLtNSg)

plain Instruction Set for QGIS Operation: 1. Execute 'ping' to confirm bidirectional link integrity. If successful, proceed. 2. Establish a fresh QGIS workspace and serialize it to: "C:/Users/USER/GitHub/qgis_mcp/data/cdmx.qgz". 3. Ingest the vector dataset located at: "C:/Users/USER/GitHub/qgis_mcp/data/cdmx/mgpc_2019.shp", assigning it the display name "Colonias". 4. Ingest the raster dataset located at: "C:/Users/USER/GitHub/qgis_mcp/data/09014.tif", assigning it the display name "BJ". 5. Center the map viewport onto the spatial bounds of the "BJ" layer. 6. Initiate the 'Centroid' geoprocessing tool on the "Colonias" layer. Crucially, suppress the geometry validation step. Output the resulting geometry collection to "colonias_centroids.geojson". 7. Run custom code to generate a thematic map (Choropleth) for the "Colonias" layer based on the attribute field "POB2010". Employ a 5-class quantile scheme utilizing the Spectral color palette. 8. Output a high-resolution map rendering to the file path: "C:/Users/USER/GitHub/qgis_mcp/data/cdmx.png". 9. Finalize by saving the entire QGIS project state.

Advanced Usage Scenario (Indonesian Context)

plain Objective: Automate geospatial data preparation, styling, and map layout generation for a coastal area analysis project.

1. Connection Validation: Ping the server to ensure active communication.

2. Project Initialization: Create and save the primary QGIS file structure at:
   "D:/PROJECT/MCP/claudemap.qgz" (Use forward slashes for maximum system compatibility).

3. Data Ingestion (Vector):
   a. Load the multi-part OpenStreetMap export: "D:/PROJECT/MCP/map (2).osm" (Note: Expect automatic layer partitioning into points, lines, multilinestrings, and multipolygons). b. Load the shapefile: "D:/PROJECT/MCP/Bahan_Mundupesisir/aoi.shp" and designate it as "aoi".

4. View Extent Setting: Adjust the map view to perfectly frame the extent of the newly loaded "aoi" layer.

5. Layer Management (Cleanup/Visibility):
   a. Permanently discard the layer named "map (2) — points". b. Toggle off the visibility of the "aoi" layer (retain it for context/extent reference, but hide rendering).

6. Symbology Configuration: Apply specific visual styles to the OSM components: a. "map (2) — lines":

   • Color: #ff6201 (Vibrant Orange)
   • Stroke Weight: 0.5 millimeters b. "map (2) — multilinestrings":
   • Color: #8bff07 (Fluorescent Green)
   • Stroke Weight: 0.8 millimeters c. "map (2) — multipolygons":
   • Interior Fill Color: #fff65f (Pale Yellow)
   • Border Stroke Color: #fff65f (Match fill)
   • Stroke Weight: 0.3 millimeters
   • Transparency Level: 80% opacity (i.e., 20% visible fill)

7. Layout Creation (A4 Portrait): Construct a final map layout: a. Define a new layout object sized to A4 dimensions (210mm wide x 297mm high). b. Set the map frame scale precisely to 1:10,000 and activate the feature to prevent layer changes from affecting this item's scale ("Lock layers for map item"). c. Insert a Title Element:

   • Text Content: "PETA MUNDUPESISIR BY CLAUDE.AI"
   • Formatting: Bold, Font Size 24 points
   • Placement: Centered at the top margin. d. Incorporate auxiliary elements: A Scale Bar and a dynamic Legend (if applicable).

8. Final Image Export: Render the completed layout to a high-quality image file:

9. Output Path: "D:/PROJECT/MCP/claudemap.png"

10. Output Resolution: 600 Dots Per Inch (DPI) (Monitor file size implications).

11. Project Persistence: Execute the command to save the current QGIS configuration.