Mapbox

官方

通过Mapbox API解锁地理空间智能，包括地理编码、兴趣点搜索、路线规划、等时线等功能。

GitHub

370

你可以用 Mapbox MCP 做什么？

地理编码和搜索地点 — 使用 search_and_geocode_tool 将地址转换为坐标，或查找咖啡店、加油站等兴趣点。
获取路线 — 通过 directions_tool 获取驾车、步行或骑行路线，并查看路况、备选路线和排除项。
查找可达区域 — 使用 isochrone_tool 生成等时圈多边形，显示在指定时间或距离内可到达的区域。
定位坐标 — 使用 ground_location_tool 一次调用即可查询坐标所在的街区、附近的兴趣点以及可达范围。
在聊天中渲染地图 — 使用 render_map_tool 将路线、搜索结果或自定义 GeoJSON 显示为实时交互式地图。
查询类别 — 通过 mapbox://categories 以英语、日语或西班牙语读取类别 ID 列表。

文档

Mapbox MCP Server

用于 Mapbox API 的 Node.js 服务器，实现了 Model Context Protocol (MCP)。

为 AI 应用解锁地理空间智能

Mapbox MCP Server 通过无缝接入 Mapbox 全面的位置信息平台，将任何 AI 智能体或应用转变为具备地理空间感知能力的系统。借助此服务器，你的 AI 可以理解并推理地点信息、探索现实世界，并访问丰富的地理空间数据，包括：

全球地理编码，可将地址和地点名称转换为坐标，反之亦然
兴趣点 (POI) 搜索，覆盖全球数百万家企业、地标和地点
多模式路线规划，支持驾车、步行和骑行，并提供实时交通信息
出行时间矩阵，用于分析可达性并优化物流
路线优化，为多个停靠点找到最佳访问顺序（旅行商问题）
地图匹配，将 GPS 轨迹吸附到道路网络，以便清晰地可视化路线
等时圈生成，可视化在特定时间或距离限制内可到达的区域
实时交互式地图渲染（render_map_tool），可在聊天中直接通过真实的 Mapbox GL JS 地图显示路线、搜索结果和你自己的自定义 GeoJSON
静态地图图像，用于创建地点、路线和地理数据的可视化表示
离线地理空间计算，可计算距离、面积、方位角、缓冲区并进行空间分析，无需 API 调用

无论你是在构建 AI 旅行助手、物流优化器、基于位置的推荐系统，还是任何需要理解“位置”的应用，Mapbox MCP Server 都能提供实现这些功能所需的空间智能。你也可以在 Claude Desktop 和 VS Code 等常用客户端中启用它。详情见下文

Mapbox MCP Server Demo

用法

使用此 MCP 服务器需要 Mapbox 访问令牌。

托管 MCP 端点

如需快速接入，可以使用我们的托管 MCP 端点：

端点：https://mcp.mapbox.com/mcp

有关不同客户端的详细设置说明和 API 用法，请参阅托管 MCP Server 指南。

获取 Mapbox 访问令牌：

在 mapbox.com/signup 注册免费的 Mapbox 账户
前往你的账户页面
创建新令牌，或使用默认的公开令牌

有关 Mapbox 访问令牌的更多信息，请参阅 Mapbox 关于访问令牌的文档。

集成指南

有关不同集成方式的详细设置说明，请参阅以下指南：

Claude Desktop 设置 - 配置 Claude Desktop 以使用此 MCP 服务器的说明
Goose 设置 - 设置 Goose AI 智能体框架
VS Code 设置 - 在 Visual Studio Code 中设置开发环境
Cursor AI IDE 设置 - 在 Cursor AI IDE 中设置开发环境
Smolagents 集成 - 展示如何将 Smolagents AI 智能体连接到 Mapbox 工具的示例
直接导入工具 - 无需运行 MCP 服务器，即可在自己的应用中使用 Mapbox 工具
render_map_tool 指南 - 地图可视化原语：完整的负载架构，以及如何独立渲染自己的数据，无需使用任何其他 Mapbox 工具
用户询问 - 介绍 search_and_geocode_tool 和 directions_tool 如何请用户消除结果歧义或选择路线，以及在客户端不支持此功能时如何平稳回退

