QgisStreamMCP

QGIS as a service for your AI assistant — Deploy once, use QGIS from anywhere. No local installation required, no GIS expertise needed.

Run a full QGIS Desktop inside Docker and expose it as an MCP server. Your AI assistant gets 42 tools covering data loading, spatial analysis, cartography and multi-format export. You don't need QGIS installed — the AI handles it entirely on your behalf, from any device, at any time.

Administrators deploy the container once (on a server, a NAS, or locally). Users connect their AI client and immediately have QGIS capabilities available in their conversations.

<p align="center"> <img src="docs/architecture.png" alt="Architecture" width="700"> </p>

Highlights

• No QGIS Required — The full QGIS Desktop runs in Docker. Your AI assistant uses it on your behalf — no local installation, no GIS expertise needed.
• Available Anywhere — Deploy on a server or locally. Connect from any MCP-compatible AI client (Claude Desktop, Cursor, Continue...).
• Smart Data Pipeline — set_study_zone("Montpellier") then smart_load("bdtopo_batiments"). Downloads WFS as local GeoPackage with automatic pagination, R-tree spatial index, CRS transform. Processing runs 60-250x faster than live WFS.
• 30+ Pre-configured French Datasets — BD TOPO, Admin Express, RPG, IGN orthophotos, cadastre, DEM, Corine Land Cover, OSM, Esri. No API key needed.
• Full QGIS Desktop — Live GUI via noVNC. AI and user work on the same instance simultaneously.
• 1000+ Processing Algorithms — Native, GDAL, GRASS, SAGA. All accessible via MCP tools.
• Automated Recipes — Pre-built workflows (density analysis, flood risk, land cover, coastal pressure). One command: run_recipe("risque_inondation", zone="Nimes").
• Multi-format Export — PDF layouts, interactive Leaflet maps (standard, flood analysis, temporal), QField mobile packages, Grist collaborative documents.
• MCP App — Interactive QGIS view embedded directly in the conversation (VNC viewer, file upload, keyboard/mouse forwarding).

Quick Start

git clone https://github.com/nic01asFr/QgisStreamMCP.git
cd QgisStreamMCP
docker compose up -d --build

Endpoints

Port	Service	URL
6080	noVNC (QGIS in browser)	http://localhost:6080
8100	MCP Server (Streamable HTTP)	http://localhost:8100/mcp
8080	REST API	http://localhost:8080/docs
8081	MJPEG stream	http://localhost:8081/stream

Connect to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "qgis": {
      "url": "http://localhost:8100/mcp"
    }
  }
}

Smart Data Loading

The core innovation: a structured pipeline that replaces unreliable live WFS connections with fast local GeoPackage files.

Why?

Problem	Live WFS	Smart Loading
Pagination	IGN silently truncates at 5000	ogr2ogr handles all pages automatically
Spatial index	None (in-memory)	R-tree in GeoPackage
Processing speed	60-250x slower (network + no index)	Fast local file
Network during analysis	HTTP requests per feature	Zero network
CRS confusion	Mixed 4326/3857/2154	Standardized EPSG:2154

Pipeline

1. set_study_zone(target="Montpellier")    # Geocode, store bbox, zoom
2. smart_load(id="osm_xyz")                # Basemap (streaming)
3. smart_load(id="bdtopo_batiments")       # Buildings (download GPKG)
4. smart_load(id="bdtopo_routes")          # Roads (download GPKG)
5. get_screenshot                           # Verify
6. run_processing / execute_python          # Analyze
7. export_pdf / export_web_map / ...        # Deliver (PDF, HTML, QField, Grist)

Performance (Montpellier, ~10 km bbox)

Operation	Features	Time
Download buildings	10,000	~30s
Download roads	5,000	6.8s
Cache reload (2nd call)	10,000	instant
Buffer 50m	10,000	1.8s
Dissolve by usage	10,000	2.2s
Density grid 500m	440 cells	0.3s

Caching

Downloads are cached in /data/cache/ with bbox hash. Same area = instant reload for 24h.

Available Data Sources

All sources are free (IGN open data since July 2021). No API key needed.

Vector Data (WFS, downloaded as GPKG)

ID	Name	Key Attributes
bdtopo_batiments	Buildings	nature, usage, height, floors, materials
bdtopo_routes	Roads	nature, importance, width, lanes, speed
bdtopo_hydrographie	Rivers	name, class, width
bdtopo_vegetation	Vegetation zones	nature
bdtopo_voie_ferree	Railways	nature, nb_voies
bdtopo_hydro_surfaces	Water bodies	nature, name
bdtopo_communes	Communes (BD TOPO)	name, code INSEE, population
admin_express_communes	Communes (Admin Express)	name, code, population
admin_express_departements	Departments	name, code
admin_express_regions	Regions	name, code
rpg	Agricultural parcels	crop type, area
bdtopo_poi	Points of interest	nature
bdtopo_lieu_dit	Place names	name
bdtopo_surface_activite	Activity zones	nature
bdtopo_equipement_transport	Transport facilities	nature

