Ultimaps

@ultimaps/mcp

适用于 Ultimaps 的 MCP 服务。向 Claude、Codex 或任何 MCP 客户端询问地图，即可在对话中获取图片。支持根据粘贴的数据绘制分级统计地图、类别地图和标记位置，适用于国家、州、省、县、大洲和世界。

“按人口绘制美国各州地图。” · “按货币为欧盟成员国着色。” · “用这些失业率展示法国各大区：……” · “在欧洲地图上标出我们的五个办公室。”

无需账户。未设置 API 密钥时，服务会使用无密钥套餐。设置 ULTIMAPS_API_KEY 即可使用套餐配额，并生成尺寸更大或不带品牌标识的输出。

无法运行本地命令？ 在 ChatGPT（开发者模式）、claude.ai 或任何可连接远程 MCP 服务的客户端中，改为添加托管服务：https://api.ultimaps.com/mcp。在 ChatGPT 中，需要在每个想查看地图的对话中启用它。它提供相同的三个工具，无需安装任何内容。请参阅托管服务。本软件包是本地版本：请求来自你自己的 IP 地址，并使用你自己的密钥；每张图片都会保存到你电脑上的文件中。

工具

工具	功能
render_map	将地图渲染为图片（PNG；使用 Pro 密钥时可生成 SVG），图片足够小时会以内嵌形式显示。支持分级统计地图（数值）、类别（标签）或指定颜色，也支持标记、标题、带独立标题的图例、主题、区域标签（名称、数值或两者）及其他图层。区域名称采用模糊匹配；任何修正或未匹配项都会附带建议报告。dryRun: true 可在渲染前预览匹配结果和配色方案。
list_maps	地图目录：{id, title, regionType, layers, regionCount, labels}，可使用 query 搜索。
get_map_regions	获取单张地图的区域键和标题，每页 200 条；可按键、标题或别名搜索。

这三个工具均为只读。Agent 很少需要使用发现工具：render_map 可直接接受区域名称、代码和别名。

安装

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

Claude Code

claude mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
claude mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcp

Codex

codex mcp add ultimaps -- npx -y @ultimaps/mcp
# with a key:
codex mcp add ultimaps --env ULTIMAPS_API_KEY=um_live_… -- npx -y @ultimaps/mcp

Codex 使用 TOML，而不是下面的 JSON。等效配置项可写入 ~/.codex/config.toml（或受信任项目中的 .codex/config.toml）：

[mcp_servers.ultimaps]
command = "npx"
args = ["-y", "@ultimaps/mcp"]

Claude Desktop

从最新版本下载 ultimaps-<version>.mcpb 并打开：Claude Desktop 会一键安装，并询问是否提供可选的 API 密钥。或者将以下内容添加到 claude_desktop_config.json：

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

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

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

VS Code

.vscode/mcp.json：

{
  "servers": {
    "ultimaps": { "type": "stdio", "command": "npx", "args": ["-y", "@ultimaps/mcp"] }
  }
}

托管服务

使用托管服务无需安装本软件包。将 URL 添加到你的客户端：

claude mcp add --transport http ultimaps https://api.ultimaps.com/mcp
# with a key:
claude mcp add --transport http ultimaps https://api.ultimaps.com/mcp \
  --header "Authorization: Bearer um_live_…"

使用配置文件的客户端只需填写 URL，例如 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "ultimaps": { "url": "https://api.ultimaps.com/mcp" }
  }
}

托管服务通过 Authorization 标头传递密钥，而不是使用 ULTIMAPS_API_KEY。在 ChatGPT 和 claude.ai 中无法设置标头，因此其中的渲染使用匿名套餐：带署名的 PNG，最大 1600 px；每个对话每小时最多 30 次。每次渲染还会返回一个图片链接，该链接 30 天后过期。对于无法在对话中显示的大图片，以及所有 SVG，服务只会返回链接。ChatGPT 不会显示工具返回的图片，因此你需要通过链接查看地图。

配置

变量	默认值	用途
ULTIMAPS_API_KEY	无（无密钥）	从 Studio → Workspace → API 获取 API 密钥。无效密钥会报错，不会回退到无密钥模式。
ULTIMAPS_API_URL	https://api.ultimaps.com	开发期间指向本地 API（http://localhost:3001）。仅接受 localhost 上的纯 http。

限额

	无密钥	免费密钥	Pro 密钥