示例提示

设置完成后，可在 Claude Desktop 或其他 MCP 客户端中尝试以下提示：

位置定位

对于以坐标为起点的查询——“我附近有什么”、“这里是什么街区”、“N 分钟内能到哪里”——请使用 ground_location_tool。它会在一次调用中组合反向地理编码、类别搜索和等时圈功能，根据查询内容自适应地选择合适的策略，并返回带引用的类型化记录（名称、地址、坐标、距离、可达区域多边形）。

以下四个提示分别通过一次工具调用测试不同的策略：

街区 — “47.6097, -122.3408 是什么街区？我附近有什么？”
POI — “40.7580, -73.9855 周围步行 10 分钟范围内有哪些咖啡店？”
区域 — “从 37.7749, -122.4194 出发，步行 15 分钟能到哪里？”
路线规划 — “34.0522, -118.2437 附近最近的可通行下客点在哪里？”

位置发现

“查找帝国大厦步行可达范围内的咖啡店”
“我想从西雅图去波特兰，沿途有星巴克吗？”
“显示波士顿到纽约路线沿途的加油站”
“时代广场附近有哪些餐厅？”

导航与出行

“获取从 LAX 到好莱坞的驾车路线，并考虑当前交通状况”
“从中央公园步行到时代广场需要多长时间？”
“计算高峰时段从我的酒店（Four Seasons）乘出租车到 JFK 机场的出行时间”

可视化与地图

“使用 Mapbox 地图渲染工具，显示从旧金山金门大桥到联合广场的路线” — 在真实的 Mapbox 地图上渲染实时交互式路线
“创建一张地图图像，显示从金门大桥到渔人码头的路线，并在两个地点添加标记”
“显示曼哈顿的卫星视图，并标出主要地标”
“生成一张地图，突出显示西雅图市中心一英里范围内的所有星巴克门店”
“在这些坐标上显示填充多边形：[...]，并在 [...] 处添加标注为‘Warehouse’的标记” — 通过 render_map_tool 直接渲染你自己的 GeoJSON，无需使用其他 Mapbox 工具

分析与规划

“显示从波特兰市中心驾车 30 分钟内可到达的区域”
“计算这 3 家酒店（Marriott、Sheraton 和 Hilton）与丹佛会议中心之间的出行时间矩阵”
“为旧金山的这 3 个旅游景点（金门大桥、Musical Stairs 和渔人码头）规划最佳游览路线”
“为以下 8 个地址优化配送路线：[地址列表]”

GPS 与路线匹配

“清理这条 GPS 轨迹，并显示道路上的实际路线：[带时间戳的坐标列表]”
“将这次记录的自行车骑行轨迹吸附到骑行网络：[GPS 坐标]”
“将这条驾车路线匹配到道路网络，并显示交通拥堵程度”

离线地理空间计算

“这两个坐标之间的距离是多少英里？”
“计算这个多边形的面积，单位为平方公里”
“坐标为 37.7749°N, 122.4194°W 的点是否位于这个服务区域多边形内？”
“从旧金山到纽约的方位角是多少？”
“求伦敦和巴黎之间的中点”
“以此位置为中心创建一个 5 英里缓冲区”
“计算这个街区边界的质心”
“这些路线坐标的边界框是什么？”
“简化这个复杂多边形以减少点的数量”

提升结果质量的提示

明确指定地点（使用完整地址或地标名称）
指定首选出行方式（驾车、步行、骑行）
在适用时注明时间限制（“高峰时段”、“下午 3 点”）
需要时指定输出格式（“作为地图图像”、“JSON 格式”）

详细示例： 请参阅 examples/search-along-route.md，了解不同用例下沿路线搜索提示的完整示例，以及 MCP Inspector 测试说明。

