# maplibre-mcp

[![birkskyum/maplibre-mcp MCP server](https://glama.ai/mcp/servers/birkskyum/maplibre-mcp/badges/score.svg)](https://glama.ai/mcp/servers/birkskyum/maplibre-mcp)

An MCP server that lets an AI agent see the [MapLibre](https://maplibre.org) map it works on, check it, and show it to you.

![A hiking map of the Alps in 3D, with the Matterhorn against an evening sky](https://raw.githubusercontent.com/birkskyum/maplibre-mcp/main/site/public/images/hiking-style-matterhorn.webp)

A hiking style an agent made from one prompt, rendered with `render_style` from a camera placed above Zermatt.

A coding agent can write a MapLibre style, but it can't see the map. So it hands you untested work, or first spends minutes building a renderer of its own, and it reaches for what it remembers, like an older MapLibre GL JS or Mapbox. With maplibre-mcp the agent renders the style, looks at the image and fixes what it sees, and you get a link to a live map that redraws as it edits the file. It runs on your machine and needs no API key.

Two things it is good for:

- **Editing a style by chat while you watch the map change.** "Make the water darker", "thin the footpaths in the village". The agent edits the file and checks the render, and your open map follows.
- **Finding out why a layer doesn't draw.** The agent reads the real tiles, sees which layers draw at a place and why the others don't, and fixes the filter.

An agent with no shell to build its own tools, in a sandbox or a chat app, gets the most from it.

**[Website](https://birkskyum.github.io/maplibre-mcp/)** · [Getting started](https://birkskyum.github.io/maplibre-mcp/getting-started/) · [Examples](https://birkskyum.github.io/maplibre-mcp/examples/) · [Tools](https://birkskyum.github.io/maplibre-mcp/tools/)

## Install

It needs Node.js 22 or newer.

| Client | Command |
| --- | --- |
| Claude Code | `claude mcp add maplibre -- npx -y maplibre-mcp` |
| Codex | `codex mcp add maplibre -- npx -y maplibre-mcp` |
| Gemini CLI | `gemini mcp add maplibre npx -- -y maplibre-mcp` |
| Grok | `grok mcp add maplibre -- npx -y maplibre-mcp` |
| VS Code | `code --add-mcp '{"name": "maplibre", "command": "npx", "args": ["-y", "maplibre-mcp"]}'` |

Claude Desktop, Cursor, Windsurf and most other clients read this JSON. [Getting started](https://birkskyum.github.io/maplibre-mcp/getting-started/) says where each one keeps it.

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

Rendering with MapLibre GL JS uses the installed Google Chrome. Without Chrome, the first render fails with the command that installs the Chromium it can use instead.

In a sandbox or in CI, where no browser can be installed, use the container image `ghcr.io/birkskyum/maplibre-mcp`, which has the server and its Chromium. [Containers and sandboxes](https://birkskyum.github.io/maplibre-mcp/containers/) shows how.

## Command line

Agents that work in a shell, and people, can also run the rendering and data tools, and the GL JS API lookup, as commands, without setting up MCP. A style is a file or a URL.

```sh
npx -y maplibre-mcp render style.json --center 12.57,55.68 --zoom 12
npx -y maplibre-mcp compare before.json after.json --zoom 10
npx -y maplibre-mcp compare-renderers style.json --renderers gl-js,native
npx -y maplibre-mcp describe-sources style.json
npx -y maplibre-mcp debug-layers style.json --center 12.57,55.68 --zoom 14
npx -y maplibre-mcp inspect-tile https://tiles.openfreemap.org/planet --center 12.57,55.68 --zoom 14
npx -y maplibre-mcp describe-gl-js-api Map#flyTo
```

The images go to `map.png`, `compare.png` and `renderers.png`, or to `--out`. `npx -y maplibre-mcp --help` lists the options, and [Command line](https://birkskyum.github.io/maplibre-mcp/command-line/) has the details. To validate, format or migrate a style, use `gl-style-validate`, `gl-style-format` and `gl-style-migrate` from `@maplibre/maplibre-gl-style-spec`.

## Tools

- `validate_style` checks a style against the MapLibre Style Specification, and lists each problem with the path to its property.
- `describe_style_spec` looks up a layer type, property, source type or expression, with its documentation and the GL JS and Native versions that support it. For a misspelled name, it suggests the closest real ones.
- `describe_gl_js_api` looks up a class, method, option or event of MapLibre GL JS, with its signature, documentation, default and examples, in the type definitions of the version the server renders with, or of another version. It also says when a method is not in MapLibre, like one from Mapbox GL JS.
- `describe_sources` reads the TileJSON, PMTiles header or GeoJSON of each source in a style, lists the source layers and fields, and finds layers that use a source layer or field that is not there.
- `inspect_tile` reads the vector tile at a place and lists each source layer with its geometry types, the values of its fields and how often they occur, and a few example features, plus the zoom range of the source and the source layers the tile lacks. The source can be a source in a style, a TileJSON URL like a Martin source, a PMTiles archive or a tile URL, with MVT or MLT tiles.
- `debug_layers` says for each layer of a style whether it draws at a place and zoom, and if not, why, like a missing source layer, a filter that matches nothing (next to the values the data has), a fill layer without polygons, paint that comes out as 0 or transparent, or icons missing from the sprite. It also notes text that falls back to local fonts, since the glyph server lacks its font stack.
- `render_style` renders a style to a PNG, and reports map errors, missing fonts and missing icons. It takes a center, zoom, bearing and pitch, bounds to fit, or a camera position and a point to look at over 3D terrain.
- `preview_style` gives the user a link to a live, interactive map of a style. The map follows the style file as it changes, and an agent with no files to write sends a changed style to the same link.
- `render_page` renders a web page with a map, for what a style cannot hold, like plugins, controls and the page's code. It reports the page's errors and failed requests, and can run a script in the page first.
- `compare_styles` renders two versions of a style at the same camera, and returns one image with the style before, after, and their differences in red.
- `compare_renderers` does the same for one style in two renderers, for example to check that a style looks the same on the web and on mobile.
- `show_map` shows the user an interactive map with GeoJSON layers and markers on an [OpenFreeMap](https://openfreemap.org) basemap, in clients that support MCP Apps.
- `martin_list_sources` lists the tiles, sprites, fonts and styles a [Martin](https://martin.maplibre.org) server serves, with the URLs to use in a style.
- `search_ecosystem` searches [Make with MapLibre](https://makewithmaplibre.com) for SDKs, plugins, routing, geocoding, styling and tiling libraries, hosted APIs, products and consultancies, filtered by kind and platform, with their links and live demos.
- `find_basemaps` lists the basemaps in Make with MapLibre with their style URLs or tile sources, whether they need an API key, and the attribution or logo their provider requires on the map.

The data of Make with MapLibre is © Birk Skyum, under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), and both tools end with its credit.

The tools that take a style accept it as an object (`style`), a URL (`url`) or a file (`path`, relative to where the server runs). The [tool reference](https://birkskyum.github.io/maplibre-mcp/tools/) lists every parameter.

## Toolsets

The tools are grouped by the MapLibre project they belong to. `style`, `gl-js` and `ecosystem` are on by default. Choose others with `--toolsets`, or with the `MAPLIBRE_MCP_TOOLSETS` environment variable, and `all` turns on every toolset:

```sh
npx -y maplibre-mcp --toolsets style,gl-js,martin
```

| Toolset | What it adds |
| --- | --- |
| `style` | `validate_style`, `describe_style_spec`, `describe_sources`, `inspect_tile`, `debug_layers` |
| `gl-js` | Rendering with MapLibre GL JS, `render_page`, `preview_style`, `describe_gl_js_api` and `show_map` |
| `native` | Rendering with MapLibre Native |
| `martin` | Rendering with a Martin server, and `martin_list_sources` |
| `ecosystem` | `search_ecosystem` and `find_basemaps`, which read the catalog of [Make with MapLibre](https://makewithmaplibre.com) |

With any renderer on, there are `render_style` and `compare_styles`, and with two or more, `compare_renderers`. Rendering with MapLibre Native needs one more package, and rendering with Martin needs a Martin build with rendering. [Rendering](https://birkskyum.github.io/maplibre-mcp/rendering/) covers both.

## Remote server

`--http` serves Streamable HTTP at `http://127.0.0.1:3100/mcp` instead of stdio, and `--host` and `--port` change the address. On a loopback address it only answers requests from localhost. On any other address it does not read or write files, it still fetches the URLs it is given from its own network, and it has no authentication, so put it behind a proxy that has. [Remote server](https://birkskyum.github.io/maplibre-mcp/remote-server/) has the details.

## Development

```sh
npm install
npm test
npm run dev:site
```

## License

MIT © 2026 [Birk Skyum](https://github.com/birkskyum)