Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@ultimaps/mcp Show a choropleth of population by US state."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for Ultimaps. Ask Claude, Codex or any MCP client for a map and get the image back in the conversation. It covers choropleths from pasted numbers, category maps and pinned locations, for countries, states, provinces, counties, continents and the world.
"Map US states by population." · "Color the EU members by currency." · "Show France's regions with these unemployment rates: …" · "Pin our five offices on a map of Europe."
No account needed. Without an API key the server uses the keyless tier; set ULTIMAPS_API_KEY for plan quotas and larger or unbranded output.
Tool | What it does |
| Renders a map as an image (PNG, or SVG with a Pro key), shown inline when it is small enough. Choropleth (numbers), categories (labels) or explicit colors, plus pins, title, legend, theme, labels and extra layers. Region names are matched fuzzily, and every correction or miss is reported with suggestions. |
| The map catalog: |
| One map's region keys and titles, 200 per page, searchable by key, title or alias. |
All three are read-only. Agents rarely need the discovery tools: render_map accepts region names, codes and aliases directly.
Related MCP server: mcp-maptiler
Requires Node.js 20 or newer.
claude mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
claude mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcpcodex mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
codex mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcpCodex writes TOML, not the JSON below. The equivalent entry in ~/.codex/config.toml (or .codex/config.toml in a trusted project):
[mcp_servers.ultimaps]
command = "npx"
args = ["-y", "@ultimaps/mcp"]Download ultimaps-<version>.mcpb from the latest release and open it: Claude Desktop installs it in one click and asks for the optional API key. Or add this to claude_desktop_config.json:
{
"mcpServers": {
"ultimaps": {
"command": "npx",
"args": ["-y", "@ultimaps/mcp"],
"env": { "ULTIMAPS_API_KEY": "" }
}
}
}~/.cursor/mcp.json (or .cursor/mcp.json in a project):
{
"mcpServers": {
"ultimaps": { "command": "npx", "args": ["-y", "@ultimaps/mcp"] }
}
}.vscode/mcp.json:
{
"servers": {
"ultimaps": { "type": "stdio", "command": "npx", "args": ["-y", "@ultimaps/mcp"] }
}
}Variable | Default | Purpose |
| none (keyless) | API key from Studio → Workspace → API. An invalid key is an error and never falls back to keyless. |
|
| Point at a local API during development ( |
Keyless | Free key | Pro key | |
Renders | 30/hour, 5/minute | 500/month, 50/day, 10/minute | 5,000/month, 1,000/day, 30/minute |
Output | PNG up to 1600 px, attribution | PNG up to 1600 px at scale 2 (a 3200 px raster), attribution | PNG up to 4000 px at scale 4, SVG, no attribution |
All keys in a workspace share the monthly quota. The daily and per-minute caps are per key, so a free key stops at 50 renders a day long before the month runs out.
Dry runs skip the monthly quota but still count against rate limits. When five or fewer keyless renders remain in the hour, the result says so.
The image, inline, when it is small enough (781 KB for PNG, 98 KB for SVG). The default 1200 px width usually fits. Every render is also written to <tmpdir>/ultimaps-mcp/ and the path is in the result, so in a terminal client the file is the thing you can actually open. Nothing is re-rendered or resampled on your behalf.
A text report: auto-corrected and unmatched region keys with suggestions, the resolved choropleth plan, warnings (such as layer_unavailable), a link to open the map in Ultimaps Studio for editing, and the render id for support.
An embeddable image URL for keyless PNG renders whose whole spec fits a ~2,000-character URL, so small datasets only. The URL carries the spec, not the image, and renders keyless, so it is not offered when a key is set.
structuredContent with the same report as data, described by the tool's outputSchema.
This server runs on your machine, has no telemetry of its own and talks only to the Ultimaps API (https://api.ultimaps.com, or the ULTIMAPS_API_URL you set). The full Ultimaps privacy policy is at ultimaps.com/privacy-policy.
What is sent to Ultimaps. Tool calls are ordinary HTTPS requests to the Ultimaps API, so they arrive from your IP address with an ultimaps-mcp/<version> user agent. render_map sends the whole map request: region keys and values, pins, title and styling. If you set ULTIMAPS_API_KEY, it is sent with render requests only.
What Ultimaps keeps. Each render request is logged: the request content, the map and outcome, timing, your IP address and user agent, and for keyed requests which key and workspace made it. This lets support look up a render id, lets the "Open in Studio" link rebuild your map, and counts usage. The request content is kept for 30 days and the IP address and user agent for 90 days; what remains is a usage record, tied to your workspace when a key was used. Ultimaps uses a third-party error-monitoring service that may receive details of a failed request. Ultimaps does not sell this data or use it for advertising.
What stays on your machine. Every rendered image is written to <tmpdir>/ultimaps-mcp/ and this server never deletes it. What your MCP client keeps, including tool results in your conversation, is governed by its own privacy policy.
Shareable links. The embeddable image URL offered for small keyless renders contains the full map request; anyone with the link can read it.
Questions or deletion requests: support@ultimaps.com, quoting the render id.
npm install
npm run typecheck
npm test # unit + in-process protocol tests
npm run build # → dist/End-to-end over stdio against a real API (spends render units from your tier):
npm run build
node scripts/smoke.mjssrc/generated/render-request.schema.json is generated from the Ultimaps API contract; do not edit it by hand. Tool and property descriptions live in src/descriptions.ts. Arguments are never validated locally: the API is additive-only, and its 400 responses carry suggestions.
Issues and pull requests are welcome. Releases are cut by the Ultimaps team, and accepted changes ship with the next release.
The package publishes a bin and nothing else. import '@ultimaps/mcp' is not
supported and fails by name, because dist/index.js starts a stdio server when
it loads.
MIT © Ultimaps. See LICENSE.
Look up one map: title, regionType, regionCount, labels, layers, and its regions as {key, title}, 200 per page.
You rarely need this before rendering. render_map accepts region names, codes and common aliases and auto-corrects typos, reporting what it matched.
Use it to build a dataset covering every region of a map, to see how a map names its regions, or to resolve a key render_map could not match.
query searches keys, titles and aliases, so no hits means the map really has no such region. Use offset for further pages.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map id from list_maps, e.g. "united-states", "europe", "united-states-california". | |
| query | No | Search region keys, titles and aliases, e.g. "saint" or "US-TX". Omit to page through every region. | |
| offset | No | Skip this many regions. Pages hold 200 regions; use the offset the previous result names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and open-world behavior, lowering the bar. The description adds meaningful behavioral depth: pagination limit of 200 per page, the region result shape, and the 'no hits means no such region' semantics for query. This goes beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense, with no filler. It front-loads the operation and result shape, then gives usage guidance and parameter behavior in just a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only lookup with no output schema, the description fully covers what is returned, pagination, query semantics, and when to prefer an alternative. An agent has enough context to call it correctly without further investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, so the baseline is 3. The description adds slight interpretive value for query ('no hits means the map really has no such region') but mostly restates what the schema already documents about mapId, query, offset, and 200-region pages.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('Look up one map'), enumerates the returned data fields, and clearly distinguishes this tool from render_map and list_maps. An agent can tell exactly what it will get and which sibling it should use instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says this tool is rarely needed before renderingainer and points to render_map as the alternative that accepts aliases and corrects typos. It then lists concrete use cases: building a full dataset, inspecting region naming, or resolving unmatched keys.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the maps Ultimaps can render: the world, continents, countries subdivided into states, provinces, counties or departments, and US ZIP code areas.
Each row is {id, title, regionType, layers, regionCount, labels}. id is the mapId for render_map and get_map_regions; it is the map's slug on ultimaps.com (the last path segment, not the whole URL) and always means the current edition.
regionCount is how many region keys a complete dataset needs. labels: false means the map has no region labels, so style.labels does nothing there. layers are the ids render_map's layers can turn on.
Pass query to search ids, titles, region types and categories (e.g. "counties", "germany", "africa").
Only call this when you don't know the id: common ids such as world, united-states and europe just work, and an unknown id usually comes back with the closest ids.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search map ids, titles, region types and categories, e.g. "counties", "germany", "africa". Omit to list every map. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses detailed output behavior: exact row shape, meaning of id as a slug that always refers to the current edition, the implication of labels:false on style.labels, and how layers relate to render_map. This gives agents actionable behavioral context not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds value: it starts with the core purpose, then explains row semantics, then query, then when to call. Advice like using common ids without listing is actionable. There is no filler and the structure front-loads the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description fully compensates by specifying the output shape and the meaning of each field, including relationships to sibling tools and the practical consequence of labels:false. It also covers query behavior and fallback behavior for unknown ids, so an agent has everything needed to call and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter (query) with a description identical to the one in the tool description, including the 'omit to list every map' behavior. With 100% schema coverage, the description adds no new meaning beyond repeating examples, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the maps Ultimaps can render' and enumerates the kinds of maps (world, continents, countries subdivided into states, provinces, counties, departments, US ZIP areas). It also links the output to sibling tools ('id is the mapId for render_map and get_map_regions'), differentiating it as the catalog tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call it: 'Only call this when you don't know the id' and gives concrete exceptions ('common ids such as world, united-states and europe just work'). It also explains how to narrow results with query, giving examples. This directly guides tool selection against siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a map of the world, a continent, a country, its states/provinces/counties, or US ZIP code areas as an image shown in the conversation. Color regions with ONE of these (choropleth and categories are mutually exclusive):
choropleth: a number per region, e.g. {"values": {"California": 39.5, "Texas": 30.5}}. Classes, breaks and palette are picked from the data unless you set them.
categories: a label per region, e.g. {"values": {"France": "Euro", "Poland": "Złoty"}}. Colors are assigned automatically unless you set colors.
regions: explicit hex colors, e.g. {"Texas": "#1D4ED8"}. Also works on top of either mode as an override.
Region keys can be names, ISO/FIPS-style codes or common aliases. Typos are auto-corrected, and every correction or unmatched key is reported with suggestions, so there is no need to call get_map_regions first. Get mapId from list_maps if you don't know it.
Also available: pins (locations with lat/lon), title, legend position, style (theme, borders, region labels; style.labels.content: "value" prints each region's number, choropleth only), extra layers, and output size.
dryRun: true validates and previews region matching and the color plan without rendering.
Without an API key: 30 renders per hour and 5 per minute (dry runs count), PNG up to 1600 px wide, with Ultimaps attribution on the image. The default 1200 px width is right for viewing in chat. Larger widths and scales are for files and are saved to disk instead of shown. Formats: png, or svg with a Pro key. PDF is not available.
Every render is also written to a file and the path reported. Relay that path: in a terminal client the inline image is visible to you but NOT to the user, and the file is the only thing they can open.
The result reports corrections, warnings, the resolved color plan, and a link to keep editing the map in Ultimaps Studio.
| Name | Required | Description | Default |
|---|---|---|---|
| mapId | Yes | Map id from list_maps, e.g. `world`, `united-states`, `europe`, `united-states-california`. It is the map's slug on ultimaps.com (the last path segment, not the whole URL) and always resolves to the current edition. | |
| style | No | ||
| title | No | ||
| dryRun | No | Validate and preview without rendering: returns the region matching report, the resolved choropleth plan and a legend preview. No image and no monthly quota for keyed calls, but it still counts against the rate limit (one of the 30 keyless renders per hour). | |
| layers | No | Extra geographic layers to draw, e.g. {"cities": true, "roads": true}. Each map ships a subset (`layers` in list_maps and get_map_regions). Turning on a layer the map lacks is not an error: it is skipped with a `layer_unavailable` warning. Omitted layers are off, except layers a map turns on by default (currently `admin0` on ZIP-code maps); pass false to hide those. | |
| legend | No | ||
| output | No | Image size and format. Keep the default width (1200 px) for images viewed in the conversation: much larger renders, and any scale of 2 or more, are too big to show inline and are saved to a file instead. Without an API key: width up to 1600 px, an explicit height up to 1600 px, scale 1. Hard caps: width×scale and height×scale ≤ 8192, and at most 4096×4096 pixels in total. | |
| regions | No | Override layer. Region key to hex color, applied AFTER choropleth/categories coloring and winning over it. Precedence: choropleth/categories paint first, `regions` overrides win, and everything else gets `choropleth.noDataColor` (choropleth mode), else `style.defaultRegionColor`, else the theme default. | |
| locations | No | Pin markers. They compose with every mode. | |
| categories | No | Categorical coloring mode. Mutually exclusive with `choropleth`. Unmatched keys simply leave their regions uncolored. The no-data fill is `style.defaultRegionColor`, and `noDataColor` does not apply here. | |
| choropleth | No | Numeric choropleth mode. Mutually exclusive with `categories` (one scale per map). `regions` composes with it as an override layer. If none of the keys in `values` match, the request fails even under `onUnmatched: warn`, since there is nothing to build a scale from. `type`, `classes`, `method` and `palette` are all optional: whatever you leave out is suggested from the data, and the resolved plan is reported in the result. | |
| onUnmatched | No | warn = render anyway (unmatched regions get the no-data fill) and report. error = 400 with per-key suggestions. Recommended for production pipelines: error. Exception: in choropleth mode, ZERO matched keys is a 400 even under warn. | warn |
| Name | Required | Description |
|---|---|---|
| file | No | Set when the image was saved to disk (too large to inline, or SVG). |
| dryRun | Yes | |
| format | No | Image format; absent on dry runs. |
| legend | No | Dry runs: legend preview, [{label, color}] or {points, stops} for a gradient. |
| editUrl | No | Opens this map in Ultimaps Studio for editing or export. |
| embedUrl | No | Keyless GET image URL, when the render is shareable that way. |
| renderId | Yes | The API render id; quote it to Ultimaps support. |
| warnings | Yes | |
| choropleth | No | The resolved choropleth plan. Dry runs add `reason` and `breaks`. |
| regionMatching | Yes | |
| keylessRemaining | No | Keyless renders left in the current hour. |
| matchingTruncated | Yes | True when `corrected`/`unmatched` list only the first 5 of their counts. Repeat the call with dryRun: true for the full report. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only include readOnlyHint and openWorldHint, so the description carries substantial behavioral disclosure. It reveals that renders count against rate limits, that outputs are written to files and the path must be relayed (critical for user visibility), and that dryRun validates without rendering. It also mentions the result reports corrections, warnings, and a Studio link. While detailed, it stops short of specifying exact API limits beyond the keyless tier, and the openWorldHint is only implicitly reflected in 'additive-only enums' statements. Overall it adds significant context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for coloring modes, additional options, and limits, and it front-loads the core functionality. It is longer than a typical description but packs valuable info like rate limits and file relay instructions. However, some repetition exists (e.g., width/scale caveats appear in both prose and output schema), and the sheer length may reduce scannability. Still, every sentence contributes to agent success, so a 4 is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 12 parameters, an output schema exists and extensively documents nested fields, so the description doesn't need to repeat those. It covers essential runtime behavior: rate limits, file output and relay requirement, dryRun validation, and result contents. It also includes tips like the default width being suitable for chat and SVG requiring Pro. The only minor gap is that it doesn't enumerate all possible layers, but the schema and sibling get_map_regions cover that. Given the complexity, it is remarkably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 75%, and the description compensates by summarizing key parameters like choropleth, categories, regions, style, legend, output, and dryRun with examples. It explains relationships (mutual exclusivity, precedence) and provides critical hints like the default 1200px width and file-saving behaviors for large renders. However, many nested parameters are exhaustively documented in the schema, so the description adds high-level guidance rather than per-field details, which is justified given the schema richness. It earns a 4 for good balance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders maps at multiple levels (world, continent, country, etc.) as an image shown in the conversation, and it distinguishes the main coloring modes (choropleth vs categories vs regions). It differentiates from siblings by referencing list_maps for getting mapId and get_map_regions for region lists, but these are complementary rather than alternatives. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool and how to avoid unnecessary calls: it states that region typo auto-correction means there is no need to call get_map_regions first, and it directs to list_maps when mapId is unknown. It also clarifies mutual exclusivity of choropleth/categories and provides usage examples. This fully satisfies the 'when to use vs alternatives' criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_map_regionslist_mapsrender_mapScored across 3 tools
Each tool has a distinct purpose: list_maps enumerates available maps, get_map_regions retrieves detailed region data for a specific map, and render_map produces an image. There is no overlap that would confuse an agent selecting a tool for a task.
All tool names follow a consistent verb_noun pattern: list_maps, get_map_regions, render_map. The pattern is uniform and predictable, making it easy to infer function from name.
Three tools is a well-scoped count for a map rendering service. Each tool covers a necessary part of the workflow—discover, inspect, and render—without unnecessary bloat or gaps.
The tool surface fully covers the intended domain: it allows listing available maps, fetching region details, and rendering maps with extensive customization. Additional operations like map editing or management are out of scope, so the set is complete for its stated purpose.
Generate styled PNG/SVG map images of any location with 11 customizable color themes.
Turn rows into bar, line, pie and scatter chart images plus an optional PDF or HTML report.
Google Maps MCP Pack — geocoding, places, directions, distance matrix, elevation.
Ask in plain English, get a rendered, shareable map from live public data. 24 geospatial tools.
