Mapbox MCP Server 是一个 Node.js 服务器，实现了 Model Context Protocol（MCP），用于把 Mapbox API 的地理空间能力接入 AI 智能体和应用。官方定位是让任意 AI 智能体或应用转变为具备地理空间感知能力的系统，使其能够理解和推理地点、在物理世界中导航并访问丰富的地理空间数据。
主要能力
- 全球地理编码：将地址和地名转换为坐标，或反向转换。
- 兴趣点（POI）搜索：覆盖全球数百万商家、地标和地点。
- 多模式路线规划：支持驾车、步行和骑行，并包含实时交通。
- 出行时间矩阵：用于分析可达性和优化物流。
- 路线优化：为多个停靠点寻找最优访问顺序（旅行商问题）。
- 地图匹配：把 GPS 轨迹贴合到路网，便于生成清晰路线可视化。
- 等时圈生成：可视化在特定时间或距离约束内可到达的区域。
- 实时交互式地图渲染（render_map_tool）：在聊天中直接于真实的 Mapbox GL JS 地图上展示路线、搜索结果和自定义 GeoJSON。
- 静态地图图像：生成地点、路线和地理数据的可视化表示。
- 离线地理空间计算：距离、面积、方位、缓冲区和空间分析，无需 API 调用。
使用方式与接入
- 使用该 MCP 服务器需要 Mapbox access token。获取方式：在 mapbox.com/signup 注册免费 Mapbox 账户，进入账户页面，创建新 token 或使用默认公开 token。
- 提供的托管 MCP 端点：https://mcp.mapbox.com/mcp ，可参考 Hosted MCP Server Guide 进行不同客户端的设置。
- 集成指南包括：Claude Desktop 设置、Goose 设置、VS Code 设置、Cursor AI IDE 设置、Smolagents 集成，以及直接导入工具（无需运行 MCP 服务器）。
- 还提供 render_map_tool 指南，说明地图可视化原语的完整载荷结构和如何独立渲染自有数据。
资源与回退机制
- 服务器以 MCP resources 暴露静态参考数据，URI 模式为 mapbox://categories 或 mapbox://categories/{language}，可获取用于分类搜索的完整分类 ID 列表，例如默认英语列表、日语（mapbox://categories/ja）、西班牙语（mapbox://categories/es）。
- 支持原生 MCP 资源的客户端可使用 resources/read 方法；不支持资源支持的客户端（如 smolagents）可启用“resource fallback tools”，包括 resource_reader_tool 和 category_list_tool。默认不包含这些工具，仅在客户端不支持资源时设置启用。
地图可视化
- render_map_tool 是该服务器唯一的可视化原语，通过 MCP Apps 协议（@modelcontextprotocol/ext-apps）以自包含 HTML 面板形式直接在聊天中渲染，带全屏切换，支持 Claude Desktop 和带 GitHub Copilot 的 VS Code。它也可直接接收手工编写的 GeoJSON，不依赖其他 Mapbox API 调用。
- 不支持 MCP Apps 的客户端可使用 static_map_image_tool，返回 base64 编码的 PNG/JPEG。
- export_map_html_tool 用于智能体构建网页或文件时返回独立 HTML 地图页面，与 render_map_tool 输入相同，返回包含地图数据和 Mapbox 公开 token 的几 KB 文档，可保存为 map.html 或用 iframe 嵌入。每页地图数据限制为 200 KB，大型多边形需先用 simplify_tool 简化。页面默认使用账户默认公开 token，除非传入 public_token；已发布站点建议使用 URL 限制的公开 token。地图脚本从 jsDelivr 加载并按版本和子资源完整性哈希固定。实时图层（路线、等时圈、搜索结果）每次页面加载时从 Mapbox API 获取，计入 token 所属账户计费。
离线地理空间工具
基于 Turf.js，完全离线执行，不需要 Mapbox API 调用，支持无网络环境：距离计算（Haversine 公式，支持公里、英里、米、英尺、海里）、点在多边形或多边形集合内的测试（支持孔洞和批量测试，用于地理围栏、配送区域验证和客户分群）、给定起点、方位和距离计算目标点（测地线偏移，非路径规划）、方位计算（返回 0-360 度及基本方位）、两点间大圆中点、多边形质心、多边形面积（支持平方米、平方公里、英亩、公顷等）。
适用场景
可用于构建 AI 旅行助手、物流优化器、基于位置的推荐器，或任何需要理解“在哪里”的应用。示例提示涵盖位置定位、地点发现、导航与旅行、可视化与地图、分析与规划、GPS 与路线匹配、离线地理空间计算等。
限制与注意事项
- 使用前必须获取 Mapbox access token。
- render_map_tool 的富地图预览仅在支持 MCP Apps 协议的客户端中可用（如 Claude Desktop、带 GitHub Copilot 的 VS Code）。
- export_map_html_tool 每页地图数据限制 200 KB，大型多边形需先用 simplify_tool 简化。
- 离线工具执行的是直线测地线计算，并非实际路径规划。
- 更多客户端设置、API 用法与完整示例需参考官方各集成指南。
