Ultimaps MCP server

@ultimaps/mcp

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 ULTIMAPSAPIKEY for plan quotas and larger or unbranded output.

Can't run a local command? In ChatGPT (developer mode), claude.ai or any client that connects to remote MCP servers, add the hosted server instead: https://api.ultimaps.com/mcp. In ChatGPT, turn it on in each conversation where you want maps. It has the same three tools and nothing to install. See Hosted server. This package is the local version: requests come from your own IP address with your own key, and every image is saved to a file on your computer.

Tools

All three are read-only. Agents rarely need the discovery tools: render_map accepts region names, codes and aliases directly.

Install

Requires Node.js 20 or newer.

Claude Code

claude mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
claude mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcp

Codex

codex mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
codex mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcp

Codex 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"]

Claude Desktop

Download ultimaps-.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 claudedesktopconfig.json:

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

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in a project):

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

VS Code

.vscode/mcp.json:

{
  "servers": {
    "ultimaps": { "type": "stdio", "command": "npx", "args": ["-y", "@ultimaps/mcp"] }
  }
}

Hosted server

You don't need this package to use the hosted server. Add the URL to your client:

claude mcp add --transport http ultimaps https://api.ultimaps.com/mcp
# with a key:
claude mcp add --transport http ultimaps https://api.ultimaps.com/mcp \
  --header "Authorization: Bearer um_live_…"

Clients with a config file take the URL alone, for example ~/.cursor/mcp.json:

{
  "mcpServers": {
    "ultimaps": { "url": "https://api.ultimaps.com/mcp" }
  }
}

Shortened. The full README is on GitHub.