Skip to main content
Glama
maproll-io

@maproll/mcp

Official
by maproll-io
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

@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

claude mcp add maproll -- npx -y @maproll/mcp

Any other client takes the same command as config — Claude Desktop, Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json under "servers"):

{
  "mcpServers": {
    "maproll": {
      "command": "npx",
      "args": ["-y", "@maproll/mcp"]
    }
  }
}

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.

Related MCP server: @chartone/mcp

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:

Field

What it is

svg_url

The map. Embeddable, permanent, and the handle the other tools take.

png_url

The same map as PNG.

editor_url

Opens it in the maproll editor, loaded and editable.

embed

A ready <img> tag.

warnings

Non-fatal problems — region ids the renderer did not recognise, for instance.

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.

prompt → assistant → maproll MCP → https://api.maproll.io/map.svg?…
                                        ↓
              README · docs · dashboard · newsletter · the next tool call

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:

{
  "mcpServers": {
    "maproll": {
      "command": "npx",
      "args": ["-y", "@maproll/mcp"],
      "env": { "MAPROLL_API_KEY": "mr_live_…" }
    }
  }
}

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.

Variable

Default

Purpose

MAPROLL_API_KEY

—

Entitles renders, and removes the wordmark.

MAPROLL_PLACES_URL

https://mcp.maproll.io/places

Where find_places resolves names. Override only for local development.

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.

Available Tools

4 tools
add_layersAdd layers to a mapA
Read-onlyIdempotent

Add markers, routes, proportional circles, pattern fills, annotations or labels to an existing map, and return the new URL.

Takes the svg_url of a map you already made. Everything on it is kept — this appends rather than replaces, so it is also how you build a map up over several turns.

Resolve coordinates with find_places before adding a marker. Guessed lat/lon lands in the wrong country and the render will not complain.

Use sea routes for shipping: they follow the lanes through Suez, Panama and Malacca instead of drawing a straight line over land.

ParametersJSON Schema
NameRequiredDescriptionDefault
mapYesA map URL from a previous call. Everything already on it is kept.
labelsNo"ISO" labels every large region; an array labels only those ids.
routesNoA→B lines to add.
markersNoPoints to add.
patternsNoPer-region texture fills, for hatching a category onto a choropleth.
annotationsNoPer-region tooltip text.
proportionalNoCircles at region centroids, area proportional to value.

Output Schema

ParametersJSON Schema
NameRequiredDescription
embedYes
png_urlYes
svg_urlYes
warningsYes
editor_urlYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond these: the operation returns a new URL, appends to existing content, and silently accepts bad coordinates ('the render will not complain'). It also explains a key failure mode and a routing nuance, which the annotations alone do not convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and return value, then provides targeted caveats and usage rules. Each paragraph earns its place: append behavior, coordinate resolution warning, and sea-route clarification. No redundant filler is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 7 parameters, the description covers the critical context: when to use it, how it interacts with prior outputs, prerequisites, failure modes, and routing nuances. An output schema exists, so return values need not be described. The description is complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% parameter coverage, so the baseline is 3. The description goes further by advising coordinate resolution before markers and explaining why guessed lat/lon fails, plus clarifying sea-route behavior. It also reinforces the map parameter contract by noting everything is preserved. This adds genuine semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Add markers, routes, proportional circles, pattern fills, annotations or labels to an existing map, and return the new URL.' It clearly states the tool appends rather than replaces, distinguishing it from create_map. This is immediately actionable and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: it says to use the svg_url of a previously made map, that everything is kept, and that this is how to build a map over several turns. It also gives concrete alternatives and prerequisites: resolve coordinates with find_places before adding markers, and use sea routes for shipping lanes. This is strong directional guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_mapCreate a mapA
Read-onlyIdempotent

Make a production-ready static map and return its URL plus a rendered preview.

The map is a URL: the returned svg_url renders the same image forever, embeds in an tag with no JavaScript, and is the handle the other maproll tools accept.

Use it for choropleths (numeric values per region), flat colour paints, qualitative category maps, and plain highlight maps. 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").

