# maproll MCP server

> Let an AI assistant generate permanent, embeddable static maps including choropleths, sea routes, and markers using URL-based state.

- Repository: https://github.com/maproll-io/mcp
- Page: https://hostedmcp.org/servers/maproll-io/mcp
- Transport: stdio
- Stars: 4
- License: MIT
- Latest version: 0.2.4

## Install

### Claude Code

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

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

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

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

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

### VS Code CLI

```sh
code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@maproll/mcp"]}'
```

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

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

### Codex

```sh
codex mcp add mcp -- npx -y @maproll/mcp
```

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

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

### Gemini CLI

```sh
gemini mcp add -s user mcp npx -- -y @maproll/mcp
```

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

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

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MAPROLL_API_KEY` | no | no |  |

## Tools (4)

- `create_map`: 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 <img> 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. (read-only)
- `add_layers`: 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. (read-only)
- `find_places`: 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. (read-only)
- `describe_options`: 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. (read-only)

## FAQ

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

No, the server runs from npm on demand and talks to the public render API without an account or signup. However, using a key removes the maproll wordmark from your maps.

### How can I add more elements to a map I already created?

You can use the `add_layers` tool, which takes the existing map's URL and appends new markers, routes, or annotations to it.

### What are the requirements to install the server?

The server requires Node 20 or newer to run.