资源

MCP 服务器将静态参考数据作为 MCP 资源公开。资源提供对数据的只读访问，客户端可以直接引用这些数据，而无需调用工具。

可用资源

Mapbox 类别资源

URI 模式：mapbox://categories 或 mapbox://categories/{language}

访问可用于类别搜索工具的完整类别 ID 列表。类别可用于按类型筛选搜索结果（例如，“restaurant”、“hotel”、“gas_station”）。

示例：

mapbox://categories - 默认（英语）类别列表
mapbox://categories/ja - 日语类别名称
mapbox://categories/es - 西班牙语类别名称

访问资源：

支持原生 MCP 资源的客户端：使用 resources/read MCP 协议方法
不支持资源的客户端：使用带有资源 URI 的 resource_reader_tool

丰富的地图预览（`render_map_tool`）

此服务器中的每个地理空间工具（路线规划、等时圈、搜索等）都可以通过 render_map_tool 将结果显示为实时交互式 Mapbox GL JS 地图——这是服务器唯一的可视化原语。它通过 MCP Apps 协议（@modelcontextprotocol/ext-apps）在支持的客户端中直接于聊天内渲染为独立的 HTML 面板，并提供全屏切换功能：

Claude Desktop ✅
带 GitHub Copilot 的 VS Code ✅
Claude Code ✅
Goose ✅

使用此功能不需要此服务器的任何其他工具。 render_map_tool 也接受直接编写的 GeoJSON——包括你自己的多边形、标记和路线——无需依赖 directions_tool、isochrone_tool 或任何其他 Mapbox API 调用。有关负载架构和完整的独立示例，请参阅**完整的 render_map_tool 指南**。

如果你需要在不支持 MCP Apps 的客户端中获得可靠的静态图像，请改用 static_map_image_tool——它会返回 base64 编码的 PNG/JPEG，所有客户端都可以显示。

CLIENT_NEEDS_RESOURCE_FALLBACK

资源回退工具（供不符合规范的客户端选择启用）

资源是大多数客户端（Claude Desktop、VS Code、MCP Inspector 等）都支持的 MCP 核心功能。不过，有些客户端（如 smolagents）完全不支持资源。对于这些客户端，服务器可以提供“资源回退工具”，通过工具调用提供与资源相同的内容。

回退工具：

resource_reader_tool - 按 URI 读取任意资源的通用回退工具
category_list_tool - 提供对类别列表（mapbox://categories）的访问

默认情况下不包含这些工具（假定你的客户端支持资源）。如果客户端不支持资源，请启用回退工具：

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

适用情况：

✅ 如果使用 smolagents 或其他不支持资源的客户端，请设置为 true
❌ 如果使用 Claude Desktop、VS Code、MCP Inspector 或任何支持资源的客户端，请保持未设置（默认值）
❌ 如果不确定，请保持未设置（大多数客户端都支持资源）

工具

实用工具

资源读取工具

为不支持原生 MCP 资源 API 的客户端提供访问 MCP 资源的功能。使用此工具读取类别列表等资源。

参数：

uri：要读取的资源 URI（例如，mapbox://categories、mapbox://categories/ja）

用法示例：

读取默认类别：{"uri": "mapbox://categories"}
读取日语类别：{"uri": "mapbox://categories/ja"}

注意：如果你的 MCP 客户端支持原生资源，请优先直接使用资源 API，以获得更好的性能。

离线地理空间工具

这些工具完全离线执行地理空间计算，无需调用 Mapbox API。它们使用 Turf.js 进行精确的地理计算，可在任何地方使用，即使没有互联网连接也可以。

距离工具

使用 Haversine 公式计算两个地理坐标之间的距离。

功能：

支持多种单位：千米、英里、米、英尺、海里
精确计算大圆距离
无需 API 调用

用法示例：“旧金山（37.7749°N, 122.4194°W）和纽约（40.7128°N, 74.0060°W）之间的距离是多少？”

