Allows interaction with QGIS (Quantum GIS) through the QGIS MCP Plugin, enabling AI agents to manage GIS projects, layers, and perform geospatial operations.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@QGIS MCP Server load the OpenStreetMap basemap and zoom to Paris"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This project explores ways to interact with QGIS using the QGIS MCP Plugin and an MCP Server.
Install QGIS MCP Plugin.
Plugins > Manage and install plugins
Source code at github.com/nkarasiak/qgis-mcp
Set configuration to start MCP server on start-up.
Configure Claude as directed, mostly. Best to add -s user to the bash command.
claude mcp add qgis -s user -- uvx --from https://github.com/nkarasiak/qgis-mcp/archive/refs/tags/v0.11.0.zip qgis-mcp-serverAsk Claude to ping QGIS.
The architecture described through key files and classes.
app/main.py
|-- app/domain/claude_mcp/service.py
ClaudeMCP -- Chat loop
|-- app/clients/claude.py
Claude <-------------------Claude API------------------> LLM
|-- app/clients/qgis_mcp.py
QgisMcpClient <-stdio-> subprocess qgis_mcp.server <---> QGIS MCP Plugin ServerTest with:
uv run pytest -vRun with:
uv run python -m app.mainRelated MCP server: QGISMCP
Consider running the entire application on an AWS EC2.
Easily see use cases with times that exceed maximum Lambda timeout.
Consider FastAPI for REST endpoints.
Add a spatial bookmark to the project for quick navigation. Provide a name and extent (xmin/ymin/xmax/ymax) with CRS.
Inputs: name (required), xmax (required), xmin (required), ymax (required), +3 more.
Add features to a vector layer. Each feature: {attributes: {field: value}, geometry_wkt: 'POINT(1 2)'}. Returns count of added features.
Inputs: features (required), layer_id (required).
Add a new field to a vector layer. field_type: 'string', 'int', 'double', 'bool', 'date', 'datetime'.
Inputs: layer_id (required), field_name (required), field_type (required), length, +1 more.
Add a text label to a print layout (mm). text may contain [% expression %] for dynamic content. color is hex (e.g. '#000000').
Inputs: text (required), layout_name (required), x, y, +4 more.
Add a legend to a print layout, linked to a map item (defaults to the first map item). Position/size in mm.
Inputs: layout_name (required), x, y, title, +3 more.
Add a map item to a print layout at specified position and size (in millimeters).
Inputs: x (required), y (required), width (required), height (required), +1 more.
Add a picture or SVG (logo, north arrow) to a print layout. path is an image or SVG file path. Position/size in mm.
Inputs: path (required), layout_name (required), x, y, +2 more.
Add a scale bar to a print layout, linked to a map item. style e.g. 'Single Box', 'Double Box', 'Line Ticks Up', 'Numeric'.
Inputs: layout_name (required), x, y, style, +3 more.
Add an attribute table for a vector layer to a print layout. max_rows caps the number of features shown. Position/size in mm.
Inputs: layer_id (required), layout_name (required), x, y, +3 more.
Create a map theme from the current layer visibility state. If a theme with this name exists, it will be updated.
Inputs: name (required).
Add a raster layer (GeoTIFF, etc.) to the project.
Inputs: path (required), name, provider.
Add a table join to a vector layer.
Inputs: join_field (required), target_field (required), join_layer_id (required), target_layer_id (required), +1 more.
Add a vector layer (shapefile, GeoJSON, GeoPackage, etc.) to the project.
Inputs: path (required), name, provider.
Add a web layer (XYZ, WMS, WFS) to the project. service: 'xyz', 'wms', 'wfs'.
Inputs: url (required), service (required), crs, name.
Apply a map theme — restores the layer visibility state saved in the theme.
Inputs: name (required).
Apply a QGIS QML style file to a layer.
Inputs: path (required), layer_id (required).
Execute multiple commands in a single round-trip. Each command is {"type": "<command_name>", "params": {...}}. Destructive commands (execute_code, remove_layer, delete_features, set_setting, reload_plugin) are not allowed in batch — use them individually.
Inputs: commands (required). Returns: result
Clear the selection on a layer.
Inputs: layer_id (required).
Configure a print layout's atlas: coverage_layer (vector layer id) drives one page per feature. Optional page_name_expression, filter_expression, sort_expression.
Inputs: layout_name (required), coverage_layer (required), enabled, sort_expression, +2 more.
Create a new layer group in the layer tree. Optionally specify a parent group name.
Inputs: name (required), parent.
Create a new print layout.
Inputs: name (required).
Create a new in-memory vector layer. geometry_type: Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon. fields: [{name, type}] where type is integer, double, string, date, datetime.
Inputs: name (required), geometry_type (required), crs, fields.
Create a new empty QGIS project and save it to the given path.
Inputs: path (required).
Build QGIS Processing Model (.model3) from structured spec; save to user models folder, register in Processing Toolbox. Only call needed: algorithm discovery + param validation run in the plugin against the live registry, so do NOT call list_processing_algorithms or get_algorithm_help first. Pass keyword ('buffer') or full id ('native:buffer'); handler resolves it. Ambiguous hint returns candidate list to refine and retry. Bad param/output names reported with the valid set.
Spec: inputs: [{name, type, description?, default?, optional?, parent_layer? (for field/distance), options? (for enum)}]. Types: vector, feature_source, raster, field, number, integer, distance, string, boolean, extent, crs, point, file, folder, enum, multiple_layers. steps: [{id, algorithm, description?, parameters: {ALG_PARAM: value}}]. algorithm = keyword or full id. Param values: '@input_name' = model input value '$step_id.OUTPUT' = earlier step output '=expression' = QGIS expression at run time else = static literal (number/bool/string/list) outputs: [{name, from_step, from_output, description?}] = exposed outputs; omit to expose the last step OUTPUT as 'Result'.
Name collision appends a suffix (name_2.model3, ...). Response returns the actual 'name', the 'requested_name', and 'resolved_steps' (which algorithm each hint mapped to).
Inputs: name (required), steps (required), group, inputs, +2 more. Returns: object
Delete features by feature IDs or expression filter. Provide either fids (list of ints) or expression (string), not both.
Inputs: layer_id (required), fids, expression.
Delete a field from a vector layer.
Inputs: layer_id (required), field_name (required).
Run diagnostic checks on the QGIS MCP stack. Reports QGIS version, plugin/server version match, processing providers, connected clients, and project status.
Inputs: no named parameters. Returns: object
Duplicate a layer (including its style) under a new name.
Inputs: layer_id (required), new_name.
Evaluate a standalone QGIS expression to a scalar value (e.g. aggregate('layer','sum','field'), @project_var, now()). Optional layer_id adds layer scope. Distinct from validate_expression (validate only) and field_calculator (per-feature).
Inputs: expression (required), layer_id.
Execute arbitrary PyQGIS code. Use for operations not covered by other tools. Has access to QgsProject, iface, and core QGIS classes. Returns stdout/stderr.
Inputs: code (required).
Execute a QGIS Processing algorithm. Use get_algorithm_help to discover parameters. Layer params accept layer IDs or file paths. Set OUTPUT to 'memory:' for temp layers.
Inputs: algorithm (required), parameters (required).
Run one algorithm once per parameter dict in 'parameters_list'. Returns a per-run result with index and success/error status. Use for applying the same operation over many inputs in a single round-trip.
Inputs: algorithm (required), parameters_list (required).
SQL across loaded layers via a virtual layer; reference layers by name in FROM/JOIN. as_layer=True registers the result as a new layer (set geometry_field for spatial output); else returns rows inline (max 1000). layers limits sources by layer id.
Inputs: query (required), layers, as_layer, uid_field, +2 more.
Export a configured atlas. format 'pdf' writes a single multi-page file at output_path; image formats ('png','jpg','tif') write one file per feature into the output_path directory. Call configure_atlas first.
Inputs: layout_name (required), output_path (required), dpi, format.
Export vector/raster to disk; format from output_path extension (.gpkg, .shp, .geojson, .tif, ...). target_crs (e.g. 'EPSG:4326') reprojects on export. filter_expression (vector only) exports a subset matching a QGIS expression.
Inputs: layer_id (required), output_path (required), target_crs, filter_expression.
Export a print layout to file. format: 'pdf', 'png', 'jpg', 'svg'. dpi: resolution (default 300).
Inputs: path (required), layout_name (required), dpi, format.
Add (if missing) + populate a field from a QGIS expression, per feature, in-place. field_type: string|int|double|bool|date|datetime (default double). Example: expression='$area', field_name='area_m2'. Returns updated feature count.
Inputs: layer_id (required), expression (required), field_name (required), length, +2 more.
Find layers by name pattern. Supports fnmatch wildcards (e.g. 'roads*') and substring matching.
Inputs: name_pattern (required). Returns: object
Capture an OPEN 3D Map View as an inline image. Reuses the open view's scene + camera, rendered via a print-layout 3D map item (the 2D get_canvas_screenshot cannot capture the OpenGL 3D view). Requires a 3D map view to be open in QGIS (View > 3D Map Views > New 3D Map View). view_index selects which view when several are open; dpi controls output resolution. Optional camera overrides (applied to the capture only, leaving the live view unchanged): pitch (0 = straight down/top-down, 90 = horizontal/edge-on; ~45 = balanced oblique), heading (compass degrees), distance (metres).
Inputs: dpi, pitch, heading, distance, +1 more.
Get the currently active (selected) layer in the QGIS layer panel.
Inputs: no named parameters. Returns: object
Get detailed help for a processing algorithm: parameters (name, type, optional, default), outputs, and description.
Inputs: algorithm_id (required). Returns: object
Get spatial bookmarks from the project. Each bookmark has a name, group, extent (xmin/ymin/xmax/ymax), and CRS.
Inputs: no named parameters. Returns: object
Get the current map canvas extent and CRS.
Inputs: no named parameters. Returns: object
Get the current map canvas scale, rotation, and magnification factor.
Inputs: no named parameters. Returns: object
Grab a fast screenshot of the current map canvas widget (no re-render). Returns the image inline. Much faster than render_map.
Inputs: no named parameters.
Compute aggregate statistics (count, sum, mean, min, max, stdev) for a numeric field. For non-numeric fields returns count and distinct values.
Inputs: layer_id (required), field_name (required). Returns: object
Get the coordinate reference system (CRS) of a layer: EPSG code, description, whether geographic, and PROJ4 string.
Inputs: layer_id (required). Returns: object
Get the spatial extent (bounding box) and CRS of a layer.
Inputs: layer_id (required). Returns: object
Get features from a vector layer. Flat dicts: _fid + attributes at top level. expression filter (QGIS, e.g. "name = 'Berlin'", "population > 1000000"), limit (max 50, default 10), offset for paging, optional geometry in _geometry key.
Inputs: layer_id (required), limit, offset, expression, +1 more. Returns: object
Get the labeling configuration of a vector layer: enabled state, field, font size, color.
Inputs: layer_id (required). Returns: object
List layers in the current project with IDs, names, types, visibility, and type-specific info. Use limit/offset for pagination. Response includes total_count.
Inputs: limit, offset. Returns: object
Get the full layer tree structure with groups and layers. Returns recursive tree with type, name, visibility, and children.
Inputs: no named parameters. Returns: object
List items in a print layout (type, id, uuid, position, size) and page count.
Inputs: layout_name (required). Returns: object
Get map themes (visibility presets). Each theme stores which layers are visible.
Inputs: no named parameters. Returns: object
Get QGIS message log entries. Filter by level ('info', 'warning', 'critical') and/or tag (e.g. 'QGIS MCP'). Returns newest first.
Inputs: tag, level, limit. Returns: object
Get detailed info for a specific plugin: name, enabled, version, description, author, path.
Inputs: plugin_name (required). Returns: object
List Processing providers (native, gdal, grass, saga, model, ...) with algorithm counts and active status. Use to diagnose missing algorithms.
Inputs: no named parameters. Returns: object
Get current project metadata: filename, title, CRS, layer count, and summary of layers.
Inputs: no named parameters. Returns: object
Get all project-level variables (key-value pairs set in Project Properties).
Inputs: no named parameters. Returns: object
Get QGIS version, profile path, and plugin count.
Inputs: no named parameters. Returns: object
Get raster layer info: band count, dimensions, CRS, extent, per-band statistics, nodata values.
Inputs: layer_id (required). Returns: object
Get the current selection for a layer. Returns feature IDs and count.
Inputs: layer_id (required). Returns: object
Read a QGIS setting by key path (e.g. 'qgis/sketching/sketching_enabled').
Inputs: key (required). Returns: object
Return the distinct values of a field. Use 'limit' to cap results (-1 for all). Useful before building categorized symbology or filters.
Inputs: field (required), layer_id (required), limit. Returns: object
Identify features at a point [x, y] in project CRS across layers (map-click analogue). tolerance (map units) expands the search; 0 = exact hit. layer_ids limits the search (default: visible vector layers). limit caps features per layer.
Inputs: point (required), limit, layer_ids, tolerance.
List all print layouts in the current project with names and page counts.
Inputs: no named parameters. Returns: object
List installed QGIS plugins with name, enabled status, and version. Set enabled_only=true to list only active plugins.
Inputs: enabled_only. Returns: object
Search for processing algorithms by keyword and/or provider. Returns id, name, provider for each match.
Inputs: search, provider. Returns: object
List registered Processing models (the 'model' provider). Returns id, name, group for each. Use run_model to execute one.
Inputs: no named parameters. Returns: object
Load a QGIS project from a .qgs/.qgz file path.
Inputs: path (required).
Move a layer into a layer group by group name.
Inputs: layer_id (required), group_name (required).
Check connectivity to the QGIS plugin server. Returns pong if connected.
Inputs: no named parameters. Returns: object
Band math via the QGIS raster calculator. Reference loaded raster layers in the expression as 'LayerName@band' (e.g. '("dem@1" > 1000) * 1'). Writes a GeoTIFF to output_path. Output grid/extent taken from reference_layer (layer id or name), defaulting to the first loaded raster.
Inputs: expression (required), output_path (required), reference_layer.
Reload a QGIS plugin by name. Cannot reload the MCP plugin itself. Useful during plugin development.
Inputs: plugin_name (required).
Remove a spatial bookmark by its ID.
Inputs: bookmark_id (required).
Remove a layer from the project by its layer ID. This is irreversible.
Inputs: layer_id (required).
Remove a print layout from the project.
Inputs: layout_name (required).
Remove a map theme by name.
Inputs: name (required).
Rename a field in a vector layer.
Inputs: layer_id (required), new_name (required), old_name (required).
Render the current map canvas to an image. Returns the image inline so you can see it. Optionally saves to a file path on disk.
Inputs: path, width, height.
Run a Processing model by registered id (e.g. 'model:myflow') or by a .model3 file path. 'parameters' maps the model's input names to values (layer ids/paths, numbers, etc.).
Inputs: model (required), parameters.
Sample raster pixel values at points. 'points' is a list of [x, y] in the raster's CRS. Omit 'band' to sample all bands. Use transform_coordinates first if your points are in a different CRS.
Inputs: points (required), raster_layer (required), band. Returns: object
Save the current project. Optionally specify a new path.
Inputs: path.
Save a layer's style to a QGIS QML file.
Inputs: path (required), layer_id (required).
Select features in a layer by expression or feature IDs.
Inputs: layer_id (required), fids, expression.
Set the active layer in the QGIS layer panel by layer ID.
Inputs: layer_id (required).
Set the map canvas extent. Coordinates should be in the specified CRS (default: project CRS).
Inputs: xmax (required), xmin (required), ymax (required), ymin (required), +1 more.
Set the map canvas scale and/or rotation. Provide scale as denominator (e.g. 50000 for 1:50000). Rotation in degrees (0-360).
Inputs: scale, rotation.
Set the CRS of a layer (e.g. 'EPSG:4326'). This does NOT reproject data — it only changes how the layer's coordinates are interpreted.
Inputs: crs (required), layer_id (required).
Configure labeling for a vector layer. Set enabled=false to disable labels. Set field_name to the attribute field to label with. Optional: font_size (float), color (hex like '#000000').
Inputs: layer_id (required), color, enabled, font_size, +1 more.
Reorder layer tree nodes; tree order is draw order. layer_ids is the ordered list of layer ids from top (drawn last) to bottom; unlisted layers keep their slots. Clears any custom draw order (it freezes a snapshot list — layers added later would silently draw behind everything).
Inputs: layer_ids (required).
Set a layer property. Supported properties: opacity (0.0-1.0), name (string), min_scale, max_scale (float), scale_visibility (bool).
Inputs: value (required), layer_id (required), property (required).
Set symbology. style_type: 'single' (one symbol), 'categorized' (unique values), 'graduated' (numeric ranges). field required for categorized/graduated. color_ramp: QGIS ramp name (e.g. 'Spectral', 'Viridis', 'Blues'). classes: graduated class count (default 5).
Inputs: layer_id (required), style_type (required), field, classes, +1 more.
Set a layer's visibility in the layer tree (show/hide on map).
Inputs: visible (required), layer_id (required).
Set the project coordinate reference system (e.g. 'EPSG:4326', 'EPSG:3857'). This changes how layers are projected on the map canvas.
Inputs: crs (required).
Set a project-level variable. Variables are accessible in expressions as @key.
Inputs: key (required), value (required).
Write a QGIS setting. Use with care — incorrect settings can affect QGIS behavior.
Inputs: key (required), value (required).
Join attributes by location (native:joinattributesbylocation). predicates int list: 0=intersects 1=contains 2=equals 3=touches 4=overlaps 5=within 6=crosses (default [0]). method: 0=one-to-many 1=first match (default) 2=largest overlap. join_fields = copied columns (default all). No output_path = in-memory layer.
Inputs: join_layer (required), target_layer (required), method, prefix, +3 more.
Transform coordinates between CRS. Accepts a point {x, y}, a point list [{x, y}, ...], or a bbox {xmin, ymin, xmax, ymax}. Returns the same format.
Inputs: source_crs (required), target_crs (required), bbox, point, +1 more. Returns: object
Update feature attributes. updates: [{fid: 1, attributes: {field: value}}]. Returns count of updated features.
Inputs: updates (required), layer_id (required).
Validate a QGIS expression. Returns whether it's valid, any parse errors, and referenced column names. Optionally test against a layer's fields.
Inputs: expression (required), layer_id. Returns: object
Per-polygon stats from a raster (native:zonalstatisticsfb). stats int codes: 0=count 1=sum 2=mean 3=median 4=stdev 5=min 6=max 7=range 8=minority 9=majority 10=variety 11=variance (default [0,1,2]). New columns prefixed by 'prefix'. No output_path = in-memory layer.
Inputs: raster_layer (required), polygon_layer (required), band, stats, +2 more.
Zoom the map canvas to the full extent of the specified layer.
Inputs: layer_id (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 103 tools
Most tools have clearly distinct purposes, but with 103 tools there is some potential for confusion, e.g., between screenshot tools (get_canvas_screenshot, get_3d_screenshot, render_map) and between execution commands (execute_processing, execute_processing_batch, execute_code, batch_commands). Descriptions help differentiate, but the sheer volume may cause an agent to misselect.
All tools follow a consistent snake_case verb_noun pattern (e.g., set_canvas_extent, get_canvas_screenshot, list_processing_algorithms). Even utility tools like 'ping' and 'diagnose' are acceptable standalone verbs. No mixing of conventions.
With 103 tools, the count is extremely high. While QGIS is a complex platform, this granularity far exceeds the typical well-scoped range of 3-15 tools. The surface feels bloated and could be consolidated (e.g., multiple layout addition tools, many field operations).
The tool set covers virtually all major QGIS functionalities: project management, layer CRUD, canvas control, processing algorithms, print layouts, atlas, expressions, SQL, and more. Missing features (e.g., direct geometry editing) can be achieved via execute_processing or execute_code, so no critical gaps.
Geospatial AI MCP server — satellite imagery, embeddings, weather, GNS governance
Geospatial MCP server for earthquake, tsunami, volcano, disaster, and FX data queries.
Skills, agents and memory in the cloud, plus a gateway to your other MCP servers.