Basemaps (streaming)

ID	Name
osm_xyz	OpenStreetMap
ign_planign	Plan IGN v2
ign_scan25	Cartes topo IGN 1:25000
cartodb_positron	Light basemap
cartodb_dark	Dark basemap
esri_world_topo	Esri World Topographic
stamen_terrain	Stamen Terrain (relief)

Imagery (streaming)

ID	Name
ign_ortho_wmts	IGN orthophotos (WMTS, fast)
ign_ortho_wms	IGN orthophotos (WMS)
ign_ortho_irc	IGN infrared photos
esri_world_imagery	Esri satellite

Other (WMS/API)

ID	Name
ign_cadastre	Cadastral parcels
ign_dem	High-resolution DEM
corine_land_cover	Land cover 2018
ban_geocode	Address geocoding API
geo_api_communes	Commune info API
dvf_api	Property transactions API
panoramax	Street-level imagery API
ign_altimetrie	Elevation API

Recipes

Pre-built workflow templates that automate complete analyses — from data loading to styled map export.

ID	Name	Description
densite_bati	Building Density	Hex grid density analysis with graduated symbology
urbanisme_general	Urban Overview	Buildings, roads, vegetation, hydrology with categorized styles
risque_inondation	Flood Risk	Flood zones, building exposure, buffer analysis + interactive web map
occupation_sol	Land Cover	Corine Land Cover with categorized symbology
pression_fonciere_cotiere	Coastal Land Pressure	DVF transactions 2020-2024, coastal bands + temporal web map

Usage

# Automated (all steps in one shot)
run_recipe(id="risque_inondation", zone="Nimes")

# Manual (follow steps one by one)
get_recipe(id="densite_bati", zone="Montpellier")
→ Returns step-by-step instructions to execute individually

Export Formats

PDF Layout

Print-ready PDF via QGIS print layouts with pre-built templates (A3 landscape, A4 portrait). Includes title, legend, scalebar, north arrow, and data sources.

apply_layout_template(template="a3_landscape", title="Flood Risk — Nimes")
export_pdf(layout="a3_landscape")

Interactive Web Map

Leaflet HTML files with embedded GeoJSON data. Three specialized templates:

Template	Use case	Features
Standard	General map	Layer toggle, popup, legend, basemap selector
Flood	Flood risk analysis	Water height slider, building exposure stats, animation
Temporal	Time series	Year slider, per-band statistics, trend arrows, animated playback

QField Mobile Package

Portable ZIP ready for QField mobile data collection:

• .qgz project with relative GPKG sources
• All vector layers materialized as individual GeoPackages
• Editable Observations layer with form widgets (dropdowns, date picker, camera, free text)

export_qfield(project_name="terrain_survey")
→ /data/terrain_survey_qfield.zip

Grist Document

Converts QGIS project layers or any HTML map into a Grist collaborative document (.grist):

• From project — Exports visible vector layers as Grist tables with a custom map widget
• From HTML — Universal converter: takes any HTML file containing GeoJSON (flood maps, temporal maps, qgis2web exports) and creates a Grist document with data in tables and the original interactive map as a Grist custom widget

Detected column types: Choice (colored dropdowns), Date (epoch timestamps), Ref (cross-table references). Form-like tables automatically get a Grist Form page.

# From QGIS project
export_grist(title="Urban Analysis")

# From any HTML with GeoJSON
export_grist(html_path="/data/flood_map_nimes.html")

MCP Tools

Smart Loading

Tool	Description
set_study_zone	Define study area (commune, address, bbox). Geocodes, stores bbox, zooms canvas.
get_study_zone	Get current study zone (name, bbox in 4326 + 2154).
smart_load	Load data by catalog ID. WFS → local GPKG with spatial index. Rasters stream.

Core

Tool	Description
execute_python	Run PyQGIS code with full access to iface, project, processing, helpers module.
get_screenshot	Capture QGIS canvas as PNG. Auto-included after modifying tools.
get_project_info	Current project state (layers, CRS, layouts, extents).
run_processing	Execute any of 1000+ Processing algorithms.
search_algorithms	Find Processing algorithms by keyword.
zoom_to	Navigate to extent, layer, or point.

Data & Layers