多边形内点工具

检查一个或多个点是否位于多边形或多多边形内，并仅返回位于其中的点。支持在一次调用中处理单个点或一批点。

功能：

支持包含孔洞的复杂多边形
支持多多边形
一次调用即可批量测试任意数量的点
适用于地理围栏、配送区域验证和客户细分

示例用法："这些配送地址中，哪些位于我们的服务区域内？"

目标点工具

使用测地线（大圆）偏移，根据起点、方位角和距离计算目标点。

功能：

直线偏移，而非沿路线行进
适用于“查找 X 以北 5km 处的点”或构建搜索偏移
无需 API 调用

示例用法："太空针塔东北方向 10km 处是什么位置？"

方位角工具

计算从一个坐标到另一个坐标的罗盘方向（方位角）。

功能：

返回以度为单位的方位角（0-360°）
提供基本方向（N、NE、E、SE、S、SW、W、NW）
适用于导航和方向查询

示例用法："从这里去机场，我应该朝哪个方向走？"

中点工具

沿大圆路径查找两个坐标之间的地理中点。

功能：

计算地球曲面上的真实中点
适用于推荐会面地点
可正确处理长距离计算

示例用法："旧金山和纽约的中点在哪里？"

质心工具

计算多边形或多多边形的几何中心（质心）。

功能：

适用于复杂形状
返回所有点的算术平均值
适用于放置标签或标记

示例用法："我应该在哪里为这个街区边界放置标记？"

面积工具

计算多边形的面积。

功能：

支持多种单位：平方米、平方千米、英亩、公顷、平方英里、平方英尺
可准确计算地球表面的面积
适用于任意大小的多边形

示例用法："这个公园的面积是多少英亩？"

边界框工具

计算包含某个几何图形的最小边界框（bbox）。

功能：

适用于点、线、多边形和多多边形
返回 [minLongitude, minLatitude, maxLongitude, maxLatitude]
适用于视口计算和空间索引

示例用法："这条路线的边界框是什么？"

缓冲区工具

围绕点、线或多边形创建缓冲区（多边形）。

功能：

支持多种距离单位
在点周围创建圆形缓冲区
适用于邻近分析和创建影响区域

示例用法："显示这个位置周围 5km 的缓冲区"

简化工具

使用 Douglas-Peucker 算法减少线或多边形中的顶点数量。

功能：

可配置细节级别的容差
在降低复杂度的同时保留整体形状
适用于减小文件大小并提升渲染性能
可选择保持拓扑结构（防止自相交）

示例用法："简化这个复杂边界，减少点的数量"

长度工具

测量由一系列坐标定义的线的总长度。

功能：

支持千米、英里、米和英尺
无需调用路线规划 API，即可测量绘制的路线、路径或边界

示例用法："这条徒步路线有多长？"

凸包工具

计算一组点的凸包——包含所有点的最小凸多边形。

功能：

适用于边界区域分析或估算覆盖面积
可离线运行，无需 API 调用

示例用法："包含所有这些门店位置的最小多边形是什么？"

线上最近点工具

将一个点吸附到线或路线上的最近位置，并返回该点及其距离。

功能：

适用于“这条路线上的哪个点离我的位置最近？”等问题，或无需 API 调用即可进行地图匹配

示例用法："我现在离这条徒步路线上的哪个位置最近？"

合并、相交和差集工具

合并或比较两个或多个多边形——union_tool 将它们合并为一个几何图形，intersect_tool 查找它们的重叠区域，difference_tool 则从一个多边形中减去另一个。

功能：

适用于合并服务区域、查找覆盖范围重叠或计算排除区域（例如“区域 A 覆盖但区域 B 未覆盖的部分是什么？”）
完全离线运行，无需 API 调用
每个工具都会返回一个 render_map_tool 引用，可直接将结果可视化

