MapSmith MCP Server

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.

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 twenty-three traps with answers computed on paper and has already sent three 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.3.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.

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:

{
  "mapsmith_version": "0.3.0",
  "operation": "buffer_layer",
  "parameters": {"distance_meters": 300.0},
  "inputs": [{"path": "rivers.gpkg", "sha256": "9f2c…", "crs": "EPSG:4326"}],
  "crs_decisions": {"analysis_crs": "EPSG:32632", "reason": "estimated UTM zone for metric buffering"},
  "engine": {"name": "geopandas", "version": "1.0.1"},
  "started_at": "2026-08-18T10:15:03Z",
  "finished_at": "2026-08-18T10:15:04Z"
}

The full manifest also carries the verification checks that ran, and any geometry MapSmith had to repair. get_provenance returns it for any output.

Why MapSmith

• Real geoprocessing, not map CRUD. Built on the proven open geospatial stack: GDAL, GeoPandas, Shapely, DuckDB Spatial, Whitebox Workflows and exactextract ship today (more to come: QGIS Processing via sidecar).
• Provenance by design. Every layer MapSmith produces ships with a machine-readable lineage manifest — source datasets with checksums, tools executed, exact parameters, CRS decisions, software versions, timestamps. Everything needed to re-run the analysis without the LLM is in there. No AI slop.
• The engines compute, the model orchestrates. Geometry and numbers only ever come from deterministic tool executions — never from model output.
• Semantic tools, not a tool dump — and a catalog built for thousands. 28 goal-level tools plus a searchable operation catalog, because tool-selection accuracy degrades once a few dozen tools are exposed at once, and fastest when two of them apply to the same input. Capability count has no such ceiling, so capability lives in the catalog. Search narrows it on what you declare and then hands over what survives rather than ranking it for you, because measurement said ranking is the wrong verb — see Finding the right operation.
• Model-agnostic infrastructure. Claude, GPT, Qwen, Kimi, GLM — anything that speaks MCP, cloud or local. The leverage is better contracts (typed plans, actionable error codes, a searchable catalog), not weights we would have to maintain. See the manifesto.

Tools

Finding the right operation

Those are the tools an agent chooses between. Behind them the catalog holds every operation MapSmith can perform — 71 today, and 46 of them have no tool of their own — and it is built to hold thousands: tool-selection accuracy degrades past a few dozen exposed tools, while capability count has no such ceiling. That makes reaching scale a retrieval problem, so it is treated as one — and measured like one.

First it narrows, deterministically, on things the caller already knows. Every entry declares what data it takes (vector, raster, dataset, plan, none), what it hands back (dataset:vector, dataset:raster, answer, description), whether it demands a projected CRS, and which family it belongs to.

Measured over 118 answerable requests written by two other model families from job scenarios — a hydrologist with a flood report, a surveyor arguing with a field measurement — neither of which was shown this catalog, because a model handed the entry writes a paraphrase of the entry:

Two ranking columns, and that is a correction. This table used to carry one, computed with the default engine — which is the embedding one where its model loads and BM25 where it does not. So the published figures were a measurement of what the machine could download, and a CI run that met a 429 from Hugging Face recomputed the first row as 28% where this page said 18%. Not a flaky test: a number that had never been reproducible on a machine without the model, published under a sentence promising it could be checked.

The two also differ in a way worth seeing. BM25 is the better ranker while the candidate set is large — an exact term either matches or does not — and the embedding engine only overtakes it once the facets have narrowed, which is where near neighbours have to be told apart by meaning rather than by words.

The last column is not an accuracy figure — it is a property, and the 97% rather than 100% is worth a sentence. The narrowing never drops the right operation: that is asserted per entry and holds for all 71. What the column measures is whether the surviving set was small enough to hand over WHOLE, and for a handful of requests it still is not, so those fall back to a ranked shortlist and the answer can be outside the top three. Ranking decides the order; it does not decide membership; and the 3% is the gap between "cannot lose the answer" and "can show you all of it".

The third row is the scaling wall, and we hit it in one afternoon. On 2026-08-29 the catalogue went from 51 operations to 61. Two rows of that table got worse: the commonest surviving set went from 26 candidates to 34, past the point where the whole set can be handed over, and delivered fell from 100% to 45% while found@3 fell from 48% to 36%. Adding capability had made discovery worse — the failure this page had predicted at eight hundred operations and met at sixty-one.

