maplibre-mcp

Name: maplibre-mcp
Author: birkskyum

本地服务

birkskyum.github.io开发工具23 周前更新

代码仓库访问官网

关于 maplibre-mcp

maplibre-mcp 是面向使用 MapLibre 样式的编码 Agent 和开发者的 MCP 服务，结合渲染、校验、数据检查与实时预览，便于从视觉和诊断层面检查样式。

主要功能

01按 MapLibre 规范校验样式
02渲染样式并比较版本或渲染器
03检查数据源、瓦片和图层行为
04在交互式地图中实时预览修改
05查询 MapLibre GL JS 和生态资料

适用场景

01编辑样式时检查渲染结果
02诊断地图图层不显示的原因
03比较修改前后的样式

MCP 相关

该 MCP 服务向 MCP 客户端提供 MapLibre 样式、渲染、检查、预览和参考查询工具，支持 stdio 与 Streamable HTTP。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "birkskyum-maplibre": {
      "command": "npx",
      "args": [
        "-y",
        "maplibre-mcp"
      ],
      "env": {
        "MAPLIBRE_MCP_TOOLSETS": "<MAPLIBRE_MCP_TOOLSETS>",
        "MARTIN_URL": "<MARTIN_URL>"
      }
    }
  }
}

启动命令npx -y maplibre-mcp

需要配置的环境变量

MAPLIBRE_MCP_TOOLSETSThe toolsets to turn on, comma separated, like style,gl-js,martin. Defaults to style,gl-js, and all turns on every toolset.

MARTIN_URLThe Martin server that the martin toolset reads and renders with. Defaults to http://localhost:3000.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmmaplibre-mcp0.9.2stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
url	string	否	样式 JSON 文档的 URL。
path	string	否	相对于服务器运行目录的样式 JSON 文件路径。
style	object	否	作为 JSON 对象的样式。

详细介绍

maplibre-mcp

一个 MCP 服务，让 AI Agent 能查看自己正在处理的 MapLibre 地图、检查地图，并展示给你。

一幅阿尔卑斯山的 3D 徒步地图，马特洪峰映衬在傍晚的天空下

Agent 通过一条提示词制作的徒步地图样式，由位于采尔马特上方的相机使用 render_style 渲染。

编码 Agent 可以编写 MapLibre 样式，却看不到地图。因此，它只能把未经测试的成果交给你，或者先花几分钟自行搭建渲染器；它还会依赖记忆中的东西，比如较旧的 MapLibre GL JS 或 Mapbox。借助 maplibre-mcp，Agent 可以渲染样式、查看图像并修复发现的问题；你则会获得一个实时地图链接，随着它编辑文件而重新绘制。它在你的机器上运行，无需 API 密钥。

它擅长两件事：

通过聊天编辑样式，同时看着地图变化。“把水域颜色调深些”“让村庄里的小径变细”。Agent 编辑文件并检查渲染结果，已打开的地图也会同步更新。
**查明图层为何没有绘制。**Agent 读取真实图块，查看某个位置有哪些图层绘制出来、其他图层为何没有，然后修复筛选器。

无法在沙盒或聊天应用中使用命令行来构建自有工具的 Agent，最能从中受益。

网站 · 快速入门 · 示例 · 工具

安装

需要 Node.js 22 或更高版本。

客户端	命令
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 和大多数其他客户端都会读取此 JSON。快速入门说明了每个客户端的配置文件存放位置。

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

使用 MapLibre GL JS 渲染时会调用已安装的 Google Chrome。如果没有 Chrome，首次渲染会失败，并提示安装可替代使用的 Chromium 的命令。

在无法安装浏览器的沙盒或 CI 环境中，请使用容器镜像 ghcr.io/birkskyum/maplibre-mcp，其中包含该服务和 Chromium。容器与沙盒介绍了具体用法。

命令行

在命令行中工作的 Agent 和用户，也可以直接将渲染、数据工具以及 GL JS API 查询作为命令运行，无需配置 MCP。样式可以是文件，也可以是 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

图像会输出到 map.png、compare.png 和 renderers.png，也可以输出到 --out 指定的位置。npx -y maplibre-mcp --help 会列出可用选项；命令行中有详细说明。要验证、格式化或迁移样式，请使用 @maplibre/maplibre-gl-style-spec 中的 gl-style-validate、gl-style-format 和 gl-style-migrate。

工具