示例用法："将这两个配送区域合并为一个覆盖区域" / "这两个等时圈在哪里重叠？" / "这个服务区域中有哪些部分未被我们的 15 分钟等时圈覆盖？"

Mapbox API 工具

类别列表工具（已弃用）

⚠️ 已弃用：请改用 URI 为 mapbox://categories 的 resource_reader_tool，或者如果客户端支持 MCP 资源，则直接访问 mapbox://categories 资源。

此工具仅为向后兼容而保留，供不支持 MCP 资源或 resource_reader_tool 的客户端使用。

矩阵工具

使用 Mapbox Matrix API 计算多个点之间的行程时间和距离。功能包括：

高效计算一对多、多对一或多对多路线
支持不同的出行方式（driving-traffic、driving、walking、cycling）
可指定出发时间，以进行交通状况感知计算
汇总路线的距离和时长指标
控制行进方向（靠路边/不限制）以及允许的出发方位角范围

静态图像工具

使用 Mapbox static image API 生成静态地图图像。功能包括：

自定义地图样式（街道、户外、卫星等）
可调整图像尺寸和缩放级别
支持使用自定义颜色和标签添加多个标记
支持叠加折线和多边形等图层
自动适配指定坐标

类别搜索工具

使用 Mapbox Search Box category search API 执行类别搜索。功能包括：

按类别搜索兴趣点（餐厅、酒店、加油站等）
按地理邻近程度筛选
可自定义结果数量上限
为每个结果提供丰富的元数据
支持多种语言

反向地理编码工具

使用 Mapbox geocoding V6 API 执行反向地理编码。功能包括：

将地理坐标转换为易读地址
可自定义详细程度（街道、街区、城市等）
按类型筛选结果（地址、兴趣点、街区等）
支持多种语言
提供丰富的位置上下文信息

地面位置工具

通过一次调用回答“这个坐标附近有什么？”的问题，包括地点名称、附近的兴趣点和可在行程时间内到达的范围；数据来自 Mapbox 实时数据，并附有引用。请使用此工具，而不要将 reverse_geocode_tool 与网页搜索串联使用。

功能：

对查询进行分类（路线规划、街区背景、兴趣点搜索或区域/可达范围），并仅获取相关数据
按需按类别搜索附近的兴趣点
提供行程时间可达范围摘要（基于等时圈）
返回一个 render_map_tool 引用，其中包含有依据的位置和绘制出的附近兴趣点

示例用法："这个坐标位于哪个街区？附近有咖啡店吗？"

地点详情工具

使用 Mapbox ID 获取特定地点的详细信息，包括照片、营业时间、评分、电话号码和网站 URL。可在 search_and_geocode_tool、category_search_tool 或 reverse_geocode_tool 之后使用，以获取特定结果的更多详情。

示例用法："告诉我第一个咖啡店搜索结果的更多信息——营业时间、电话号码和网站"

路线规划工具

使用 Mapbox Directions API 获取路线指引。功能包括：

支持不同的路线规划配置：驾车（实时交通或典型交通）、步行和骑行
支持多个途经点的路线（2-25 对坐标）
可选择备选路线
路线注释（距离、时长、速度、拥堵情况）
时间安排选项：
- 驾车和 driving-traffic 配置可指定未来出发时间（depart_at）
- 仅驾车配置可指定期望到达时间（arrive_by）
特定配置的优化选项：
- 驾车：车辆尺寸限制（高度、宽度、重量）
路线排除选项：
- 常见排除项：渡轮路线、仅接受现金的收费路段
- 驾车专属排除项：收费路段、高速公路、未铺装道路、隧道、国界、州界
- 自定义点排除项（最多可避开 50 个地理点）
GeoJSON 几何图形输出格式

等时圈工具

使用 Mapbox Isochrone API 计算从某个位置出发，在指定时间内可到达的区域。功能包括：

支持不同的出行方式（驾车、步行、骑行）
可自定义行程时间或距离
可生成多个等值线（例如 15、30、45 分钟范围）
可选指定出发或到达时间
可自定义用于可视化的颜色

