maplibre-mcp

maplibre-mcp

An MCP server that lets an AI agent see the MapLibre map it works on, check it, and show it to you.

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 · Getting started · Examples · 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 says where each one keeps it.

{
  "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 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.

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 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 basemap, in clients that support MCP Apps.
• martin_list_sources lists the tiles, sprites, fonts and styles a Martin server serves, with the URLs to use in a style.
• search_ecosystem searches Make with MapLibre 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, 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 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:

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

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 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 has the details.

Development

npm install
npm test
npm run dev:site

License

MIT © 2026 Birk Skyum