
LLM-native spatial middleware. Give an AI agent a map of any location on earth as a token-budgeted
LLM-native spatial middleware. Give an AI agent a map of any location on earth as a token-budgeted topological graph, with indoor floors, weather, and traffic.
·
mcp-name: io.github.Unselfisheologism/supercarto
LLM-native spatial middleware. Compiles geospatial data into token-budgeted topological graphs that an AI agent can reason over directly.
Give an agent a map without paying the token tax. One file in, both numbers
out: examples/synthetic-dense.geojson is 272,993 bytes (~68,000 tokens) raw
and compiles at a 1024-token budget to about 890 tokens - 26 nodes
(10 named) on 34 edges (streets plus access links), ~99% smaller.
Rerun it yourself: supercarto compile examples/synthetic-dense.geojson --budget 1024. Token counts are character-based estimates on a fixed test
file; the sun and timestamp lines shift them by a few tokens run to run.
npm install supercarto
pip install supercarto # Python client, talks MCP over stdioThis is the whole product:
import { SuperCarto } from 'supercarto';
const carto = new SuperCarto();
const result = await carto.maplet({
lat: 35.6833,
lon: 139.7620,
radiusM: 400,
budget: 1500,
});
console.log(result.yaml);The same file from the headline, compiled below (truncated output; warnings travel inside the map, where an agent reading only the map sees them):
map:
center: "37.7749, -122.4194"
source: geojson
note: Simplified for reasoning; call expand_feature for exact geometry.
nodes:
n530: {type: poi, name: Bank 0, tags: [bank]}
n531: {type: poi, name: Cafe 1, tags: [cafe]}
n673: {type: transit, name: Station 0, tags: [subway_entrance]}
edges:
n515->n516: {dist: 80m, dir: east, path: road}
n516->n517: {dist: 80m, dir: east, path: road}
omitted:
- {layer: building, count: 259}
- {layer: poi, count: 141}
- {layer: road, count: 441}
tools:
- expand_feature(id)That is about 890 tokens for the whole extract at a 1024 budget: every drop named by layer, nothing silently vanished.
You want an agent to know where things are and how to get between them. Three options, all bad:
supercarto takes the third option seriously and solves it the only way it can be solved: the model never reads the wire format.
coordinates live sources reasoning format
35.68, 139.76 ──▶ Overpass / PMTiles ──▶ topological YAML graph
distances in metres,
compass directions,
built for modelsThe wire format is a spec you own, optimized for machines. The reasoning format is standard YAML in flow style, using only constructs a model has read billions of times. A deterministic compiler in the middleware does the translation.
The person is standing outside. Rain and traffic change whether the trip happens at all, so those are first-class layers here, not an afterthought bolted onto a routing engine.
No API key. No account. No billing.
const w = await carto.weatherAt(35.6833, 139.7620, 12);
w.now.summary; // "heavy rain"
w.now.precipitation; // "rain" | "snow" | "sleet" | "hail" | "drizzle"
w.now.feelsLikeC; // what they actually feel$ supercarto weather --lat 35.6833 --lon 139.762
now clear night, 23.2C (feels 26.9C), wind 4.3km/h, precip none
2026-10-01T13:00:00Z 22.7C none 3.5km/h
2026-10-01T14:00:00Z 22.1C none 3.1km/hThe MCP tool returns prose rather than fields, because a model repeats "it is raining, take the bus" reliably and re-derives it from twelve numbers unreliably.
When the source is unreachable it returns NaN for every reading and sets
degraded, and the tool raises. It does not return zeroes. An agent handed
precipitationMm: 0 concludes the weather is dry and sends someone cycling into
a storm.
const t = await carto.routeWithTraffic({ from, to, mode: 'drive' });
t.freeFlowOnly; // true when no flow credential is configured
t.worstLevel; // "severe" - the segment that makes someone late
t.delayS;Traffic needs a credential, so get_traffic is absent from the tool list
until you set one. With no key the routing path reports free-flow and labels it:
$ supercarto traffic --from 37.7749,-122.4194 --to 37.7849,-122.4194
traffic: unknown (no flow source configured)
free-flow estimate: 244s, ignores congestion
note: set TOMTOM_API_KEY or HERE_API_KEY for live conditionsA free-flow estimate for a congested route is worse than no answer, because the person leaves on the schedule the agent gave them. Presenting one as live is the single most damaging thing this library could do, so it does not.
Set TOMTOM_API_KEY or HERE_API_KEY and it becomes live, reporting the worst
segment rather than an average.
Same keyless contract as weather, one pollutant further:
const a = await carto.airAt(35.6833, 139.7620, 12);
a.now.europeanAqi; // 62 - the raw index
a.now.pm25UgM3; // 28.1 - the fraction that sends asthmatics indoors
a.hourly; // forward-looking window, trimmed at "now"$ supercarto air --lat 35.6833 --lon 139.762
now air poor (AQI 62 EU, 65 US), PM2.5 28.1µg/m³, PM10 29.7µg/m³
gases above good range: NO2 63.5µg/m³
2026-10-27T08:00:00Z AQI 74 33.4µg/m³ PM2.5
2026-10-27T09:00:00Z AQI 55 21.2µg/m³ PM2.5The MCP answer names a gas only when it clears its own good bound on the
European scale, so a clean day costs four tokens instead of twelve. Every
answer carries the distance to the model's sample grid, because a metro with
one diesel corridor out of four is not one number. A missing gas reading
renders as unknown, never as 0: a zero invented from a gap is how a tool
certifies airspace as clean.
Nobody else publishes this. Google builds indoor maps for its own users and has no reason to hand a third-party agent a clean floor-by-floor graph; Mapbox has nothing comparable; every MCP wrapper returns the same flat GeoJSON.
indoor:
storeys: 0,1,2
multi_storey: true
0: {label: ground, rooms: 12}
L0n1: {type: corridor}
L0n2: {type: shop, name: "Blue Bottle"}
L0n1->L0n2: {dist: 11m}
v1: {type: lift, levels: [0,1,2], wheelchair: true}
missing: [1]Lifts are collapsed across storeys into one vertical link. Rooms only connect to
corridors on the same floor — an edge through a concrete slab would send
someone through a floor. A room more than 40m from any corridor is left
unattached, because a straight line through intervening walls is worse than no
edge. Untagged storeys are reported as missing rather than invented.
Set SUPERCARTO_GTFS to any static GTFS feed (an unzipped directory or a .zip)
and get_transit appears: stops, lines, and a service window for the queried
day. It is the one agent map tool that answers "can you be somewhere by 9"
from an actual schedule, and every agency's failure mode is covered by an
honest state rather than a guess:
transit:
center: "36.913, -116.77"
radius: 3.0km
feed: sample-feed
note: Stop distances are straight-line. Schedule from GTFS feed for 2007-01-11 in America/Los_Angeles.
nodes:
STAGECOACH: {type: stop, name: "Stagecoach Hotel & Casino", tags: [bus], routes: ["30", "40"], first: 06:00, last: 06:58}
NADAV: {type: stop, name: "North Ave / D Ave N", tags: [bus], routes: ["40"], first: 06:14, last: 06:44}
edges:
NADAV->DADAN: {dist: 601m, dir: south, path: bus 40}routes: [] — no transit is not no stops — and the note says so. A feed
without a calendar shows the whole network and says the service window is
unknown instead of presenting whole-feed data as today's schedule.25:10). Rendering
that as 01:10 fits the eye and misleads the decision, so it renders as
recorded, in the feed's own timezone.SUPERCARTO_GTFS_RT
to the agency's TripUpdates URL and predictions join onto the schedule:
node lines gain a live: attribute such as bus 16 +300s or
bus 16 cancelled, and the note says how fresh the feed is. Spec
precedence holds — an explicit stop update beats the trip-level delay;
absolute-time predictions convert through the feed's timezone. The
honesty rule that matters most: a stop with no live entry is unknown,
not on time, and the note says so in words. A feed that will not read
(404, timeout, malformed data) degrades to the pure schedule answer with
a one-sentence explanation, never a silent drop.next: attribute on
each node lists the upcoming departures at that stop, in feed time order
and in the feed's clock (tram 9 25:10 stays past midnight), capped at
three with the hidden rest counted (+2 more). With a realtime feed
configured the board speaks the prediction inline — bus 16 07:05 +300s
or cancelled — and the live: list omits anything the board already
said, so nothing prints twice. When the day's last departure has run, the
note says the day is over instead of letting an empty board read as a
broken feed.get_transit_route
walks to a stop, rides one line that serves both catchments, and walks it
off — all straight-line legs labelled as such, never an interchange the
feed cannot prove. Plans ride on the departure board's honesty: certified
against the service day, predictions decorate their trips, cancelled
trips drop out with a counted note, and when nothing can be certified
the note names the leg that failed.note, where a model reading only the map
sees them.Most map-for-agents code truncates and hopes. supercarto treats truncation as a correctness problem:
emitAndVerify re-measures the actual emitted YAML and cuts
again until it fits. The reported budget is the budget delivered, not an
estimate.omitted:, aggregated per layer, so
the model can tell "not there" from "not shown".Lives in its own repo now: supercarto-bench.
Same question, same model, same map — the only variable is what sits in the context window: compiled graph vs raw GeoJSON vs nothing. Raw runs, frozen test maps, and the scoring code all live there, so anyone building a rival map tool can run the same test and try to beat the score.
Current headline there: 9/9 for the compact graph against ~4/9 raw and 0/9
with no map, on two AI models. Route questions are unmeasurable (the public
test router gives impossible answers) — so route is demoted to a
feasibility answer: straight-line distance, compass direction, then
"verify the approach on arrival". Turn-by-turn requires a router you host and
have verified; OSRM is opt-in, not default. Stated, not hidden.
The score now ships with its own reproduction recipe (scoreC certificate,
re-derived from raw answer archives without model calls), a per-model
leaderboard, and adapter arms: a rival tool registers itself with a single
{ name, prepare } module and gets the same tasks, models and pass rules.
The current certificate: supercarto 38/47 · geojson 15/44 · none 0/47
across every archived run.
What this repo keeps is a quick token-cost check:
npx supercarto bench <file.geojson>| Source | Status | Use |
|---|---|---|
| Overpass | default | Development. 15-40s per call, rate limited. |
| PMTiles / Protomaps | SUPERCARTO_PMTILES | Production. Range requests against object storage, milliseconds, no rate limit. |
| OSRM | default | Turn-by-turn routing, walk/bike/drive. |
| Open-Meteo | default | Weather. No key. |
| TomTom / HERE | key required | Live traffic. |
| Terrarium tiles | default | Elevation and slope. No key. |
| GTFS feeds | SUPERCARTO_GTFS | Transit stops, lines, and schedules. Any static feed, no key. Live delays join from a GTFS-Realtime TripUpdates URL via SUPERCARTO_GTFS_RT. |
export SUPERCARTO_PMTILES=https://your-bucket/planet.pmtilesPMTiles is the answer at production volume. The reader is included — no pmtiles
dependency, no mapbox-gl, zero transitive packages.
Everything is read from the environment by one factory, so the CLI and the MCP server cannot disagree about where data came from. They did once, and nothing reported it.
SUPERCARTO_PMTILES PMTiles archive URL; primary source when set
OVERPASS_ENDPOINT your own Overpass instance
TERRARIUM_ENDPOINT elevation tile template
TOMTOM_API_KEY enables get_traffic
HERE_API_KEY enables get_traffic
SUPERCARTO_NO_TERRAIN disable elevation
SUPERCARTO_NO_WEATHER disable weather
SUPERCARTO_GTFS path to a GTFS feed (dir or .zip); enables get_transit
SUPERCARTO_GTFS_RT TripUpdates URL; adds live delay lines to get_transitsupercarto never ships keys. You configure every source with your own credentials, so every upstream relationship — Open-Meteo, TomTom, HERE, a transit agency's feed — is a direct one between you and the provider:
get_traffic is
absent from tools/list until TOMTOM_API_KEY or HERE_API_KEY is set,
and a free-flow estimate always says "free flow" in its own output. A
congestion-free answer presented as live is the one failure this library
refuses on principle.SUPERCARTO_GTFS; the note lines name it, its timezone, and its service
date. Some agencies license their feeds with agency-specific terms — check
the feed you import before a commercial deployment.X-Data-Attribution: © OpenStreetMap contributors (ODbL) and an attribution field in the JSON body, and
MCP map answers carry the same line in a comment. The compiled document
itself is untouched — the attribution costs tokens at transport level only.Nothing abhors a key like a self-hosted install, and nothing is attributed except what was actually fetched: arithmetic carries no line, and a custom weather or air source is named by its own name rather than handed a licence it did not grant.
Whole-metro feeds load entirely into memory. Since 0.6.1 the load is
columnar — stop_times go straight into per-trip arrays, no row objects — so
a feed the size of Translink SEQ (35 MB zip) fits Node's default heap and
the answer is byte-identical to the pre-0.6.1 build. Verified live at that
size: schedule, departure boards, and 750+ realtime predictions join in one
answer with no NODE_OPTIONS at all. Bigger feeds load in proportion to
their own inflated size; give such a run NODE_OPTIONS=--max-old-space-size=4096.
Every release ships supercarto-X.Y.Z.mcpb — an MCPB bundle:
download it from the latest release,
open it with Claude Desktop, and the maps tools install with one click.
Optional install-time configuration: an Open-Meteo key for higher weather
limits, and a local GTFS feed path (plus the operator's TripUpdates URL) for
the transit tools. Node ≥ 18 is the only requirement; the bundle carries the
server, which has zero npm dependencies, so it is half a megabyte.
{
"mcpServers": {
"supercarto": { "command": "npx", "args": ["supercarto", "mcp"] }
}
}Eight tools: get_maplet, route, search_places, expand_feature,
get_daylight, get_terrain, get_weather, get_air, plus get_traffic
when a key is present, get_transit and get_transit_route when a GTFS
feed is configured. Each maplet lists exactly the tools that deployment can
answer, so an agent never calls one that cannot work. get_daylight is
always available: sun position is arithmetic, needing no source and no
credential. get_weather and get_air are keyless by default: an agent
never tells someone it is safe to go out without knowing rain or air first.
Beyond topology and distance, a node can carry the facts that decide whether a trip is worth making:
n3: {type: poi, name: Blue Bottle, tags: [cafe], hours: 07:00-18:00, brand: Blue Bottle}
n4: {type: poi, name: Central Rx, tags: [pharmacy], hours: 09:00-17:00}
map:
sun: up, elevation: 43.4deg, twilight: day, azimuth: 22deg, sunrise: "..."Both shops above are open at 12:00 local. At 04:00 the same two read
hours: closed, because their hours are known and they are shut. A bench with
no recorded hours emits no hours field at all.
hours is evaluated against an instant and evaluated in the map's timezone,
not the server's. Three states, never two: a time range, closed, or absent
because nobody recorded it. Absent is deliberately not closed — those lead to
opposite advice, one means go and find out, the other means go elsewhere.
twilight is day, civil, nautical, or night rather than a boolean,
because the three lead to different decisions: walking is fine at civil
twilight and unwise at nautical. Above the Arctic circles in summer and winter
the map reports polar: day or polar: night instead of inventing a sunrise.
Pass compile.utcOffsetMinutes and compile.now to fix both to a known place
and instant, which is what the tests do.
import asyncio
from supercarto import SuperCarto
async def main():
async with SuperCarto() as carto:
m = await carto.maplet(lat=35.6833, lon=139.7620, radius_m=400, budget=1500)
print(m.yaml)
w = await carto.weather(lat=35.6833, lon=139.7620)
asyncio.run(main())Zero runtime dependencies. It speaks JSON-RPC to the Node server over stdio
rather than importing an SDK, because the mcp package pulls in httpx and
pydantic and an agent framework that already depends on one of them should not
get a second copy.
curl 'localhost:8787/maplet?lat=35.6833&lon=139.762&radiusM=400&budget=1500&format=yaml'The compile path is Workers-compatible (fetch-based sources, no Node built-ins),
and cloud/worker/ packages it as a Cloudflare Worker: the same /maplet,
/scr, weather, daylight and terrain surface as the local HTTP API above, with
per-IP rate limiting and ODbL attribution on every map response. It is
deliberately a subset — transit and traffic are not served, because a Worker has
no filesystem for a GTFS feed and hosted mode ships no flow-provider keys, and
GET / states that openly. See cloud/worker/README.md.
Deployed at https://supercarto-compile.jeffrinjames99.workers.dev. Data source
chain for /maplet and /scr: live Overpass first, then a hosted PMTiles
planet build of the OpenStreetMap basemap — every known public Overpass
instance refuses the shared Cloudflare egress range (HTTP 521), so the
fallback is what actually serves a hosted maplet. The archive's detail level
is coarse beyond z10-ish, and the deployment caps a request's tile and
feature fetches so a planet tile stays inside a Worker CPU budget;
truncation travels in the document as warnings, and the source: line says
protomaps when the fallback served it. Weather, daylight and rate limiting
are live; terrain answers an honest 503 (Terrarium tiles are PNG-encoded and
the bundled zero-dependency decoder reads raw Terrarium buffers only); transit
and traffic are absent for the reasons GET / lists. GET /healthz probes
Overpass only, so a 503 there means the Overpass leg is unreachable — not that
the PMTiles fallback is down.
supercarto fetch --lat 35.6833 --lon 139.762 --radiusM 400 --budget 1500 --metrics
supercarto weather --lat 35.6833 --lon 139.762 --hours 12
supercarto traffic --from 37.7749,-122.4194 --to 37.7849,-122.4194
supercarto transit --feed city-gtfs.zip --lat 36.913 --lon -116.77 --radiusM 3000
supercarto route --from 37.7749,-122.4194 --to 37.7849,-122.4194 --mode walk
supercarto mcp
supercarto serve --port 8787
supercarto compile city.geojson --budget 1024 --metrics
supercarto encode city.geojson --out city.scr
supercarto decode city.scr
supercarto bench city.geojsonfetch layers accept road and poi alongside raw OSM tags; anything
else is rejected rather than silently returning nothing. A request that
would yield named places with no streets fails with a clear error instead
of a misleading map — pass --layers poi for a POI-only map. Warnings
travel inside the map output, not just stderr, so agents see them.
Distances are verified against haversine ground truth at mid and high latitude:
This required getting the Web Mercator scale correction right: mercator distances
exceed ground distance by 1/cos(latitude) on both axes, and getting the sign
wrong produces a 26% error at mid latitude that compounds toward the poles. A
mean isotropic scale is also wrong for a non-square bbox, so the scale is applied
per axis.
The benchmark task set spans 64°N to 33°S deliberately. A benchmark run only at 37°N measures one case and hides every sign error toward the poles.
461 tests passing: 328 unit (including 42 for the GTFS transit layer, 14 for the protobuf wire and TripUpdates schema, 5 for the real-time overlay join, and 7 for the PNG elevation decoder), 121 against live sources, and 12 MCP end-to-end. Outputs are byte-identical to the Python port - the parity engine runs on every push. Verified against live OpenStreetMap, live Open-Meteo, and the live MCP server driven from Python.
Implemented: SCR codec (text and binary, delta geometry, ring groups, three heat encodings, omissions, routes, refs), Web Mercator with per-axis scale correction, Visvalingam-Whyatt simplification, GeoJSON ingestion with OSM classification, topology compilation with junction welding and landmark attachment, token budgeting with connectivity guarantees, YAML emission, indoor floor graphs with vertical circulation, place-density heatmaps, live Overpass, PMTiles with a built-in MVT decoder, routing demoted to feasibility (straight-line distance and direction by default; OSRM turn-by-turn is opt-in for an engine you have verified — the public demo router returns impossible distances), keyless weather with a degraded path that refuses to invent readings, traffic with an honest free-flow fallback, terrain elevation and slope, GTFS transit schedules with three honest service states, GTFS-Realtime trip updates joined onto those schedules with unknown-not-on-time semantics, MCP over stdio, HTTP API, CLI, a Python client, and a task-level benchmark with OSRM ground truth.
Not implemented: hosted vector tiles with style delivery, and full indoor room geometry beyond centroids.
Apache-2.0
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add supercarto -- npx supercarto mcp{
"mcpServers": {
"supercarto": {
"args": [
"supercarto",
"mcp"
],
"command": "npx"
}
}
}code --add-mcp '{"name":"supercarto","args":["supercarto","mcp"],"command":"npx"}'[mcp_servers.supercarto]
command = "npx"
args = ["supercarto", "mcp"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/supercarto to learn what the "supercarto" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
npx supercarto bench <file.geojson>pip install supercarto| Name | What it does |
|---|---|
get_maplet | Fetch real map data around a coordinate and return a token-budgeted topological graph: named places joined by walkable edges with distances in metres and compass directions. Use this to answer 'what i |
localize | Move within a map session you already hold. Pass the session SCR (from get_maplet with returnScr, or from the last localize) and your new position; the answer is only the delta: + places that entered |
route | Feasibility between two coordinates: straight-line distance, the compass direction to head, and nothing that pretends to be turn-by-turn navigation. Turn-by-turn comes only from a routing engine the o |
search_places | Find named places (cafes, stations, shops) near a coordinate. Cheaper than get_maplet when only names are needed. |
expand_feature | Fetch the exact geometry of features by id, as WKT. Use only when shape matters, such as checking whether a route clears a building. |
get_terrain | Sample ground elevation around a coordinate, in metres. Returns the range plus high and low points, which is what an agent needs for grade reasoning. |
get_weather | Current weather conditions and a short forecast at a coordinate. Use this before telling someone to walk, cycle, or drive, or to pick between an indoor and outdoor option. Reports what is actually fal |
get_air | Air quality at a coordinate: European and US AQI bands, particulate load, and the forecast window. Use this before sending someone into prolonged outdoor exertion, or before recommending a walking rou |
get_daylight | Sun position, sunrise, sunset, and twilight state for a coordinate. Twilight is reported as day, civil, nautical, or night rather than a boolean, because "needs a torch" and "cannot see" are different |
Read live from the server on November 5, 2026.
Paste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/supercarto)Nothing comparable is listed yet.
v0.7.00.7.0 — air quality joins the honest decision setRelease notesv0.6.20.6.2 — one-click install in Claude Desktop (MCPB bundle)Release notesv0.6.10.6.1 — whole-metro feeds inside the default heapRelease notesv0.6.00.6.0 — registry marker in plain textRelease notesv0.5.90.5.9 — official MCP Registry metadataRelease notesv0.5.80.5.8 — HTTP parity for the transit surfacesRelease notesv0.5.70.5.7 — The certified ride planRelease notesv0.5.60.5.6 — drive the realtime join from every entry pointRelease notesv0.5.50.5.5 — The next-departure boardRelease notesv0.5.40.5.4 — GTFS-Realtime: live delays join onto the scheduleRelease notesv0.5.30.5.3 — real elevation: /terrain decodes PNG Terrarium tilesRelease notesv0.5.20.5.2 — PMTiles reads real archives at the true latitudeRelease notesv0.5.10.5.1 — the budget kept its promiseRelease notesv0.5.00.5.0 — GTFS transit schedules for agentsRelease notesv0.4.110.4.11Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "supercarto" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.