搜索和地理编码工具

使用 Mapbox Search Box Text Search API 端点，搜索并对兴趣点、地址、地点以及该 API 支持的其他类型进行地理编码。此工具整合了早期版本的此 MCP 服务器中由 ForwardGeocodeTool 和 PoiSearchTool 提供的功能。

地图匹配工具

使用 Mapbox Map Matching API 将 GPS 轨迹吸附到道路网络。功能包括：

将有噪声的 GPS 轨迹转换为道路网络上的干净路线
支持不同的出行方式（driving、driving-traffic、walking、cycling）
每个请求最多处理 100 对坐标
可选提供时间戳，以根据速度提高准确性
可针对不同的 GPS 质量级别配置吸附半径
路线注释（限速、距离、时长、交通拥堵情况）
支持多种几何图形输出格式（GeoJSON、polyline）

示例用法："清理这条 GPS 轨迹并将其吸附到道路上：[带时间戳的坐标]"

路线优化工具

使用 Mapbox Optimization API 查找经过多个地点的最优路线。功能包括：

为 2-12 个地点求解旅行商问题（TSP）
支持不同的出行方式（driving、driving-traffic、walking、cycling）
灵活配置起点和终点
可优化往返或单程行程
可选提供逐向导航指引
路线注释（距离、时长、速度）
支持多种几何图形输出格式（GeoJSON、polyline）

示例用法："查找经过这 5 个停靠点的最优路线：[地址或坐标列表]"

注意：提供具有高级功能（时间窗口、容量限制、多辆车）的 V2 API，但需要获得 beta 访问权限。V2 实现已包含在代码库中，但默认未注册。

反馈工具

通过 Mapbox Feedback API（公开预览版）向应用或智能体的开发者发送用户反馈。反馈会归入拥有访问令牌的账户，因此，当你使用自己的令牌基于此服务器构建应用或智能体时，用户反馈会与应用的 Feedback Agent 报告显示在同一信息流中，你可以在 Feedback Explorer 中查看。此工具不会向 Mapbox 报告问题。与 Feedback Agent 一样，它适用于任何有助于你了解用户需求的产品反馈，例如：

已关闭、信息有误或位置不正确的地点
找不到的地点或地址
已封闭的道路、错误的限速信息或显示错误的交通状况
存在非法转弯或入口的路线，或完全没有路线
与应用本身有关的问题，例如错误或建议（application_issue）

它会发送反馈文本、类别和位置，并返回该条目的 ID 和状态。对于与地点无关的反馈，位置是可选的；但 API 要求提供位置，因此目前该工具会按照 Feedback API 团队的建议发送 0, 0。未经用户同意，不会发送任何内容：支持 elicitation 的客户端会先显示确认提示；其他情况下，工具描述会要求模型在聊天中确认。

Public Preview 期间，Feedback API 免费。正式发布后，Feedback Agent 每条反馈收费 $0.02。为避免重复提交同一问题，工具会在发送前检查该账户过去 30 天内提交的报告。如果同一类别、距离 50 m 以内的报告仍在等待审核（不检查没有位置的反馈），工具会返回该报告，而不是发送新报告。Feedback API 只会列出该账户自己的报告，因此无法发现其他账户提交的报告。用户表示自己的问题不同于已有报告时，send_anyway: true 会跳过检查。

要求：访问令牌需要 user-feedback:write scope 才能发送反馈，并需要 user-feedback:read scope 才能检查重复项。没有写入 scope 时，工具会返回相应错误。没有读取 scope 时，工具会跳过检查并在结果中说明。若要禁用此工具，请使用 --disable-tools feedback_tool 启动服务器。

使用示例：“Mint St 上的 Blue Bottle 去年就关门了，可以把这个作为反馈发送吗？”

Report 工具

