QGIS MCP Server for Claude AI Integration

Overview

The QGIS MCP Server is a lightweight bridge that connects QGIS desktop projects to Claude AI (via the Model Context Protocol). It exposes a set of prompt-assisted tools and code-execution endpoints so Claude-based agents can create QGIS projects, load and inspect layers, run Python/QGIS processing scripts, and move files between the local environment and AI-driven workflows. The server acts as the runtime and context-provider that lets an LLM safely inspect and manipulate QGIS projects without giving direct unrestricted access to your machine.

This integration is useful when you want to automate GIS workflows with natural language instructions, enable programmatic project setup, or delegate repetitive spatial processing tasks to an LLM. Typical scenarios include creating templated maps, running analyses (buffers, intersections, raster operations), and exporting results — all orchestrated by Claude prompts while QGIS executes the spatial operations locally.

Features

• Exposes MCP-compatible endpoints to integrate QGIS with Claude AI agents
• Create, open, and save QGIS projects programmatically
• Load vector and raster layers from URLs, local paths, or uploaded files
• Execute Python/QGIS Processing code snippets in a controlled environment
• Transfer files (GeoPackage, shapefiles, GeoJSON, rasters) between server and client
• Prompt-assisted tooling so LLMs can request and run GIS tasks with context
• Lightweight, minimal dependencies; designed to run alongside a local QGIS installation

Installation / Configuration

Prerequisites: Python 3.8+, QGIS (matching the PyQGIS version), and pip. A QGIS Python environment or a system with QGIS bindings available is required to run processing scripts.

Clone and install:

git clone https://github.com/jjsantos01/qgis_mcp.git
cd qgis_mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Environment configuration (example .env):

# .env
MCP_HOST=0.0.0.0
MCP_PORT=8080
WORKDIR=/var/qgis_mcp/workdir
ALLOWED_ORIGINS=http://localhost:3000
LOG_LEVEL=info

Start the server (example):

# activate your QGIS Python environment if needed, then:
python server.py --host $MCP_HOST --port $MCP_PORT --workdir $WORKDIR

Or use Docker (if provided by the repository):

docker build -t qgis-mcp .
docker run -p 8080:8080 -v /path/to/workdir:/workdir qgis-mcp

Note: Ensure the process runs in an environment where PyQGIS is importable (system QGIS environment or a matching conda/pip environment).

Available Tools / Resources

The server exposes a collection of tools intended for MCP clients (Claude agents). Commonly exposed capabilities include:

• Project management
  • create_project(name)
  • open_project(path)
  • save_project(path)
• Layer operations
  • load_layer(source_url|local_path)
  • list_layers()
  • remove_layer(layer_id)
• Code execution
  • run_python(code): execute a Python snippet in the QGIS context (returns logs, outputs, and file outputs)
• File handling
  • upload_file(file)
  • download_file(path)
• Processing helpers
  • run_processing(algorithm_id, parameters)

Example HTTP-style endpoints (conceptual):

Example request to run code:

POST /mcp/run
Content-Type: application/json

{
  "language": "python",
  "code": "layer = iface.addVectorLayer('/workdir/data.shp', 'data', 'ogr')\nprint(layer.isValid())"
}

Response contains stdout, stderr, and any output file references.

Use Cases

• Project templating and reprojection

  • Prompt Claude to create a new QGIS project, add basemap and administrative layers, reproject layers to a target CRS, and save the project file for handoff.

• Batch spatial analysis via natural language

  • Ask Claude to load a parcel layer and a floodplain raster, compute parcel-area intersections with the floodplain, create buffers, and export the affected parcels as a GeoPackage.

• Automated map export and reporting

  • Use Claude to style layers based on attributes, render map layouts, export map images or PDFs, and generate a short report summarizing the steps taken.

• Ad-hoc scripting with safety

  • Run small Python snippets to clean attributes, compute new fields, or run QGIS Processing algorithms with outputs managed in the server working directory.

Example: Compute buffer and export GeoJSON

1. Upload or point to a vector layer.
2. Issue a run request with Python code that creates a 100m buffer, saves the result to /workdir/buffer.geojson.
3. Download buffer.geojson from the files endpoint.

Tips and Best Practices

• Run the server inside a controlled environment and restrict access (ALLOWED_ORIGINS, firewall) — the server executes code on your host.
• Limit uploaded file sizes and sanitize inputs if exposing the server to untrusted networks.
• Use a dedicated work directory for each project to avoid accidental file collisions.
• Test processing scripts locally in QGIS Python console before invoking them through the MCP server.

For full API details, examples, and repository-specific configuration, refer to the GitHub project: https://github.com/jjsantos01/qgis_mcp