Raising the threshold would have postponed it by about ten operations. What fixed it is the fourth row: how many datasets you are holding. That is a fact about your situation — one layer or two — not a guess about our vocabulary, it is derivable from each operation's own signature so a test can check the declaration against the code, and it takes the median surviving set from 34 to 9. The catalogue grew by a fifth and discovery got better, but only because a facet arrived with it. That is the trade this design makes, stated rather than discovered later.

It happened again the next day, and this is what watching a curve is for. On 2026-08-30 the catalogue went from 61 operations to 71. Every ranking figure in that table fell — 28% to 25% bare, 34% to 28% on the input kind — and the delivered column of the second row fell from 48% to 28%, because more requests now leave a set too large to hand over whole. The bottom row did not move: 97%, the same as at 61 and at 51. Ten more operations, no new facet, and the guarantee held, which is the first time growth has been absorbed by the facets already there.

That is the shape of the trade, and it says when the next facet is due. The figure to watch is not found@3 — a ranker will always get worse as the catalogue grows, and it is a hint. It is the median surviving set at the fullest declaration: 9 at 51 operations, 14 at 61, 16 at 71. When that crosses 30, delivery stops being a property and starts being a ranking again, and the answer is another fact the caller already knows, not a bigger threshold.

The requests, both labels and the harness are all in the repository: tests/data/discovery_queries.json and benchmarks/discovery_report.py, which recomputes every number above from those files with no network and no model — so they can be checked rather than believed, and tests/test_discovery_report.py fails if this page and the harness disagree. The one exception is the 69%: reproducing that needs the model that did the choosing, and the report says so where it stops.

So it hands over the set instead of picking for you. Below thirty survivors list_operations answers with status: "choose": every candidate, ordered as a hint that says it is a hint, each carrying the sentence that separates it from its neighbours. The threshold is 30 because the surviving set over those 118 requests has a median of 26 and never exceeded it; the payload is about 2,100 tokens, less than one wrong operation costs to run and undo.

Three measurements say this is the right shape, and the third is the one that settles it:

All three are over the same 118 requests, which matters: agreement measured over all 155 requests in the file is 68%, and the difference is the 21 pairs where both labellers agreed a request was unanswerable — true, and the easy half. Quoting that 68% beside a 48% computed over the 118 would be comparing two populations, which this table did for half a day.

The last row is a ceiling, not a baseline, and the second row sits at it rather than below it. When two competent labellers disagree three times in ten about which operation answers a request, "the right one" is not a single value to rank toward, and a system scoring above that is fitting one annotator rather than getting better. Two GIS analysts with thirty years each do the same job with different tools and neither is wrong.

That is why the answer is a set and why its reason field says, in words, that the order is a hint and that two defensible candidates are a question for the person who made the request. The caller — an agent with the conversation in context — knows things no ranking can. Where it does not, the human does.

The remaining honesty: the ceiling was measured between two language models. Whether human GIS analysts agree with each other more, less, or about the same is unmeasured, and until it is, these numbers are reported as agreement with model-written labels and never as accuracy.

The family is the one facet that orders instead of filtering, and that is a correction. It used to be a hard filter like the others. It is not like the others: input kind and projected-CRS are facts about the data in hand and output kind is what the caller wants, but family is a guess about our taxonomy, which the caller cannot see. Measured, it removed six candidates out of twenty-one — and when the guess was wrong it removed the right operation, with no error, leaving a confident answer assembled from neighbours. Every request in the independent set has 4.4 plausible families. That is the silent-failure class Argleton measures in other people's systems, sitting in our own discovery layer, so it now sorts: declaring the family lifts it to the front and costs positions when wrong, never the answer. The hard cut stays available on catalog.applicable, where asking for it means it.

We do not need a model to extract those facets, because the caller is one. An MCP client is an LLM with the context we lack — it knows what file it is holding and what it is trying to produce. So list_operations asks for them in its schema, and its description leads with why. This is the same shape as LlamaIndex's Auto-Retrieval or LangChain's Self-Querying, minus the model those have to host: here it is already on the other end of the protocol. A geographic raster is never offered slope, because slope refuses one — a property of the data, checked in code, no model in the loop.

Then it ranks, with two engines that both always run. list_operations takes engine: auto (the default), lexical, or vector. Every result carries the engine that produced it, because a BM25 score of 10.03 and a cosine of 0.38 are not on the same scale.

