maproll

@maproll/mcp

让 AI 助手制作真实地图。每张地图都会以 maproll URL 的形式返回——永久有效、可嵌入，也是进行下一次修改的入口。

这张图片并非本仓库中的文件，而是由 maproll URL 实时渲染的，这正是核心理念：URL 就是地图。

安装

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

其他客户端也使用相同命令作为配置——Claude Desktop、Cursor （.cursor/mcp.json）、VS Code（"servers" 下的 .vscode/mcp.json）：

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

需要 Node 20 或更高版本。无需 API 密钥、注册或账户——服务会按需从 npm 运行，并与公共渲染 API 通信。

试用

用下面这些话，或你自己的说法，向助手提问：

绘制人均咖啡消费量最高的十个国家的地图。

在浅色地图上突出显示欧盟成员国。

绘制从上海到鹿特丹的海上航线，并标出港口。

在深色地图上对比 NATO 和 BRICS 成员国，并给我一个可嵌入的 URL。

如果只试一个，就试第三个。海上航线会经过苏伊士、巴拿马和马六甲，而不是横穿亚洲画一条直线：

工具

create_map

根据你的数据制作地图。数值会生成分级统计图，颜色会为区域填充纯色，文本值会生成定性分组，而 highlight 则适用于关注的是哪些区域，而非数量多少的情况。

世界范围使用 ISO 3166-1 alpha-2 区域 ID（US、DE、BR），国家范围内使用 ISO 3166-2（RO-B、RO-CJ）。数据以结构化形式传入——URL 语法由服务负责处理，因此模型无需手动拼接 US:200:#ff0000。

add_layers

在已有地图上添加标记、路线、比例圆、图案填充、注释和标签。它接收该地图的 URL 并追加图层——因此，也可以在多轮对话中逐步构建地图，而不必每次都从头重建。

find_places

将地点名称解析为真实坐标及 maproll 使用的 ID。支持国家、地区、城市和机场，并提供各自的 ISO 3166-1 / 3166-2 / IATA 代码。

建议在添加每个标记前使用。凭记忆填写的坐标常常会差好几度，而地图对错误标记的绘制，会和正确标记一样笃定。

describe_options

列出渲染器实际接受的范围、主题、标记图标、投影和图案填充。使用不存在的主题或图标名称不会显示任何内容，也不会报告错误，因此先检查比猜测更可靠。

返回内容

每个制作地图的工具都会返回渲染后的 PNG 供查看，此外还会返回：

字段	含义
svg_url	地图。可嵌入、永久有效，也是其他工具接受的入口。
png_url	同一张地图的 PNG 版本。
editor_url	在 maproll 编辑器中打开地图，地图已加载且可编辑。
embed	可直接使用的 <img> 标签。
warnings	非致命问题，例如渲染器无法识别的区域 ID。

为什么 URL 就是地图

Agent 通常会返回一个产物：一个文件、一个数据块，或只存在于对话中的某种内容。maproll 返回的是一个地址。

prompt → assistant → maproll MCP → https://api.maproll.io/map.svg?…
                                        ↓
              README · docs · dashboard · newsletter · the next tool call

无需会话，也无需保存状态，因为 svg_url 就是状态。将它传给 add_layers，便会返回一条已应用新增图层的新 URL。每个步骤生成的 URL 都会永久有效，并且无需 JavaScript 就能在 <img> 标签中渲染。

品牌标识和密钥

无需账号即可使用 Maps。匿名使用的代价是品牌标识：此服务生成的每张地图都会在角落带有小小的 maproll 标记。

密钥可以移除该标记。在编辑器 app.maproll.io → API keys 中创建密钥，并将其传入服务的环境变量：

{
  "mcpServers": {
    "maproll": {
      "command": "npx",
      "args": ["-y", "@maproll/mcp"],
      "env": { "MAPROLL_API_KEY": "mr_live_…" }
    }
  }
}

使用密钥后，返回的 URL 会附带与对应地图绑定的签名，因此嵌入地图无论发布在哪里都能干净呈现——密钥本身绝不会出现在别人可以复制的链接中。有两点值得注意：密钥在 90 天后过期；密钥过期后，使用该密钥发布的嵌入地图会重新显示品牌标识。如果这点很重要，请重新生成地图。

无论是否使用密钥，都必须注明 OpenStreetMap 来源。这是许可义务，不是品牌要求。

变量	默认值	用途
MAPROLL_API_KEY	—	授权渲染，并移除品牌标识。
MAPROLL_PLACES_URL	https://mcp.maproll.io/places	find_places 用于解析地点名称的地址。仅在本地开发时覆盖。

资源和提示词

七个只读资源提供模型原本需要猜测的目录，尤其是 maproll://grammar，以及范围、主题、图标、投影和图案列表，还有一组完整示例。

此服务附带三个提示词：mapped_episode（采用 Mapped 风格的数据集）、readme_map（一张地图，以及包含真实替代文本、可直接粘贴的代码片段）和 refine_map（用通俗英语修改现有地图）。

文档

• maproll.io/mcp — 一页介绍本工具。
• docs.maproll.io/docs/mcp/intro — 各客户端的安装说明、每个工具的架构和使用方法。
• 已在 MCP Registry 中列出，名称为 io.maproll/maproll。

开发

项目结构、本地开发流程和端到端冒烟测试请参阅 DEVELOPMENT.md。发布说明见 PUBLISHING.md。

采用 MIT 许可。