MapSmith

Professional-grade GIS geoprocessing for AI agents — with provenance you can verify.

mapsmith.dev — a real terrain analysis and the manifest that came with it. Both are build products: the figure is rendered from GeoTIFFs MapSmith writes, so the page cannot drift from what the software does.

MapSmith is an open-source MCP server that gives an AI agent real GIS analysis — buffers, overlays, reprojections, zonal statistics, terrain and hydrology — executed by GeoPandas, DuckDB Spatial, exactextract and Whitebox Workflows, never written by the model. Every dataset it produces lands on disk next to a lineage manifest: inputs with checksums, the exact parameters, the CRS decisions and why, engine versions, and the deterministic checks that ran on the result.

Ask for the result. The agent picks the tools. You can check the work afterwards.

The manifest is a specified format, not MapSmith's private output: JSON Schema, a toolchain-free validator, a conformance suite, and a hundred-line emitter that never imports MapSmith. Records carry spec_version, and CI validates real MapSmith output against the spec's own validator. The specification is archived and citable as 10.5281/zenodo.22205213. The names MapSmith puts in a record beyond the ones the specification defines — every extension check name, and every extension field in crs_decisions with the reason it is not a synonym of a key the specification already has — are listed in docs/manifest-vocabulary.md, generated from the source rather than maintained by hand.

Evidence before promises: an A/B on GABench whose headline is a null result — with the analysis that took our own positive number apart — a correctness suite in its own organisation, Argleton, whose published run grades MapSmith on thirty-one traps with answers computed on paper and has already sent six defects back here, notebooks on a real USGS DEM of Mount St. Helens, an in-chat map panel that shows the verification status of every layer it draws, and a measurement of our own tool discovery that retracted two numbers this page had already published — including the one in the bullet list below.

Quickstart

Add MapSmith to any MCP client over stdio (Claude Desktop, Claude Code, Cursor, VS Code):

{
  "mcpServers": {
    "mapsmith": {
      "command": "uvx",
      "args": ["mapsmith"]
    }
  }
}

Docker is the supported path, and confines the server to the directory you mount:

{
  "mcpServers": {
    "mapsmith": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-v", "/absolute/path/to/your/data:/data",
               "-e", "MAPSMITH_WORKSPACE=/data",
               "ghcr.io/mapsmith-ai/mapsmith"]
    }
  }
}

One-click installs:

or from a terminal: code --add-mcp '{"name":"mapsmith","command":"uvx","args":["mapsmith"]}'

To check it runs before wiring a client, uvx mapsmith starts the server on stdio (Ctrl-C to quit) — it speaks MCP, not a CLI, so a silent prompt means it is working.

This page describes 0.4.0, which is what that command installs. When main runs ahead of the published artifact this paragraph says so and names the difference — a reader should never have to find out by calling a tool that is not there. main is ahead of 0.4.0 today, by defects found in shipped code and by one change a reader of this page would notice: eight crs_decisions keys are spelled differently on main, because 0.4.0 had invented names of its own where the specification already fixes one, and left the keys that really are MapSmith's own looking like the format's. No tool, operation or count has moved. [Unreleased] in the changelog has the old-to-new table and the rest of the list.

Then ask your agent things like:

"Take parcels.gpkg, keep only the parcels within 300 m of the river in rivers.gpkg, and give me the result with the analysis lineage."

The Docker image includes the [raster] and [whitebox] extras. With uvx, pick your own: uvx --from "mapsmith[raster,whitebox]" mapsmith. Docker — or uvx on a machine with working wheels — is the only supported installation path: geospatial native dependencies across three OSes are a support black hole, and issues about broken local environments will be redirected here.

Two things about the image, because they change what happens on your machine: it sets MAPSMITH_WORKSPACE=/data itself (the -e above is explicit, not required) and runs as uid 1000, so pass --user $(id -u):$(id -g) if the directory you mount belongs to another user; and it is built for amd64 only, so on Apple Silicon it runs under emulation.

What you get back

Every dataset comes with the file below, written next to it as <output>.provenance.json — enough to re-run the analysis without the model that asked for it:

{
  "spec_version": "1.0.0-draft.3",
  "producer": {"name": "mapsmith", "version": "0.4.0"},
  "operation": "buffer_layer",
  "parameters": {"distance_meters": 300.0},
  "inputs": [{
    "path": "rivers.gpkg",
    "sha256": "b24b884f49eee431133d443d842557d3ed21f3978e2c4b1e8e072fd1240effe8",
    "crs": "EPSG:4326"
  }],
  "crs_decisions": {
    "analysis_crs": "EPSG:32632",
    "reason": "estimated UTM zone for metric buffering on a geographic CRS",
    "x-mapsmith:round_trip": {
      "transformation": {
        "pipeline": "+proj=pipeline +step +proj=unitconvert +xy_in=deg +xy_out=rad +step +proj=utm +zone=32 +ellps=WGS84",
        "accuracy_m": 0.0,
        "is_ballpark": false
      },
      "return_transformation": {
        "pipeline": "+proj=pipeline +step +inv +proj=utm +zone=32 +ellps=WGS84 +step +proj=unitconvert +xy_in=rad +xy_out=deg",
        "accuracy_m": 0.0,
        "is_ballpark": false
      }
    }
  },
  "engine": {"name": "geopandas", "version": "1.0.1"},
  "environment": {},
  "verification": [
    {"name": "input_crs_present", "passed": true, "detail": "'input_path': EPSG:4326"},
    {"name": "input_not_empty", "passed": true, "detail": "'input_path': 1 features"},
    {"name": "result_not_empty", "passed": true, "detail": "1 features"},
    {"name": "crs_present", "passed": true, "detail": "EPSG:4326"},
    {"name": "crs_matches", "passed": true, "detail": "expected EPSG:4326, got EPSG:4326"},
    {"name": "geometry_valid", "passed": true, "detail": "all valid"},
    {"name": "x-mapsmith:no_geometry_is_empty", "passed": true, "detail": "none empty"},
    {"name": "feature_count_exact", "passed": true, "detail": "expected 1, got 1"},
    {"name": "geometry_types", "passed": true, "detail": "expected subset of ['MultiPolygon', 'Polygon'], got ['Polygon']"}
  ],
  "started_at": "2026-08-18T10:15:03Z",
  "finished_at": "2026-08-18T10:15:04Z"
}

The checksum and the timestamps are made up; everything else — the CRS decision, the transformation, every check name and detail — is copied from a record buffer_layer emits for exactly this call. The real file also carries output, repairs, notes and a critical flag on each check, left out here for length. tests/test_showcase.py validates this block against the specification's own validator and re-runs the operation to compare its crs_decisions keys with the emitted ones, because a record typed by hand drifts silently while every generated surface stays correct: it lacked spec_version for two releases, and on 2026-09-06 it was still recording a round trip without the x-mapsmith:round_trip key that says the coordinates came back. This is the record a third-party implementer copies.

Trimmed for the page, not for the file: the real record also carries the output's own path and hash, any geometry MapSmith had to repair, and the notes it made about how the inputs were handled — and every check says whether it was critical and, when it failed, what to do about it. get_provenance returns it for any output.

Why MapSmith