The default was lexical until the measurement said otherwise, and the measurement is the interesting part. Golden queries written by whoever wrote the catalog share its vocabulary, so they test word overlap dressed as retrieval: on those, BM25 scores 100% found@1 and embeddings 60%. Re-phrased the way somebody with a problem actually phrases it — "the coastline is 400000 nodes and the browser dies" rather than "simplify the geometry" — the finding reverses and both engines degrade as the catalog grows:

BM25 degrades faster and the gap widens with every entry, which is why the embedding engine is a dependency rather than an extra. The whole curve is a test (test_retrieval_degradation.py), so growing the catalog cannot quietly make it harder to find anything.

And that finding does not survive being scaled up — measured the same day it was published. The distractors above are drawn from our own fifty-one entries, which are semantically spread out. Growing this catalog means adding near neighbours: hundreds of raster and terrain operations that resemble each other. Re-run against 800 real GIS operations, taken from a library that ships them with their own descriptions, the ranking reverses and the embedding engine degrades faster:

Embeddings blur near neighbours; an exact term either matches or does not. The two measurements answer different questions and both are kept: which engine suits the catalog we have (the embedding one, and it is the default), and which survives the catalog we plan (neither). At 800 entries the better engine is wrong two times in three, so scale will not be bought by choosing a better ranker. test_retrieval_at_scale.py keeps the projection under measurement rather than under opinion.

And the narrowing does not scale on its own either — this page claimed otherwise and was wrong. It said the facets leave sixteen candidates at 800 operations just as they do at 200. The sixteen is real and it is produced almost entirely by family: those 803 operations are all raster-in, raster-out, so input kind and output kind cut nothing at all, and only the taxonomy does — a choice among 43 families that the caller has to guess. Which is exactly the facet that must not filter.

So the open problem has a sharper shape than "ranking is hard". What is needed at a thousand operations is more facts a caller can state without knowing our taxonomy — how many inputs an operation takes, whether it changes geometry or only attributes, whether the output has the same number of features as the input. Those are structural properties of the operation, they are checkable against the code rather than declared by hand, and they separate the pairs a bag of words cannot: spatial_join from overlay_layers, flow_accumulation from extract_streams. That work is not done, and until it is, the honest claim is the measured one: the guarantee above holds at fifty-one operations, not at eight hundred.

How an entry has to be written is a published specification, not a convention: docs/catalog-entry-spec.md, with a normative JSON Schema that every entry validates against in CI. Each field is there because a measurement said so — including the two that measured to nothing and are documented as such, because a spec that only reports what worked is an advertisement.

And discoverability is a contract per operation, not an average. A catalog-wide 90% found@3 over fifty entries means five are invisible and the average will not say which. So every available entry is probed with its own first worked example, with its own facets declared (test_discovery_contract.py, parameterised over the catalog, so a new operation is under contract the moment it is added). Two things are required of it: the facets the entry declares must never drop that entry, and the entry must reach the caller.

Its rank is no longer one of them, and removing that is the point. The contract used to demand the top three. That looks like a discovery contract and is a ranking contract, with one bad property: the only way to repair a failure is to reword the entry until the ranker likes it. Fifty entries tuned that way score nineteen points better on examples we wrote than on requests written by anyone else — that gap is measured, and it is where a published 70% on this page turned into 51% overnight. A test whose repair procedure is fit the text to the scorer manufactures the number it reports. What remains under contract is the part that is deterministic and ours; rank inside the delivered set is still measured, and no longer fails a build.

The old form still earned its place the first time it ran. centroid_layer advertised “label points for a polygon layer” and ranked below point_on_surface. The ranking was right: a centroid can fall outside its own polygon, which is Argleton trap 014 — our catalog was recommending the defect our own suite measures. The example changed, not the score.

And when the two engines agree on nothing, the search says so instead of answering. This is the failure that measurement turned up in our own product: asked "send an email to my accountant", the embedding engine returned idw_interpolation with the same confidence as a real answer — a silent error in the layer whose job is to prevent them. A similarity threshold does not fix it, because there is no line to draw: "convert this mp4 to a gif" scores above sixteen of twenty genuine queries. What does separate them is the two rankers landing on nothing in common — mean top-3 overlap 0.90 of 3 when an answer exists, 0.18 when it does not. So a query the catalog cannot place comes back as status: "unsure", carrying both engines' guesses and the question that narrows the catalog deterministically: what kind of data do you have. It fires on 9 of 11 unanswerable queries and suppresses 1 correct answer in 20.

