# Ultimaps

Ultimaps — an MCP server that renders choropleths, category maps and pins from region names and values. Works without an API key, saves images locally.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 1 repo stars
- Author: ultimaps
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ultimaps/mcp-server
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/ultimaps

## What it does

The agent gets a `render_map` tool that draws maps: colors countries, states, counties or ZIP codes by numbers (choropleth), categories or explicit colors, adds pins, title and legend. Region names are matched fuzzily and every correction is reported. Two other tools, `list_maps` and `get_map_regions`, provide a map catalog and region lists, but agents rarely need them: `render_map` accepts names, codes and aliases directly.

Without an API key, the keyless tier gives 30 renders per hour, PNG up to 1600 px with attribution. A key from Ultimaps Studio unlocks a plan: free tier — 500 renders per month, Pro — 5,000 and SVG without attribution. The image is returned in the response when it fits and always written to `<tmpdir>/ultimaps-mcp/`. Besides the local npm package, a hosted server at `https://api.ultimaps.com/mcp` works the same way but requires no Node.js.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://api.ultimaps.com/mcp`
- Environment variables: `ULTIMAPS_API_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http mcp https://api.ultimaps.com/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env ULTIMAPS_API_KEY=<ULTIMAPS_API_KEY> --transport stdio ultimaps -- npx -y @ultimaps/mcp
```
Replace <…> with your own values

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add ultimaps --url https://api.ultimaps.com/mcp
```

2. **Platform CLI**
```bash
codex mcp add ultimaps --env ULTIMAPS_API_KEY=<ULTIMAPS_API_KEY> -- npx -y @ultimaps/mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "ultimaps": {
            "url": "https://api.ultimaps.com/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "ultimaps": {
            "command": "npx",
            "args": [
                "-y",
                "@ultimaps/mcp"
            ],
            "env": {
                "ULTIMAPS_API_KEY": "<ULTIMAPS_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "ultimaps": {
            "type": "http",
            "url": "https://api.ultimaps.com/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "ultimaps": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@ultimaps/mcp"
            ],
            "env": {
                "ULTIMAPS_API_KEY": "<ULTIMAPS_API_KEY>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http ultimaps https://api.ultimaps.com/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e ULTIMAPS_API_KEY=<ULTIMAPS_API_KEY> ultimaps npx -y @ultimaps/mcp
```
Replace <…> with your own values

## When to use it
- draw a choropleth of US states by population
- color EU countries by currency
- pin five offices on a map of Europe
- build an unemployment map for France's regions
- preview region name matching before rendering

## Example prompts
- Map US states by population
- Color EU countries by their currency
- Show unemployment rates for California, Texas and New York on a map

## Similar
- [matplotlib-best-practices](https://affpapa.org/en/nevibecode/skills/matplotlib-best-practices.md) — skill · 1100 installs
- [maproll](https://affpapa.org/en/nevibecode/mcp/maproll.md) — MCP server · ★ 4 repo stars
- [globestudio](https://affpapa.org/en/nevibecode/skills/globestudio.md) — skill · ★ 41430 repo stars
- [cartography-geoviz](https://affpapa.org/en/nevibecode/skills/cartography-geoviz.md) — skill · ★ 48 repo stars
- [r-reviewer](https://affpapa.org/en/nevibecode/agents/r-reviewer.md) — subagent · ★ 1104 repo stars
- [karpathy-jobs-bls-visualizer](https://affpapa.org/en/nevibecode/skills/karpathy-jobs-bls-visualizer.md) — skill · 1300 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
