Mapsi Mcp

mapsi-mcp

适用于 Mapsi 的 MCP 服务 — 为 AI 编码助手提供 18 种地理空间工具。将 Claude Code、Cursor、Windsurf 或任何兼容 MCP 的 IDE 直接连接到 Mapsi API。

基于 OpenStreetMap · 可自托管的基础设施 · 不受 Google Maps 供应商锁定

快速开始

1. 获取 API 密钥，访问 mapsi.dev/console/api-keys（免费套餐：每天 1,000 次调用，无需信用卡）

2. 将配置添加到 IDE：

Claude Code / Claude Desktop

添加到 ~/.claude.json（或项目根目录中的 .mcp.json）：

{
  "mcpServers": {
    "mapsi": {
      "command": "npx",
      "args": ["-y", "mapsi-mcp"],
      "env": { "MAPSI_API_KEY": "msk_your_key_here" }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mapsi": {
      "command": "npx",
      "args": ["-y", "mapsi-mcp"],
      "env": { "MAPSI_API_KEY": "msk_your_key_here" }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json — JSON 格式与上方 Cursor 配置相同。

VS Code + Cline

打开 Cline 设置 → MCP Servers → Add server → 粘贴：

{
  "mapsi": {
    "command": "npx",
    "args": ["-y", "mapsi-mcp"],
    "env": { "MAPSI_API_KEY": "msk_your_key_here" }
  }
}

Zed

在 Zed 设置的 "context_servers" 下添加：

{
  "mapsi-mcp": {
    "command": { "path": "npx", "args": ["-y", "mapsi-mcp"] },
    "env": { "MAPSI_API_KEY": "msk_your_key_here" }
  }
}

3. 重启 IDE — 然后用自然语言向 AI 提问。

---

可以向 AI 提出哪些请求

Geocode all addresses in my CSV and add lat/lon columns
Build an address autocomplete input for this React form using Mapsi
Draw a 20-minute drive isochrone from our warehouse at this coordinate
Find the 5 nearest hospitals to this coordinate
Migrate this Google Maps geocoding call to Mapsi
Add a MapLibre map with Mapsi light tiles and drop markers from this array
Calculate a distance matrix between 10 warehouses and 50 delivery stops
Snap this GPS trace to the road network and calculate total distance

---

可用工具（18 种）

地理编码

工具	描述
geocode	地址或地点名称 → 纬度/经度。返回置信度分数（0–1）；低于 0.6 的分数应视为存在歧义。
reverse_geocode	纬度/经度 → 格式化地址、街道、城市、邮编、国家/地区。
autocomplete	用户输入时实时提供地址建议（至少 2 个字符）。适用于 UI 输入字段。
normalize_address	规范化杂乱或不一致的地址。返回结构化字段和坐标。
timezone	任意坐标对应的 IANA 时区名称、UTC 偏移量和夏令时状态。
elevation	任意坐标的海拔（米）（全球分辨率约为 30 米）。

路线规划

工具	描述
route	转弯导航。模式：auto、truck、bicycle、pedestrian、motor_scooter。
isochrone	N 分钟或 N 米范围内的可达区域多边形。返回适用于 MapLibre/Leaflet 的 GeoJSON。
matrix	一次调用即可计算最多 50×50 个起点-终点组合的行程时间和距离矩阵。
map_match	将 GPS 轨迹匹配到道路网络。坐标顺序为 [lon, lat]（GeoJSON）。
nearest_road	查找最近的可导航道路点。如果 route 返回“no route found”，请调用此工具。

地点

工具	描述
places_search	按类别查找附近的兴趣点（餐厅、医院、药店、ATM 等）。返回名称、坐标和类别。

空间

工具	描述
point_in_polygon	查询坐标对应的行政区划层级：国家/地区、区域、城市、街区。
h3_index	将坐标转换为分辨率 0–15 的 H3 六边形网格单元。

批处理

工具	描述
batch_geocode	一次调用即可对最多 30,000 个地址进行地理编码。批量处理数据时，切勿循环调用 geocode。
batch_reverse_geocode	一次调用即可对多个坐标进行反向地理编码。

瓦片

工具	描述
get_tile_style_url	MapLibre GL 样式 URL。样式：light、dark、streets、topo、grayscale、black、white、liberty。
get_static_map_url	静态 PNG 地图 URL，可用于 <img> 标签、电子邮件和 PDF。

---

身份验证

• API 调用： X-API-Key 请求头（由 MCP 服务自动处理）
• 瓦片 URL： ?key= 查询参数（适用于浏览器；由 get_tile_style_url 返回）

---

Agent 常用模式

地理编码一次，重复使用结果：

Don't re-geocode the same address twice within a session. Cache the lat/lon and pass it directly to route, isochrone, and places_search.

批量数据 → 使用批处理工具：

For more than 1 address or coordinate pair, always use batch_geocode / batch_reverse_geocode.

路线规划失败 → 先调用 nearest_road：

If route returns an error near the origin or destination, call nearest_road to snap the point to a routable road, then retry route with the snapped coordinates.

等时圈 — 时间还是距离：

Use contours_minutes for time-based reachability (delivery ETAs, commute zones).
Use contours_meters for fixed-radius circles on the road network.
Provide only one, not both.

---

定价

套餐	每日调用次数	批次大小
免费	1,000	10
Growth	50,000	5,000
Business	无限制	30,000

完整定价请访问 mapsi.dev/pricing

---

Links

• Website: mapsi.dev
• API docs: mapsi.dev/docs
• AI prompts: mapsi.dev/prompts-for-ai
• npm: npmjs.com/package/mapsi-mcp
• GitHub: github.com/algolayer/mapsi-mcp
• Support: [email protected]

---

License

MIT — algolayer.com