maplibre-mcp

maplibre-mcp is an MCP server (Model Context Protocol) that provides support for MapLibre, with the goal of enabling AI agents to truly "see" and inspect the map they are operating on when editing map styles, and to present the results to the user.

Purpose

Coding agents can write MapLibre styles but cannot see the map, so they often can only deliver untested results, or spend time first building their own renderer, and tend to use older MapLibre GL JS or Mapbox syntax from memory. With maplibre-mcp, the agent can render the style, view the image, and fix the problems it sees, while the user gets a live map link, and the map redraws as the style file is edited. The server runs locally on the user's machine and requires no API key.

It is especially suited to two scenarios:

1. Editing styles through conversation while observing map changes, for example "make the water darker" or "make the village trails thinner." The agent edits the file and checks the rendered result, and the already-open map updates accordingly.
2. Finding out why a certain layer is not drawn. The agent reads the real tiles, sees which layers are drawn at a location and why other layers are not, and fixes the filters.

In environments without a shell where tools can be built on their own (such as sandboxes or chat applications), the agent benefits the most.

Runtime requirements and installation

Node.js 22 or newer is required. Claude Desktop, Cursor, Windsurf, and most other clients read the same JSON configuration, with the specific location described in their "Getting started" documentation. Rendering with MapLibre GL JS depends on an installed Google Chrome; if Chrome is not available, the first render will fail and provide the command to install a usable Chromium. In sandboxes or CI where a browser cannot be installed, the container image ghcr.io/birkskyum/maplibre-mcp can be used, which contains the server and its Chromium. Agents and users with a shell can also run the rendering, data, and GL JS API query tools directly from the command line without configuring MCP; styles can be files or URLs.

Main capabilities

The tools are grouped by the MapLibre project they belong to. By default, style, gl-js, and ecosystem are enabled, and --tool can be usedSet the MAPLIBRE_MCP_TOOLSETS environment variable to select other combinations; all means enable everything.

• validate_style: Validates a style against the MapLibre style specification, listing each issue and its property path.
• describe_style_spec: Looks up layer types, properties, source types, or expressions, with documentation and the supported GL JS and Native versions; for misspelled names it suggests the closest real name.
• describe_gl_js_api: Looks up classes, methods, options, or events in MapLibre GL JS, giving signatures, documentation, default values, and examples, based on the type definitions of the version used by the server rendering or other versions; it also points out when a method does not belong to MapLibre (for example, it comes from Mapbox GL JS).
• describe_sources: Reads the TileJSON, PMTiles header, or GeoJSON of each source in the style, lists source layers and fields, and finds layers that use nonexistent source layers or fields.
• inspect_tile: Reads the vector tile at a location, listing each source layer and its geometry type, field values and their frequencies, several example features, as well as the source's zoom range and the source layers missing from the tile. The source can be a source in the style, a TileJSON URL (such as a Martin source), a PMTiles archive, or a tile URL, supporting MVT or MLT tiles.
• debug_layers: Determines whether each layer of the style is drawn at a location and zoom level, and if not, explains why, such as a missing source layer, a filter that cannot match (and compares it against the actual values in the data), a fill layer with no polygons, a draw result of 0 or transparent, or a missing icon in the sprite; it also indicates when text falls back to a local font because the glyph server lacks its font stack.
• render_style: Renders the style to a PNG and reports map errors, missing fonts, and missing icons. You can specify the center, zoom, bearing, and pitch, or fit to bounds, or specify the camera position and look-at point on 3D terrain.
• preview_style: Gives the user a live interactive map link. The map updates as the style file changes; agents with no file to write can send the modified style to the same link.
• render_page: Renders a web page containing a map, suitable for content that a style cannot carry, such as plugins, controls, and page code. It reports page errors and failed requests, and can run scripts in the page first.
• compare_styles: renders two versions of a style with the same camera, returning an image containing before, after, and the differences marked in red.
• compare_renderers: does the same comparison for the same website in two renderers, for example checking whether a style looks consistent on web and mobile.
• show_map: in clients that support MCP Apps, shows the user an interactive map with GeoJSON layers and markers, using OpenFreeMap as the basemap.
• martin_list_sources: lists the tiles, sprites, fonts, and styles provided by a Martin server, along with the URLs that should be used in styles.
• search_ecosystem: searches Make with MapLibre for SDKs, plugins, routing, geocoding, style and tile libraries, hosted APIs, products, and consulting services, filterable by type and platform, with links and live demos.
• find_basemaps: lists the basemaps in Make with MapLibre along with their style URLs or tile sources, whether an API key is required, and the attribution or logo required by the provider.

The data in Make with MapLibre is copyright © Birk Skyum, licensed under CC BY 4.0, and both tools include this attribution at the end.

Usage

Tools that accept a style support passing it as an object (style), a URL (url), or a file (path, relative to where the server is running). If any renderer is enabled, render_style and compare_styles are available; if two or more renderers are enabled, compare_renderers is also available. Rendering with MapLibre Native requires an additional package, and rendering with Martin requires a Martin build with rendering capability.

On the command line, images are output to map.png, compare.png, and renderers.png, or specified via --out. npx -y maplibre-mcp --help lists the options. To validate, format, or migrate styles, you can use gl-style-validate, gl-style-format, and gl-style-migrate from @maplibre/maplibre-gl-style-spec.

--http serves Streamable HTTP at http://127.0.0.1:3100/mcp instead of stdio, and --host and --port can change the address. On a loopback address, it only responds to requests from localhost; on other addresses, it does not read or write files, still fetches the given URLs from the network it is on, and has no authentication, so it should be placed behind an authenticated proxy.

Use cases and limitations

Suitable for editing map styles in chat and observing them in real time, troubleshooting layers that do not draw, and giving agents in shell-less sandboxes or chat applications map operation capabilities. Requires Node.js 22 or newer; GL JS rendering depends on Chrome or Chromium, and environments where a browser cannot be installed need to use a container image; Native and Martin rendering require additional dependencies; HTTP mode has no authentication on non-loopback addresses, so you need to add your own proxy protection.

License

MIT © 2026 Birk Skyum.