渲染次数	30 次/小时，5 次/分钟	500 次/月，50 次/天，10 次/分钟	5,000 次/月，1,000 次/天，30 次/分钟
输出	PNG，最大 1600 px，带署名	PNG，最大 1600 px，缩放比例为 2（栅格图像为 3200 px），带署名	PNG，最大 4000 px，缩放比例为 4；SVG；不带署名

工作区内的所有密钥共用每月配额。每日和每分钟上限按密钥计算，因此免费密钥每天渲染 50 次后就会停止，远在当月配额用完之前。

试运行不会占用每月配额，但仍计入速率限制。当无密钥渲染次数在一小时内剩余不超过 5 次时，结果会提示这一点。

渲染结果

• 图像：图像足够小时会以内嵌形式返回（PNG 不超过 781 KB，SVG 不超过 98 KB）。默认的 1200 px 宽度通常符合要求。每次渲染也会写入 <tmpdir>/ultimaps-mcp/，结果中会包含文件路径，因此在终端客户端中，实际可打开的就是该文件。系统不会代你重新渲染或重采样。
• 文本报告：包含自动更正和未匹配的区域键及建议、已解析的分级统计地图方案、警告（例如 layer_unavailable 或 labels_overlap）、用于在 Ultimaps Studio 中打开地图进行编辑的链接，以及供支持人员查询的渲染 ID。
• 可嵌入的图像 URL：无密钥 PNG 渲染在完整规格适合约 2,000 个字符的 URL 时会提供此链接，因此仅适用于小型数据集。URL 中包含规格而非图像，并且以无密钥方式渲染，因此设置了密钥时不会提供。
• structuredContent：以数据形式提供相同的报告，具体定义见工具的 outputSchema。

隐私政策

此服务在你的机器上运行，不会自行收集遥测数据，且只与 Ultimaps API 通信（https://api.ultimaps.com，或你设置的 ULTIMAPS_API_URL）。完整的 Ultimaps 隐私政策见 ultimaps.com/privacy-policy。

发送给 Ultimaps 的信息。 工具调用是发往 Ultimaps API 的普通 HTTPS 请求，因此请求会携带你的 IP 地址，并使用 ultimaps-mcp/<version> 用户代理。render_map 会发送完整的地图请求：区域键和值、图钉、标题和样式。如果设置了 ULTIMAPS_API_KEY，它只会随渲染请求发送。

Ultimaps 保留的信息。 每个渲染请求都会被记录：请求内容、地图和结果、耗时、你的 IP 地址和用户代理；对于使用密钥的请求，还会记录使用了哪个密钥和工作区。这便于支持人员查询渲染 ID、让“在 Studio 中打开”链接重建地图，并统计用量。请求内容会保留 30 天，IP 地址和用户代理会保留 90 天。之后仅保留用量记录；若使用了密钥，该记录会关联到你的工作区。Ultimaps 使用的第三方错误监控服务可能会收到失败请求的详细信息。Ultimaps 不会出售这些数据，也不会将其用于广告。

保留在你机器上的信息。 每张渲染后的图像都会写入 <tmpdir>/ultimaps-mcp/，此服务绝不会删除这些文件。你的 MCP 客户端保留的信息（包括对话中的工具结果）受其自身隐私政策约束。

可分享链接。 为小型无密钥渲染提供的可嵌入图像 URL 包含完整的地图请求。任何获得该链接的人都可以查看其中的内容。

托管服务。 https://api.ultimaps.com/mcp 上的服务运行在 Ultimaps 的服务器上，而非你的机器上，因此上文关于你机器的说明不适用于它。完整的隐私政策也涵盖该服务。

如有疑问或需删除数据，请发送邮件至：[email protected]，并注明渲染 ID。

开发

npm install
npm run typecheck
npm test           # unit + in-process protocol tests
npm run build      # → dist/

通过 stdio 对真实 API 进行端到端测试（会消耗你套餐中的渲染单位）：

npm run build
node scripts/smoke.mjs

src/generated/render-request.schema.json 根据 Ultimaps API 契约生成；请勿手动编辑。工具和属性的说明位于 src/descriptions.ts。参数不会在本地验证：API 仅支持新增，且其 400 响应会提供建议。

欢迎提交问题和拉取请求。版本由 Ultimaps 团队发布，已接受的更改会随下一个版本发布。

该软件包仅发布一个 bin，不包含其他内容。不支持 import '@ultimaps/mcp'，且会因模块名称而失败，因为 dist/index.js 在加载时会启动一个 stdio 服务。

许可证

MIT © Ultimaps。详见 LICENSE。