Tool	Description
add_layer	Add vector/raster/WFS/WMS by URI.
remove_layer	Remove a layer.
get_features	Query features with attribute/spatial filters.
list_datasources	Browse the pre-configured data catalog.
add_from_catalog	Add a source by catalog ID.

Styling

Tool	Description
set_layer_style	Apply single color, categorized, or graduated symbology.
set_layer_visibility	Show/hide layers.
apply_layout_template	Apply a print layout template (A3 landscape, A4 portrait).
list_layout_templates	List available layout templates.

Recipes

Tool	Description
list_recipes	Browse available workflow recipes.
get_recipe	Get recipe details with parameter substitution.
run_recipe	Execute a complete recipe automatically (all steps in one shot).

Export

Tool	Description
export_pdf	Export print layout to PDF.
export_web_map	Export visible layers as interactive Leaflet HTML.
export_flood_map	Interactive flood analysis HTML (water height slider, building exposure).
export_temporal_map	Interactive temporal analysis HTML (year slider, animated playback).
export_qfield	QField-ready ZIP package (.qgz + GPKGs + editable Observations layer).
export_grist	Grist document from project layers or from any HTML with GeoJSON.
export_layer	Export vector layer to GPKG, GeoJSON, Shapefile, CSV.

Files

Tool	Description
upload_file	Upload file (shapefile, GeoJSON, GPKG, CSV, TIFF, project).
download_file	Download file from /data/.
list_files	List files in /data/.
delete_file	Delete file from /data/.
download_project	Save project as .qgz.

GUI Interaction

Tool	Description
qgis_desktop_ui	Open interactive QGIS MCP App in conversation.
mouse_click / mouse_scroll / mouse_drag / key_press	Direct GUI interaction via xdotool.

Projects

Tool	Description
new_project	Create empty project.
open_project	Open a .qgz project.
save_project	Save current project.

MCP Skills (Resources)

Reference documents that guide the AI assistant's expertise:

Resource URI	Content
skill://smart-loading	Smart Loading Pipeline — set_study_zone + smart_load, CRS handling, caching
skill://pyqgis	PyQGIS scripting patterns & API usage
skill://processing	Processing algorithms guide (native, GDAL, GRASS)
skill://cartography	Symbology, labels, print layouts, PDF export
skill://helpers	Ready-made Python helpers (geocode, add_wfs, zoom_to, create_point_layer...)
skill://data-sources	French national datasets reference
skill://recipes	Workflow recipes reference
skill://external-services	Calling external HTTP services from PyQGIS scripts
skill://qgis-status	Live QGIS instance status

MCP Prompts

Prompt	Description
analyse_territoire	Template for territory analysis (zone + question).
workflow_donnees	Guided workflow — theme-based loading (urbanisme, environnement, transport, agriculture, risques) with step-by-step instructions.

MCP App

An interactive QGIS view embedded directly in the Claude conversation:

• Live VNC viewer — See and interact with QGIS in-conversation
• File upload — Drag & drop files directly into the QGIS container
• Keyboard/mouse forwarding — Full interaction without leaving the chat
• MJPEG fallback — Lightweight stream for quick visual feedback

Example Workflows

Manual: Urban Analysis

User: "Analyse l'urbanisation autour de Montpellier"

AI: [set_study_zone("Montpellier")]
    → Geocodes, stores bbox, zooms canvas

    [smart_load("osm_xyz")]              → OpenStreetMap basemap
    [smart_load("bdtopo_batiments")]     → 10,000 buildings as GPKG
    [smart_load("bdtopo_routes")]        → 5,000 road segments

    [execute_python → density grid]      → 500m hex grid, graduated symbology
    [apply_layout_template("a3_landscape", title="Densité bâtie — Montpellier")]
    [export_pdf]                         → /data/densite_montpellier.pdf

Automated: Flood Risk with Recipe

User: "Analyse le risque inondation à Nîmes"

AI: [run_recipe("risque_inondation", zone="Nimes")]
    → Executes all steps automatically:
      1. set_study_zone("Nimes")
      2. smart_load basemap + buildings + flood zones
      3. Buffer analysis (50m, 100m, 200m from flood zones)
      4. Building exposure classification
      5. Graduated symbology
    → Returns screenshot + statistics

    [export_flood_map(include_fields=["nature","usage","height"])]
    → Interactive HTML with water height slider

    [export_grist(html_path="/data/flood_map_nimes.html")]
    → Grist document with editable tables + embedded map widget

Field Survey: QField Export

User: "Prépare un relevé terrain pour la commune de Sète"