Numeric values and text categories cannot appear in the same map — pick one.

Do not use it for interactive or zoomable maps, driving directions, or street-level detail; maproll renders static statistical maps, not a slippy map.

ParametersJSON Schema
NameRequiredDescriptionDefault
bboxNoCrop to "minLon,minLat,maxLon,maxLat"; the projection refits to the rectangle.
extraNoEscape hatch for documented parameters without a field here (patterns, annotations, proportional, labelMinArea, ...). Passed through verbatim.
scopeYesGeography to draw. "world", a group ("EU", "NATO", "G20", "ASEAN", "AFRICA"), or a country code for its subnational regions ("RO"). Read maproll://catalog/scopes for the full list.
themeNoColour theme. Defaults to dark.
titleNoHeadline above the map.
widthNoPixel width. Defaults to 1200.
breaksNoBin upper bounds. Required when classification is custom.
heightNoPixel height. Defaults to the projection's aspect ratio.
labelsNo"ISO" labels every region above the size threshold; an array labels only those ids.
legendNoShow the legend. Defaults true; set false for flat colour paints, which have no scale to show.
valuesNoPer-region data. Give `value` for a choropleth, `color` to paint a region flat, or `category` for qualitative buckets.
scaleBarNoKilometre scale bar, bottom left.
subtitleNoSmaller line under the title.
graticuleNoDraw a 10-degree lat/lon grid.
highlightNoRegion ids to highlight with no data behind them. Use instead of `values` when the point is which regions, not how much.
colorScaleNoSequential for magnitudes, diverging for values around a midpoint, categorical for buckets.
northArrowNoCompass arrow, top right.
projectionNoMap projection. Each scope has a sensible default; override only with a reason.
attributionNoOpenStreetMap credit. On by default and should stay on.
legendTitleNoCaption above the legend.
legendLayoutNo
classificationNoHow numeric values are binned. Ignored for diverging and categorical scales.

Output Schema

ParametersJSON Schema
NameRequiredDescription
embedYesReady-to-paste <img> tag.
png_urlYesSame map as PNG.
svg_urlYesEmbeddable SVG. This is also the handle other tools take.
warningsYesNon-fatal problems, e.g. region ids the renderer did not recognise.
editor_urlYesOpen in the maproll editor.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With readOnlyHint and idempotentHint already present, the description still adds valuable behavioral context: the returned svg_url is stable, JavaScript-free, renders the same image forever, and serves as the handle for other maproll tools. It also clarifies that the output is a static map rather than a slippy map. No annotation contradiction is present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the one-sentence purpose, and each subsequent paragraph earns its place: output semantics, supported use cases, id conventions, and exclusions. There is no filler or unnecessary repetition of schema details, despite the tool's large parameter surface.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 22-parameter tool, the description supplies the high-level decision framework that the schema cannot: what kind of map to build, which parameter mode to select, and when not to use the tool. Combined with the detailed schema and output schema, the agent has enough information to invoke create_map correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is very high (~95%), so the baseline is 3, and the description meaningfully reinforces the parameter model by explaining that value-based, color-based, category-based, and highlight-only maps are distinct usage modes. It also centralizes the ISO id convention and the numeric-vs-category incompatibility, which guides how to populate parameters. Most lower-level syntax remains in the schema, so a 4 is appropriate rather than 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Make a production-ready static map and return its URL plus a rendered preview,' which clearly identifies the tool's core task. It also lists supported map types (choropleths, flat paints, qualitative categories, highlights), but it does not explicitly contrast against sibling tools by name, so full sibling differentiation is left to the agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit positive use cases ('Use it for choropleths...') and explicit negative ones ('Do not use it for interactive or zoomable maps, driving directions, or street-level detail'). It also warns that numeric values and text categories cannot be combined, which helps the agent avoid invalid calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

describe_optionsList what the renderer acceptsA
Read-onlyIdempotent

Return the exact accepted values for scopes, themes, marker icons, projections, pattern fills, or the URL grammar.

