# Ultimaps MCP server

> Generates choropleth, category, and pin maps of countries, states, and ZIP codes as images for AI clients.

- Repository: https://github.com/ultimaps/mcp-server
- Page: https://hostedmcp.org/servers/ultimaps/mcp-server
- Transport: stdio, remote
- Stars: 1
- License: MIT
- Latest version: 0.2.1

## Install

### Claude Code

```sh
claude mcp add --env 'ULTIMAPS_API_KEY=<YOUR_ULTIMAPS_API_KEY>' mcp-server -- npx -y @ultimaps/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@ultimaps/mcp"
      ],
      "env": {
        "ULTIMAPS_API_KEY": "<YOUR_ULTIMAPS_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ultimaps/mcp"
      ],
      "env": {
        "ULTIMAPS_API_KEY": "<YOUR_ULTIMAPS_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp-server","type":"stdio","command":"npx","args":["-y","@ultimaps/mcp"],"env":{"ULTIMAPS_API_KEY":"<YOUR_ULTIMAPS_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@ultimaps/mcp"
      ],
      "env": {
        "ULTIMAPS_API_KEY": "<YOUR_ULTIMAPS_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add mcp-server --env 'ULTIMAPS_API_KEY=<YOUR_ULTIMAPS_API_KEY>' -- npx -y @ultimaps/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mcp-server]
command = "npx"
args = ["-y", "@ultimaps/mcp"]

[mcp_servers.mcp-server.env]
ULTIMAPS_API_KEY = "<YOUR_ULTIMAPS_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'ULTIMAPS_API_KEY=<YOUR_ULTIMAPS_API_KEY>' mcp-server npx -- -y @ultimaps/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@ultimaps/mcp"
      ],
      "env": {
        "ULTIMAPS_API_KEY": "<YOUR_ULTIMAPS_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `ULTIMAPS_API_KEY` | no | yes | Optional API key. Without one you get 30 maps per hour with attribution. A key raises the limits, and a Pro key adds SVG, larger PNGs and no attribution. |

## Tools (3)

- `list_maps`: 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. (read-only)
- `get_map_regions`: 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. (read-only)
- `render_map`: Draws a map of real places as an image: countries, states, counties or ZIP codes colored by data (a choropleth or heat map) or by category, with a legend, a title and pins. Borders come from real geographic data, not from an image model, and region names are matched for you. It draws only real places, never fictional or invented ones. The map is returned as an image in the conversation. Maps cover the world, continents, countries, their states, provinces and counties, and US ZIP code areas. 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. Say what the numbers are with `kind` (and `midpoint` when they have a meaningful center, `unit` for a short label unit): that is what gets percents, currencies, years and diverging scales right. When the data does not cover every region of the map, add `noData: true` so the legend explains the uncolored ones. - `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, `title`, `subtitle`), `style` (theme, borders, region labels; `style.labels.content: "value"` prints each region's value instead of its name and `"name_value"` stacks the name above the value, both needing `choropleth` or `categories`; `style.labels.fit` (default "auto") shortens labels that don't fit or overlap and never hides one; any still overlapping are reported in a `labels_overlap` warning with their keys), extra `layers`, and `output` size. A data legend needs a `legend.title`: what is measured, its unit and the year ("Median household income (US$, 2023)"). An untitled legend leaves the reader guessing. Short units ("%", "°C", "t") go in `choropleth.unit`, long ones ("litres per person") in the legend title. `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. In a terminal client the inline image reaches only the model, and that file is the one thing the user can open. The result reports corrections, warnings, the resolved color plan, and an edit link that opens the map in Ultimaps Studio, where it can be edited, exported, or published as an interactive, clickable map to embed on a website (free account).

## FAQ

### Do I need an API key to use Ultimaps?

No, you can use the keyless tier without an account. Setting an ULTIMAPS_API_KEY allows for larger outputs and higher plan quotas.

### What kind of maps can I create?

You can create choropleth maps from numbers, category maps with labels, and maps with pinned locations for various regions like countries, states, and counties.