And when the facets leave nothing at all, it says which declaration did it. Zero candidates used to fall through the branch above and come back as "0 operations survive, which is few enough to read" — prose that means nothing and, worse, an empty candidate list, which an agent reads as MapSmith cannot do this. It was found by the discovery log below on its first real session: "how much land is in each of these parcels" with produces="answer" left nothing, while measure_area computes exactly that and declares dataset:vector because it writes the areas into a column. So that case is now its own answer — each declaration with the number of operations that would survive without it, smallest first — and it is arithmetic, not ranking.

Below the choose threshold it stops refusing and becomes a warning instead — order_is_weak on the delivered set. Refusing made sense while the search was deciding; handing over every candidate is not deciding, so the disagreement reverts to being evidence about the order, which is the only thing it was ever evidence about.

The applicability filter above runs first for both engines — otherwise the guarantee would only be true of one of them, and there is a test that says so.

Then it runs, tool or no tool. Most catalog operations have a tool of their own; the newer ones increasingly do not, and run_operation(operation, arguments) runs those by name. This is deliberate: capability count has no ceiling, but the exposed tool list has one, so the catalog is allowed to grow faster than the tool list. Arguments are checked against the catalog before anything executes — unknown operation (with a "did you mean", from the same ranking), missing or misnamed argument, wrong type, path outside the workspace — and every error carries a stable code. Execution goes through the same path as execute_plan, so an operation cannot behave one way alone and another way inside a plan.

Both engines embed the identical document text (catalog.document_text), so a comparison between them measures the ranking and nothing else. Three test files keep the rest under measurement rather than under opinion: the degradation curve over our own catalog, the projection against 800 real neighbouring operations, and a discoverability contract per entry. That is what turns the scaling limit into a curve you can watch rather than a number someone guessed.

Determinism is the reason for building it this way rather than reaching for a hosted embedding API: that would make tool discovery a network call whose answer can change under you, and an agent that finds a different tool tomorrow for the same question is not reproducible, whatever its manifest says. The one network access left is the model download on first use, at the pinned revision; after that the vector engine is local, and an install that never makes it keeps BM25, and the engine field of every result says which one answered.

Making it better with your own requests, without a model that drifts

The 155 requests behind those percentages were written by two language models. They are the best set we could build without users, and they are not what users ask: a real request names the file somebody actually has and the words their field actually uses.

So MapSmith can record its own. Set MAPSMITH_DISCOVERY_LOG to a file path and each search is written as one JSON line together with the operation that was run after it — the query, the facets declared, which engine ranked it, every candidate delivered, and where in that list the chosen one sat:

MAPSMITH_DISCOVERY_LOG=/data/discovery.jsonl   # then work normally for a while
python benchmarks/log_to_cases.py /data/discovery.jsonl

For the part that needs eyes rather than a pipe, there is a dashboard — see below.

log_to_cases.py prints those lines as rows shaped like tests/data/discovery_queries.json and flags the two that matter: a run the ranking did not put first (the answer was on screen and the order was wrong) and a search nothing followed (a request the catalog did not serve). It prints; it never writes. Which rows become test cases is a person's call.

None of this trains anything, and that is the design. A ranker that learns from what callers pick learns from an ordering it produced: the operation shown first gets picked more, gets learned as correct, gets ranked first harder — a confident answer nothing contradicts, which is the exact failure this product exists to measure. The model revision stays pinned, held there by a golden-vector test, so the same query gets the same answer next year. What improves instead is the catalog text — a phrasing, a distinguishes that does not distinguish — as a diff somebody can read and revert. That loop is not the weak option: it is what took found@3 from 18% to 57% and delivery to 97%.

The log is off unless the variable is set, holds queries and operation names and nothing else (no dataset paths, no arguments), is guarded by MAPSMITH_WORKSPACE like any other path MapSmith writes, and never leaves the machine — nothing reads it back. Your queries describe your work; treat the file that way, and delete it when you are done.

One question, end to end

Everything above is about one step. Here is a whole question — six parcels, a river, an elevation grid, and five operations picked out of fifty-one — with the search, the arguments and the verification of each step as they were actually recorded.