validate_style 根据 MapLibre 样式规范检查样式，并列出每个问题及其属性路径。
describe_style_spec 查询图层类型、属性、数据源类型或表达式，并提供其文档以及支持它的 GL JS 和 Native 版本。遇到拼写错误的名称时，它会建议最接近的有效名称。
describe_gl_js_api 在服务器所用版本或其他版本的类型定义中查询 MapLibre GL JS 的类、方法、选项或事件，并提供其签名、文档、默认值和示例。它还会指出某个方法是否并非 MapLibre 所有，例如来自 Mapbox GL JS。
describe_sources 读取样式中每个数据源的 TileJSON、PMTiles 标头或 GeoJSON，列出源图层和字段，并查找使用了不存在的源图层或字段的数据图层。
inspect_tile 读取某个位置的矢量瓦片，并列出每个源图层的几何类型、字段值及其出现频率，以及几个示例要素；还会提供数据源的缩放级别范围，以及瓦片中缺少的源图层。数据源可以是样式中的数据源、类似 Martin 数据源的 TileJSON URL、PMTiles 存档或瓦片 URL，瓦片格式可以是 MVT 或 MLT。
debug_layers 针对样式中的每个图层，说明它在某个位置和缩放级别下是否会绘制；如果不会，则说明原因，例如缺少源图层、筛选器匹配不到任何内容（并列出数据中的值）、填充图层没有多边形、绘制属性的结果为 0 或透明，或精灵中缺少图标。它还会指出回退到本地字体的文本，因为字形服务器缺少对应的字体栈。
render_style 将样式渲染为 PNG，并报告地图错误、缺失的字体和图标。它可以接收中心点、缩放级别、方位角和倾斜角、用于适配的边界框，或相机位置及其在 3D 地形上要观察的点。
preview_style 为用户提供样式的实时交互式地图链接。地图会随样式文件的变化而更新；无法写入文件的 Agent 可以将更改后的样式发送到同一链接。
render_page 渲染带有地图的网页，适用于样式无法承载的内容，例如插件、控件和页面代码。它会报告页面错误和请求失败，还可以先在页面中运行脚本。
compare_styles 在相同相机视角下渲染样式的两个版本，并返回一张图像，其中包含更改前、更改后以及以红色显示的差异。
compare_renderers 对同一个样式使用两个渲染器执行相同操作，例如检查样式在 Web 和移动设备上的外观是否一致。
show_map 在支持 MCP Apps 的客户端中，向用户展示一张交互式地图，其中包含 GeoJSON 图层和标记，底图来自 OpenFreeMap。
martin_list_sources 列出 Martin 服务提供的瓦片、精灵、字体和样式，以及在样式中使用的 URL。
search_ecosystem 搜索 Make with MapLibre 中的 SDK、插件、路径规划、地理编码、样式和瓦片处理库、托管 API、产品和咨询服务，并按类型和平台筛选，同时提供链接和实时演示。
find_basemaps 列出 Make with MapLibre 中的底图及其样式 URL 或瓦片数据源、是否需要 API 密钥，以及提供商要求在地图上显示的署名或标志。

Make with MapLibre 的数据版权归 Birk Skyum 所有，采用 CC BY 4.0 许可；两个工具的结果末尾都会附上其署名。

接受样式的工具可以通过对象（style）、URL（url）或文件（path，相对于服务器的运行位置）接收样式。工具参考列出了所有参数。

工具集

工具按其所属的 MapLibre 项目分组。默认启用 style、gl-js 和 ecosystem。使用 --toolsets 或 MAPLIBRE_MCP_TOOLSETS 环境变量选择其他工具集，使用 all 可启用所有工具集：

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

工具集	新增内容
`style`	`validate_style`、`describe_style_spec`、`describe_sources`、`inspect_tile`、`debug_layers`
`gl-js`	使用 MapLibre GL JS 渲染、`render_page`、`preview_style`、`describe_gl_js_api` 和 `show_map`
`native`	使用 MapLibre Native 渲染
`martin`	使用 Martin 服务渲染，以及 `martin_list_sources`
`ecosystem`	`search_ecosystem` 和 `find_basemaps`，用于读取 Make with MapLibre 的目录

启用任意渲染器后，即可使用 render_style 和 compare_styles；启用两个或更多渲染器后，还可使用 compare_renderers。使用 MapLibre Native 渲染需要额外安装一个软件包；使用 Martin 渲染则需要带渲染功能的 Martin 构建版本。渲染介绍了这两种情况。

远程服务

--http 会在 http://127.0.0.1:3100/mcp 提供 Streamable HTTP 服务，而不是使用 stdio；--host 和 --port 可更改地址。对于回环地址，服务只响应来自 localhost 的请求。对于其他地址，服务不会读取或写入文件，但仍会从自身网络获取提供给它的 URL，并且没有身份验证，因此请将其置于带有身份验证的代理之后。远程服务中有详细说明。

开发

npm install
npm test
npm run dev:site

许可证

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

maplibre-mcp

关于 maplibre-mcp

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

maplibre-mcp

安装

命令行

工具

工具集

远程服务

开发

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？