@maproll/mcp
Let an AI assistant make real maps. Every map comes back as a maproll URL — permanent, embeddable, and the handle for the next change.
[World choropleth of coffee consumption per capita, made through the maproll MCP server]
That image is not a file in this repository. It is a maproll URL rendering live, which is the whole idea: the URL is the map.
Install
Any other client takes the same command as config — Claude Desktop, Cursor
(.cursor/mcp.json), VS Code (.vscode/mcp.json under "servers"):
Needs Node 20 or newer. No API key, no signup, no account — the server runs
from npm on demand and talks to the public render API.
Try it
Ask your assistant, in these words or your own:
Map coffee consumption per capita for the ten biggest drinkers.
Highlight the EU member states on a light map.
Draw the sea route from Shanghai to Rotterdam, with the ports marked.
Compare NATO and BRICS members on a dark map, and give me a URL I can embed.
The third one is the one to try if you only try one. Sea routes thread Suez,
Panama and Malacca instead of drawing a straight line across Asia:
[Sea route from Shanghai to Rotterdam through the Suez canal, with both ports marked]
Tools
create_map
A map from your data. Numeric values give a choropleth, colours paint regions
flat, text values give qualitative buckets, and highlight covers the case
where the point is which regions rather than how much.
Region ids are ISO 3166-1 alpha-2 at the world scope (US, DE, BR) and ISO
3166-2 inside a country scope (RO-B, RO-CJ). Data arrives structured — the
server owns the URL grammar, so the model never hand-assembles US:200:#ff0000.
add_layers
Markers, routes, proportional circles, pattern fills, annotations and labels,
added to a map you already made. It takes that map's URL and appends — so
it is also how a map gets built up over several turns instead of rebuilt from
scratch each time.
find_places
A place name resolved to real coordinates and the id maproll uses. Countries,
regions, cities and airports, each with its ISO 3166-1 / 3166-2 / IATA code.
Worth using before every marker. Coordinates recalled from memory are routinely
wrong by degrees, and a map draws a wrong marker exactly as confidently as a
right one.
describe_options
The scopes, themes, marker icons, projections and pattern fills the renderer
actually accepts. An invented theme or icon name renders nothing and reports no
error, so checking beats guessing.
What comes back
Every tool that makes a map returns the rendered PNG to look at, plus:
Why the URL is the map
An agent usually hands back an artifact: a file, a blob, something that exists
in the conversation and nowhere else. maproll hands back an address.
There is no session and no state to keep, because svg_url is the state.
Pass it to add_layers and a new URL comes back with the addition applied.
Every URL from every step still renders, forever, in an <img> tag with no
JavaScript.
Branding and keys
Maps work with no account. What anonymous costs is the wordmark: every map this
server makes carries the small maproll mark in the corner.
A key removes it. Mint one in the editor at
app.maproll.io → API keys, and pass it in the
server's environment:
With a key, returned URLs carry a signature bound to that one map, so an
embedded map renders clean wherever it is published — without the key itself
ever appearing in a link someone can copy. Two things worth knowing: keys
expire after 90 days, and when one expires, embeds published under it start
carrying the wordmark again. Regenerate the maps if that matters.
OpenStreetMap attribution stays on either way. That is a licence obligation,
not branding.
Resources and prompts
Seven read-only resources publish the catalogs a model otherwise guesses at —
maproll://grammar most of all, plus the scope, theme, icon, projection and
pattern lists and a set of worked examples.
Three prompts ship with the server: mapped_episode (a dataset in the house
style of Mapped), readme_map (a map plus a
paste-ready snippet with real alt text), and refine_map (change an existing
map in plain English).
Documentation
Development
See DEVELOPMENT.md for the layout, the local loop, and the
end-to-end smoke test. Publishing notes are in PUBLISHING.md.
MIT licensed.