Nothing in this section is drawn. benchmarks/worked_example.py builds fixtures whose answer can be worked out on paper, asks the catalogue in the words of the problem, validates and runs the plan, reads the manifests, and writes what follows; tests/test_worked_example.py fails if this page and that script disagree. The position column is BM25's rather than the default engine's, because a published figure should not depend on whether a model download succeeded on the machine that built the page — the narrowing, which is the point, is identical on both. Two things worth watching: the middle column, where the catalogue goes from fifty-one operations to a handful the caller can read; and the CRS column, where every metric operation says which coordinate system it moved the data into and why.

flowchart TB
  ASK["<b>Parcels within 1.5 km of the river whose ground sits below 120 m, with the elevation and the ground area of each</b>"]
  ASK --> PLAN{{"plan validated<br/>before anything runs"}}
  PLAN -. "rejected: FORWARD_REFERENCE" .-> BAD["'mask_path' references '$buffer' which runs later — move step 'buffer' before 'near'"]
  BAD:::bad
  BUFFER["<b>buffer_layer</b><br/>71 operations &rarr; 27 candidates &rarr; chosen<br/>CRS EPSG:32610<br/>9/9 checks"]
  PLAN --> BUFFER
  NEAR["<b>clip_layer</b><br/>71 operations &rarr; 14 candidates &rarr; chosen<br/>12/12 checks"]
  BUFFER --> NEAR
  HEIGHT["<b>zonal_statistics</b><br/>71 operations &rarr; 4 candidates &rarr; chosen<br/>CRS EPSG:4326<br/>7/7 checks"]
  NEAR --> HEIGHT
  AREA["<b>measure_area</b><br/>71 operations &rarr; 27 candidates &rarr; chosen<br/>CRS WGS 84 &#40;ellipsoidal&#41;<br/>9/9 checks"]
  HEIGHT --> AREA
  FILTER["<b>run_sql</b><br/>71 operations &rarr; 38 candidates &rarr; chosen<br/>outside the plan"]
  AREA --> FILTER
  OUT[["3 parcels, each with elevation and ground area"]]
  FILTER --> OUT
  classDef bad stroke-dasharray: 4 3

One step runs outside the plan — run_sql, 4 rows in and 3 out — and the reason is a boundary rather than a gap: $step references resolve only in arguments declared as dataset inputs; run_sql takes its inputs inside a SQL string, so it cannot join the plan's dataflow. Deliberate: substituting into arbitrary strings would let a planner assemble a path out of text.

The answer, which can be worked out on paper before MapSmith sees the files: the parcels are squares of 0.0015° at 46.2°N, so each is about 119 m by 167 m, and the elevation ramps west to east across the fixture.

The rejected plan is the honest half. Steps in the wrong order are the dominant failure class in the agent benchmark, so the example includes one and shows what the validator says about it, before any file is touched. It earned that place while this was being written: the first version of the plan passed distance_m where the operation declares distance_meters, and the validator named the argument and listed the three it accepts.

Formats

GeoParquet 2.0 moves geometry into Parquet's own logical types and makes the geo key optional, so "a Parquet file with geometry in it" no longer implies that key. MapSmith reads the CRS from the logical type when it is the only place it exists — the spec default, an authority string, projjson:<key>, or the whole PROJJSON document inline, which is what DuckDB writes. run_sql emits both layers (geoparquet_version 'BOTH'), so one output file satisfies a 2.0-native reader and a GeoPandas 1.x one; the GeoPandas writer path stays 1.x because GeoPandas 1.1 caps schema_version there.

One declaration is deliberately refused rather than guessed: srid:<n>. The spec defines it as a numeric identifier and names no authority — its own example is srid:0 — so reading it as EPSG:<n> would be inventing a coordinate system and recording it as fact.

Verification, in and out

Every tool that writes a dataset also writes <output>.provenance.json beside it and verifies its own work — CRS agreement, geometry validity, raster dimensions, count and extent invariants — recording the results in the manifest before raising anything, so the audit trail survives the error.

Verification runs on the way in as well. Before an operation touches your data, MapSmith checks the failures that produce plausible junk: an input with no CRS is refused outright, because metric maths on unknown units is how a confidently wrong answer gets made; an empty input, or two layers whose extents cannot possibly overlap, comes back as a named warning with a hint — in the tool result, not only in the manifest, so the agent sees it instead of assuming success. (The join fast paths, DuckDB and SedonaDB, only ever receive inputs that already share a known CRS; they verify their output and diagnose an empty join.)

Documentation truncated — see the full README on GitHub.