向构建 Mapbox MCP server 的 Mapbox 团队发送有关服务器本身的反馈：错误、工具返回错误或令人困惑的结果、缺少的功能或建议。反馈会记在 Mapbox 自己的账户下，而不是你的账户，因此不需要额外的令牌 scope；提交后也无法查看或撤回。此工具不用于报告地图、地点或路线数据错误。

服务器会在文本末尾添加自身版本、客户端名称和版本，以及反馈所涉及的工具。未经用户同意，不会发送任何内容：支持 elicitation 的客户端会先显示确认提示；其他情况下，工具描述会要求模型在聊天中确认。

此工具使用 Feedback API 团队为 Mapbox CLI 的 mapbox report 命令添加的端点。若要禁用此工具，请使用 --disable-tools report_tool 启动服务器。

使用示例：“地图没有绘制我的任何等时圈。可以告诉 Mapbox MCP 团队吗？”

列出公开令牌工具

列出账户的公开（pk.）访问令牌，供在聊天之外构建网页或应用的代理使用，以便加载 Mapbox GL JS 或从浏览器调用 Mapbox API。在聊天中，render_map_tool 不需要令牌。每个令牌都会附带名称、是否为默认令牌、URL 限制和 scope。

传入 site_url（网页运行的位置）；如果账户中有受该 URL 限制的令牌，工具会推荐使用该令牌。否则，工具会推荐默认公开令牌，并说明已发布的网站应改用受 URL 限制的令牌，同时提供创建令牌的链接。任何人复制了不受限制的公开令牌后都可以使用它，相关用量会计入该账户。

此工具绝不会返回机密或临时令牌，也无法创建令牌（创建令牌需要 tokens:write；DevKit server 的 create_token_tool 可以创建）。

要求：列出令牌需要 tokens:read scope；聊天内地图也使用相同的 scope 来查找默认公开令牌。如果访问令牌具有 pk.，或者在服务器自身的 MAPBOX_ACCESS_TOKEN 上列出失败且已设置 MAPBOX_PUBLIC_TOKEN，工具会改为返回该令牌。使用自己的 bearer token 的调用方（托管服务器）永远不会获得 MAPBOX_PUBLIC_TOKEN，而受其他 URL 限制的令牌也永远不会被推荐。若要禁用此工具，请使用 --disable-tools list_public_tokens_tool 启动服务器。

使用示例：“帮我构建一个单页网站，在 Mapbox 地图上显示我们的三个门店位置。”

开发

检查服务器

使用 Node.js

# Run the built image
npm run inspect:build

使用 Docker

# Build the Docker image
docker build -t mapbox-mcp-server .

# Run and inspect the server
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

创建新工具

npx plop create-tool
# provide tool name without suffix (e.g. Search)

发布新版本

# 1. Bump version in package.json
npm version <new-version> --no-git-tag-version

# 2. Sync version to manifest.json and server.json
npm run sync-manifest

# 3. Prepare CHANGELOG (replaces "Unreleased" with version and date)
npm run changelog:prepare-release <new-version>

# 4. Update package-lock.json
npm install

# 5. Review changes, then commit and tag
git add package.json package-lock.json manifest.json server.json CHANGELOG.md
git commit -m "Release v<new-version>"
git tag v<new-version>
git push && git push --tags

重要：发布工作流会验证 package.json 和 server.json 的版本是否与发布版本一致。跳过版本升级或清单同步会导致发布失败。

OpenTelemetry 跟踪

此 MCP server 包含全面的 OpenTelemetry 跟踪功能，便于在生产环境中进行可观测性监控：

快速演示

# 1. Copy the example configuration
cp .env.example .env

# 2. Edit .env to add your MAPBOX_ACCESS_TOKEN and configure tracing

# 3. Start Jaeger for local development
npm run tracing:jaeger:start

# 4. Run the server (it will automatically use .env configuration)
npm run inspect:build

# 5. View traces at http://localhost:16686

# 6. Stop Jaeger when done
npm run tracing:jaeger:stop