The same content is published as the maproll:// resources; this tool is for hosts that do not read resources. Check it rather than guessing a name — an icon or theme that does not exist renders nothing and reports no error.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindYesWhich catalog to return.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses a critical behavioral trait: nonexistent icons or themes 'renders nothing and reports no error'. It also reveals that the same content is available via maproll:// resources, clarifying the tool's niche. There is no contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded with the tool's exact purpose. Every sentence earns its place: the first states what is returned, the second explains the alternative resource and warns against guessing. No filler or redundant restating of the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter catalog-read tool, the description is sufficient: it enumerates all catalog categories, explains why to use the tool, and notes the silent failure mode of invalid values. The absence of an output schema is not a problem because the description explicitly says it returns exact accepted values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage and a single enum parameter with a description, so the baseline is 3. The description adds value by expanding the enum labels into clearer phrases ('icons' → 'marker icons', 'patterns' → 'pattern fills', 'grammar' → 'URL grammar'), which helps an agent map the parameter to real-world concepts without much inference.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Return') and resource ('exact accepted values for scopes, themes, marker icons, projections, pattern fills, or the URL grammar'). It is easily distinguished from sibling tools like create_map and add_layers because it describes an introspection/catalog operation rather than a mutation or search operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: use this tool instead of reading maproll:// resources when the host does not read resources. It also tells the agent to 'Check it rather than guessing a name', with a concrete consequence of guessing incorrectly, which makes the invocation context clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_placesFind a placeA
Read-onlyIdempotent

Resolve a place name to real coordinates and the region id maproll uses.

Searches countries, regions, cities and airports, and returns each hit's ISO 3166-1 / 3166-2 / IATA code alongside its latitude and longitude.

Use it before placing any marker or lat,lon route endpoint. Coordinates recalled from memory are frequently wrong by degrees, and a map renders a wrong marker exactly as confidently as a right one.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNoNarrow the search. Omit to search all four.
limitNoDefault 10.
queryYesPlace name to resolve, e.g. "Constanța", "Suez", "Heathrow".

Output Schema

ParametersJSON Schema
NameRequiredDescription
placesYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral detail beyond those: it searches four place categories, returns codes alongside coordinates, and positions the tool as a correctness safeguard. With output schema present, return-value detail is not required, so this is strong coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tight and front-loaded: the core purpose appears in the first sentence, the scope/return details in the second, and the practical usage guidance in the third. No sentence is redundant, and the motivational warning earns its place by explaining why lookup is needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only lookup tool with full schema parameter documentation, an output schema, and safety annotations, the description supplies everything an agent needs to invoke it correctly: purpose, search scope, return contents, and the right moment to use it. The sibling tools are clearly different in function.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with descriptions already provided for query, kind, and limit. The main description does not add much parameter-specific meaning beyond reinforcing the searchable place categories, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Resolve a place name to real coordinates and the region id maproll uses.' It also enumerates the exact entity types searched and the returned identifiers (ISO codes, IATA, latitude/longitude), which clearly distinguishes it from the sibling creation/layer tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit usage context: 'Use it before placing any marker or lat,lon route endpoint' and warns against relying on recalled coordinates. It does not explicitly name alternatives or state when not to use this tool, so it stops short of a 5, but the intended workflow is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedadd_layers
    • First observedcreate_map
    • First observeddescribe_options
    • First observedfind_places
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct step in map production: creating the base map, appending layers, resolving place names, and querying supported options. There is no overlap or plausible confusion between their purposes.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with lowercase snake_case: create_map, add_layers, describe_options, find_places. The verbs clearly describe each action, making the set predictable and easy to navigate.

Tool Count5/5

Four tools is well-scoped for this server's purpose: each tool is necessary and covers a meaningful part of the map-building workflow. There is no redundancy or missing fundamental capability that would require additional tools.

Completeness4/5

The set covers the core workflow of creating, layering, geocoding, and discovering options without dead ends. The main limitation is that layers can only be appended and not removed or edited, but the immutable URL model makes this a minor gap rather than a blocking one.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers