适合谁
- 需要地理编码、POI 搜索、路线规划等真实地图数据的 AI 应用开发者
- 物流、出行、地产选址等需要离线几何计算(面积、缓冲区、并交差集)的场景
- 使用 Claude Desktop、VS Code Copilot、Claude Code 或 Goose 等支持 MCP Apps 的客户端，希望获得可视化地图展示的用户
M
71FMRS · B
Mapbox MCP Server 由 Mapbox 官方维护，将地理编码、POI 搜索、路线规划、等时圈、地图渲染及大量离线几何计算工具整合进一个 MCP 服务，功能覆盖全面，但强依赖 Mapbox 访问令牌与网络连接，敏感位置数据会发送至 Mapbox API。
Mapbox MCP Server 是由 Mapbox 官方维护的 Node.js 服务器，通过 Model Context Protocol 把地理编码、兴趣点(POI)搜索、多种出行方式的路线规划、行程时间矩阵、路线优化(旅行商问题)、GPS 轨迹匹配、等时圈(isochrone)分析、静态/交互式地图渲染，以及基于 Turf.js 的离线几何计算(距离、面积、方位角、缓冲区、并集/交集/差集等)整合到一个 MCP 服务中。既可通过 npm 包以本地 stdio 方式运行，也可直接使用 Mapbox 官方托管的 streamable-http 端点，两种方式都需要提供 Mapbox 访问令牌。
工具能力
resource_reader_tool
为不支持原生 MCP 资源的客户端提供读取资源(如分类列表)的兜底工具。
category_list_tool
(已弃用)提供搜索分类 ID 列表，建议改用 resource_reader_tool 或原生资源接口。
distance_tool
使用 Haversine 公式离线计算两个坐标之间的大圆距离，支持多种单位。
points_within_polygon_tool
判断一个或一批点是否位于给定多边形/复合多边形内部，适用于地理围栏和配送范围校验。
destination_tool
根据起点、方位角和距离，用大圆偏移离线计算目标点坐标。
bearing_tool
计算两个坐标之间的罗盘方位角(0-360°)及对应的方向。
midpoint_tool
沿大圆路径计算两个坐标之间的地理中点。
centroid_tool
计算多边形或复合多边形的几何中心(质心)。
area_tool
计算多边形面积，支持平方米、平方公里、英亩等多种单位。
bounding_box_tool
计算点、线、面或复合几何的最小外接矩形范围。
buffer_tool
围绕点、线或面生成指定距离的缓冲区多边形。
simplify_tool
使用 Douglas-Peucker 算法减少线或面的顶点数量以简化几何。
length_tool
测量由一系列坐标组成的线的总长度。
convex_tool
计算一组点的凸包，即包含所有点的最小凸多边形。
nearest_point_tool
在一组候选点中找到距离目标点最近的点。
nearest_point_on_line_tool
将目标点吸附到线或路线上最近的位置，并返回距离。
union_tool
将多个多边形合并为一个几何图形。
intersect_tool
计算多个多边形的重叠(相交)区域。
difference_tool
从一个多边形中减去另一个多边形，得到差集区域。
matrix_tool
调用 Mapbox Matrix API 计算多个地点之间的行程时间和距离矩阵，支持多种出行方式和出发时间设置。
static_map_image_tool
调用 Mapbox 静态地图 API 生成带标记、路线和多边形叠加的静态地图图片(PNG/JPEG)。
category_search_tool
调用 Mapbox Search Box 分类搜索 API，按类别(餐厅、酒店、加油站等)搜索兴趣点。
reverse_geocode_tool
调用 Mapbox 地理编码 V6 API，将坐标转换为可读地址及位置上下文信息。
ground_location_tool
针对某个坐标一次性回答“附近有什么”，综合逆地理编码、分类搜索和等时圈，返回带引用来源的结果。
place_details_tool
根据 Mapbox ID 获取地点的详细信息，包括照片、营业时间、评分、电话和网站。
directions_tool
调用 Mapbox Directions API 获取驾车、步行、骑行的路线规划，支持多途经点、实时路况和排除条件。
isochrone_tool
调用 Mapbox Isochrone API 计算在指定时间或距离内可达的区域范围。
search_and_geocode_tool
调用 Mapbox Search Box 文本搜索 API，用于搜索并地理编码兴趣点、地址和地点。
map_matching_tool
调用 Mapbox Map Matching API 将带噪声的 GPS 轨迹吸附到实际路网上。
optimization_tool
调用 Mapbox Optimization API 求解多地点最优访问顺序(旅行商问题)。
render_map_tool
通过 MCP Apps 协议在聊天界面内渲染可交互的 Mapbox GL JS 地图，可展示路线、搜索结果或自定义 GeoJSON。
安装接入
- 在 mapbox.com/signup 注册 Mapbox 账号，在账号页面创建或使用默认的访问令牌。
- 若使用本地方式，在 MCP 客户端配置中添加通过 npx 启动的 @mapbox/mcp-server，并设置环境变量 MAPBOX_ACCESS_TOKEN。
- 若不想本地运行，可直接将客户端指向官方托管端点 https://mcp.mapbox.com/mcp(streamable-http)。
- 若客户端不支持 MCP 资源(如 smolagents)，设置 CLIENT_NEEDS_RESOURCE_FALLBACK=true 以启用资源兜底工具。
- 重启客户端并测试地理编码或路线查询确认连接成功。
claude_desktop_config.json
{"mcpServers": {"mapbox": {"command": "npx", "args": ["-y", "@mapbox/mcp-server"], "env": {"MAPBOX_ACCESS_TOKEN": "YOUR_MAPBOX_ACCESS_TOKEN"}}}}
选型与风险
不适合谁
- 没有 Mapbox 账号或不愿申请访问令牌的用户
- 需要完全离线、不依赖任何外部 API 的地理编码/路线场景(仅部分几何计算工具支持离线)
- 需要车队级多车辆、时间窗和容量约束优化的场景(V2 优化 API 需 beta 权限，默认未注册)
所需权限
- 需要一个有效的 Mapbox 访问令牌(MAPBOX_ACCESS_TOKEN)，以环境变量形式提供，标记为敏感信息
- 本地 stdio 方式下需要网络访问权限以调用 Mapbox 各类 API
- 使用官方托管端点时需要网络访问 https://mcp.mapbox.com/mcp
风险与副作用
- Mapbox 访问令牌一旦泄露可能被滥用，产生额外 API 调用费用或超出配额
- 地理编码、搜索、路线等工具会把地址、坐标、路线偏好等位置数据发送给 Mapbox API，需符合 Mapbox 隐私政策
- render_map_tool 依赖客户端支持 MCP Apps 协议渲染 HTML 面板，若客户端不受信任的富内容处理存在缺陷可能带来风险
- V2 优化等高级功能虽在代码中但默认未注册，误启用需额外 beta 权限
常见排障
- 确认已正确设置 MAPBOX_ACCESS_TOKEN 且令牌未过期、具备所需 API 权限范围
- 若工具调用失败，检查网络是否可访问 api.mapbox.com 或 mcp.mapbox.com
- 客户端若不支持 MCP 资源(如部分早期或第三方客户端)，设置 CLIENT_NEEDS_RESOURCE_FALLBACK=true 启用 resource_reader_tool 等兜底工具
- 若地图渲染未显示，确认客户端支持 MCP Apps(如 Claude Desktop、VS Code Copilot、Claude Code、Goose)，否则改用 static_map_image_tool 获取静态图片
- 版本升级或功能异常时，检查 package.json、manifest.json 与 server.json 中的版本号是否一致
使用场景
构建具备地理位置理解能力的 AI 出行助手或位置推荐应用
在物流场景中做行程时间矩阵分析和多点配送路线优化
清洗 GPS 轨迹并吸附到路网，生成可视化路线
分析特定时间/距离内的可达区域(等时圈)用于选址或覆盖范围评估
在聊天中直接渲染交互式地图或静态地图图片展示路线与地点
支持客户端
Claude Desktop完整支持
Claude Code完整支持
VS Code (GitHub Copilot)完整支持
Goose完整支持
Cursor部分支持
Smolagents部分支持