**注意：**服务器启动时会自动从你的 .env 文件加载配置。.env.example 文件包含多个可观测性平台的配置示例。

支持的可观测性平台

.env.example 中包含以下平台的配置示例：

云服务提供商：

☁️ AWS X-Ray
☁️ Azure Monitor (Application Insights)
☁️ Google Cloud Trace

SaaS 平台：

📊 Datadog
📊 New Relic
📊 Honeycomb
📊 任何兼容 OTLP 的后端

生产环境配置

请参阅 docs/tracing.md，了解完整的设置说明，包括：

🔧 特定平台的配置指南
📊 身份验证和端点设置
🎯 自定义跟踪属性和上下文
🚀 性能优化（开销极低）
🔍 故障排查和调试

跟踪功能：

✅ 配置加载跟踪（.env 文件加载）
✅ 自动跟踪工具执行
✅ HTTP 请求检测，包含 CloudFront 关联 ID
✅ 可配置的导出器（console、OTLP）
✅ 注重安全性（数据保护、JWT 验证）
✅ 可用于生产环境（CPU 开销 <1%）

贡献

欢迎为 Mapbox MCP Server 做出贡献！提交 pull request 前，请阅读 CONTRIBUTING.md。

完整标准和指南：

CONTRIBUTING.md - 入门指南、PR 流程、快速参考
工程标准 (docs/engineering_standards.md) - 完整的代码质量、测试、文档和协作标准
Claude Code 指南 (CLAUDE.md) - 使用 Claude Code 的贡献者应遵循的标准和模式
AI Agent 说明 (AGENTS.md) - 其他 AI 编码助手（Cursor、Continue、Aider 等）的指南
GitHub Copilot 指南 - 负责任地使用 GitHub Copilot 的最佳实践

贡献者快速入门

Fork 仓库并克隆你的 fork
安装依赖：npm install
按照我们的编码标准进行修改
运行测试和 lint：npm test && npm run lint
为任何新功能添加测试
提交 pull request，并附上清晰的说明

所有贡献都必须通过 CI 检查和代码审查流程。详细要求请参阅 docs/engineering_standards.md。

数据使用与隐私

发送到 Mapbox API 的数据

使用 MCP server 工具时，以下数据会从你的环境直接发送到 Mapbox API：

地理编码工具：地址/位置文本、坐标、国家/地区筛选条件
搜索工具：搜索查询、用于计算邻近度的位置坐标、类别筛选条件
路线规划工具：起点/终点坐标、途经点、路线偏好、车辆限制
矩阵工具：多个坐标对、出行方式、出发时间
静态地图工具：坐标、缩放级别、样式偏好、标记信息
等时圈工具：起点坐标、时间/距离参数、出行方式

你的隐私

本地执行：所有 API 调用都从你的环境直接发送到 Mapbox API
令牌安全：你的 Mapbox API 令牌保留在本地计算机上，不会传输给此 MCP server，也不会由其存储
不存储数据：此 MCP server 不会存储、记录或收集你的任何数据或 API 请求
直接通信：你与 Mapbox API 之间没有中间服务器

第三方数据使用

Mapbox 的隐私政策适用于发送到其 API 的数据：https://www.mapbox.com/legal/privacy/
API 使用：通过这些工具发出的所有请求均适用 Mapbox API 的标准条款
数据保留：有关 Mapbox 的数据保留政策，请参阅其文档

支持与联系

MCP Server 问题

电子邮件：mcp-feedback@mapbox.com
GitHub Issues：报告错误和功能请求

Mapbox API 问题

Mapbox 支持：https://support.mapbox.com/
文档：https://docs.mapbox.com/
API 状态：https://status.mapbox.com/

维护承诺

此 MCP server 由 Mapbox, Inc. 正式维护。我们提供：

定期更新，支持新的 Mapbox API 功能
错误修复和安全更新
兼容最新版本的 MCP 协议
通过 GitHub issues 提供社区支持

MIT License