AI: [set_study_zone("Sète")]
    [smart_load("bdtopo_batiments")]
    [smart_load("bdtopo_routes")]
    [set_layer_style("Batiments", type="categorized", field="usage")]

    [export_qfield(project_name="releve_sete")]
    → ZIP with .qgz + GPKGs + Observations layer (camera, dropdowns, date picker)
    → Ready to load on QField mobile app

Extending with External Services

PyQGIS scripts (execute_python) can call any HTTP service accessible from the container — local or remote. This covers ML inference APIs, custom backends, satellite processors, elevation services, or any internal API.

Pass service URLs via environment variables in .env:

MY_SERVICE_URL=http://host.docker.internal:8001

Then use them in scripts:

import os, urllib.request, json
url = os.environ.get("MY_SERVICE_URL")
# call your service...

host.docker.internal resolves to the host machine, allowing access to services running outside the container.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    QgisStreamMCP Container                      │
│                                                              │
│  supervisord                                                 │
│  ├── Xvfb :99                (virtual display 1920x1080)    │
│  ├── fluxbox                 (window manager)               │
│  ├── QGIS Desktop ◄─────────────────────┐                  │
│  │   └── qgis_bridge.py    (startup)    │ UNIX socket      │
│  ├── x11vnc → noVNC         (:6080)     │                  │
│  ├── api_server.py           (:8080) ───┘                   │
│  ├── main_mcp.py             (:8100) ───┘                   │
│  └── stream_server.py        (:8081)                        │
│                                                              │
│  /data/          (user files, projects)                     │
│  /data/cache/    (smart_load GPKG cache, 24h)               │
│  /app/skills/    (MCP skill documents)                      │
│  /app/datasources.json  (30+ pre-configured sources)        │
└──────────┬──────────────────────────────────────────────────┘
           │ HTTP (optional)
           ▼
    External services     (any HTTP API reachable from the container)

Communication Flow

Claude Desktop / MCP Client
  │ JSON-RPC over Streamable HTTP (:8100)
  ▼
main_mcp.py (MCP Server)
  │ UNIX socket /tmp/qgis_bridge.sock
  ▼
qgis_bridge.py (runs inside QGIS, main thread)
  │ PyQGIS API (iface, QgsProject, processing)
  ▼
QGIS Desktop (Xvfb display :99)
  │ X11
  ▼
x11vnc → websockify → noVNC (:6080)
  │ WebSocket
  ▼
User's browser

Development

# Source files are mounted as volumes — edit locally
# Restart to apply changes:
docker compose restart qgisstreammcp

# View logs
docker compose logs -f qgisstreammcp

# Test API
curl http://localhost:8080/health
curl -X POST http://localhost:8080/api/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "result[\"v\"] = Qgis.version()"}'

# Test smart loading
curl -X POST http://localhost:8080/api/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "result.update(helpers.set_study_zone(\"Montpellier\"))", "timeout": 30}'

Project Structure

QgisStreamMCP/
├── main_mcp.py             # MCP Server (40 tools, 10 resources, 3 prompts)
├── datasources.json        # 30+ pre-configured data sources catalog
├── qgis_app.html           # MCP App (interactive QGIS in conversation)
├── src/
│   ├── qgis_bridge.py      # Runs inside QGIS (UNIX socket bridge, 45 actions)
│   ├── qgis_helpers.py     # Python helpers (geocode, smart loading, etc.)
│   ├── api_server.py       # FastAPI REST API
│   └── stream_server.py    # MJPEG stream
├── skills/                 # MCP Resources (AI skill documents)
│   ├── smart_loading.md
│   ├── pyqgis.md
│   ├── processing.md
│   ├── cartography.md
│   ├── helpers.md
│   ├── data_sources.md
│   └── external_services.md
├── recipes/                # Workflow recipes (JSON)
│   ├── densite_bati.json
│   ├── urbanisme_general.json
│   ├── risque_inondation.json
│   ├── occupation_sol.json
│   └── pression_fonciere_cotiere.json
├── templates/              # Print layout templates (.qpt)
│   ├── a3_landscape.qpt
│   ├── a4_portrait.qpt
│   └── web/                # Leaflet HTML templates
│       ├── leaflet_template.html
│       ├── leaflet_flood_template.html
│       └── leaflet_temporal_template.html
├── projects/               # QGIS project files (persisted)
├── docs/                   # Architecture diagrams
├── Dockerfile
├── docker-compose.yml
├── supervisord.conf
├── entrypoint.sh
├── requirements.txt
└── CLAUDE.md

License

MIT

Credits

• QGIS — https://qgis.org
• noVNC — https://novnc.com
• MCP — https://modelcontextprotocol.io
• IGN Geoplateforme — https://data.geopf.fr (free French national geodata)
• GDAL/OGR — https://gdal.org (data conversion & download engine)