Mapbox MCP Server

官方

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

GitHub
347

文档

Mapbox MCP 服务器

npm version

实现 Mapbox API 的模型上下文协议 (MCP) 的 Node.js 服务器。

为您的人工智能应用解锁地理空间智能

Mapbox MCP 服务器通过提供对 Mapbox 全面位置智能平台的无缝访问，将任何 AI 代理或应用转变为具有地理空间感知能力的系统。借助此服务器，您的 AI 可以理解和推理地点、在物理世界中导航，并访问丰富的地理空间数据，包括：

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

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

Mapbox MCP Server Demo

用法

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

托管 MCP 端点

如需快速访问，您可以使用我们的托管 MCP 端点：

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

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

要获取 Mapbox 访问令牌：

  1. 在 mapbox.com/signup 注册一个免费的 Mapbox 账户
  2. 导航到您的账户页面
  3. 创建一个新令牌或使用默认的公共令牌

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

集成指南

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

示例提示

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

地点发现

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

导航与出行

  • “获取从洛杉矶国际机场到好莱坞的驾车路线，并考虑当前交通状况”
  • “从中央公园步行到时代广场需要多长时间？”
  • “计算从我的酒店（四季酒店）到肯尼迪机场在高峰时段的出租车出行时间”

可视化与地图

  • “创建一张地图图像，显示从金门大桥到渔人码头的路线，并在两个地点放置标记”
  • “显示曼哈顿的卫星视图，并标记主要地标”
  • “生成一张地图，高亮显示西雅图市中心一英里范围内的所有星巴克门店”

分析与规划

  • “显示从波特兰市中心驾车 30 分钟内可到达的区域”
  • “计算丹佛这 3 个酒店地点（万豪、喜来登和希尔顿）与会议中心之间的出行时间矩阵”
  • “找到游览旧金山这 3 个旅游景点（金门大桥、音乐楼梯和渔人码头）的最佳路线”
  • “优化这 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 协议方法
  • 不支持资源的客户端：使用 resource_reader_tool 并附带资源 URI

富地图预览 (MCP Apps)

static_map_image_tool 在兼容的客户端中提供了一个交互式地图预览面板，作为所有客户端都能收到的 base64 图像的补充。

此服务器实现了 MCP Apps 协议 (@modelcontextprotocol/ext-apps)，该协议直接在聊天中渲染一个自包含的 HTML 应用面板。受支持的客户端会显示一个带有全屏切换功能的交互式地图：

  • Claude Desktop ✅
  • VS Code with GitHub Copilot ✅
  • Claude Code ✅
  • Goose ✅

无论协议支持如何，所有客户端都会收到 base64 编码的地图图像——交互式预览是在标准图像响应之上的渐进增强。

旧版：MCP-UI

此服务器还保留了对 MCP-UI (@mcp-ui/server) 的支持，这是一个用于嵌入式 iframe 预览的早期开放规范。MCP Apps 是推荐的协议；保留 MCP-UI 支持是为了向后兼容。

MCP-UI 默认启用。要禁用它，请将 --disable-mcp-ui 作为命令行标志传递或设置 ENABLE_MCP_UI=false。详情请参阅 MCP-UI 文档。

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) 之间的距离是多少？”

点在多边形内工具

测试一个点是否在多边形或多多边形内部。

功能：

  • 适用于包含孔洞的复杂多边形
  • 支持多多边形
  • 可用于地理围栏和服务区域检查

用法示例：“这个配送地址在我们的服务区域内吗？”

方位角工具

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

功能：

  • 返回以度为单位的方位角 (0-360°)
  • 提供基本方向（北、东北、东、东南、南、西南、西、西北）
  • 可用于导航和方向查询

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

中点工具

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

功能：

  • 计算地球曲面上真实的中点
  • 可用于会面地点建议
  • 正确处理长距离计算

用法示例：“旧金山和纽约之间的中点在哪里？”

质心工具

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

功能：

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

用法示例：“我应该把这个社区边界的标记放在哪里？”

面积工具

计算多边形的面积。

功能：

  • 支持多种单位：平方米、平方公里、英亩、公顷、平方英里、平方英尺
  • 在地球表面上进行精确的面积计算
  • 适用于任何大小的多边形

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

边界框工具

计算包含几何体的最小边界框 (bbox)。

功能：

  • 适用于点、线、多边形和多多边形
  • 返回 [最小经度, 最小纬度, 最大经度, 最大纬度]
  • 可用于视口计算和空间索引

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

缓冲区工具

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

功能：

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

示例用法：“显示此位置周围 5 公里的缓冲区”

简化工具

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

功能：

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

示例用法：“简化此复杂边界以减少点数”

Mapbox API 工具

类别列表工具（已弃用）

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

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

矩阵工具

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

  • 高效的一对多、多对一或多对多路径计算
  • 支持不同的出行方式（驾车-实时路况、驾车、步行、骑行）
  • 出发时间设定，用于考虑路况的计算
  • 包含距离和时长指标的路线摘要
  • 控制接近方式（路边/无限制）和允许的出发方位角范围

静态图像工具

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

  • 自定义地图样式（街道、户外、卫星等）
  • 可调整的图像尺寸和缩放级别
  • 支持多个带有自定义颜色和标签的标记
  • 叠加选项，包括折线和多边形
  • 自动适应指定坐标

类别搜索工具

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

  • 按类别搜索兴趣点（餐厅、酒店、加油站等）
  • 按地理邻近性过滤
  • 可自定义结果数量限制
  • 每个结果的丰富元数据
  • 支持多种语言

反向地理编码工具

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

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

路线工具

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

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

等时圈工具

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

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

搜索和地理编码工具

使用 Mapbox Search Box 文本搜索 API 端点来支持搜索和地理编码兴趣点、地址、地点以及该 API 支持的任何其他类型。 此工具将之前由 ForwardGeocodeTool 和 PoiSearchTool（来自此 MCP 服务器的早期版本）提供的功能整合到一个工具中。

地图匹配工具

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

  • 将嘈杂的 GPS 轨迹转换为道路网络上的干净路线
  • 支持不同的出行方式（驾车、驾车-实时路况、步行、骑行）
  • 每个请求最多处理 100 个坐标对
  • 可选的时间戳，用于根据速度提高准确性
  • 可配置的捕捉半径，适用于不同的 GPS 质量水平
  • 路线注释（限速、距离、时长、交通拥堵）
  • 多种几何图形输出格式（GeoJSON、折线）

示例用法：“清理此 GPS 轨迹并将其捕捉到道路：[带时间戳的坐标]”

优化工具

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

  • 解决 2-12 个地点的旅行商问题（TSP）
  • 支持不同的出行方式（驾车、驾车-实时路况、步行、骑行）
  • 灵活的起点和终点配置
  • 往返或单程路线优化
  • 逐向导航指令（可选）
  • 路线注释（距离、时长、速度）
  • 多种几何图形输出格式（GeoJSON、折线）

示例用法：“查找访问这 5 个站点的最优路线：[地址或坐标列表]”

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

开发

检查服务器

使用 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 服务器包含全面的 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 文件加载）
  • ✅ 自动工具执行追踪
  • ✅ 带有 CloudFront 关联 ID 的 HTTP 请求检测
  • ✅ 可配置的导出器（控制台、OTLP）
  • ✅ 安全意识（数据保护、JWT 验证）
  • ✅ 生产就绪（CPU 开销低于 1%）

贡献

我们欢迎对 Mapbox MCP 服务器的贡献！在提交拉取请求之前，请阅读 CONTRIBUTING.md。

完整的标准和指南：

贡献者快速入门

  1. Fork 仓库并克隆您的 fork
  2. 安装依赖项：npm install
  3. 遵循我们的编码标准进行更改
  4. 运行测试和代码检查：npm test && npm run lint
  5. 为任何新功能添加测试
  6. 提交带有清晰描述的拉取请求

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

数据使用与隐私

发送到 Mapbox API 的数据

当您使用 MCP 服务器工具时，以下数据会直接从您的环境发送到 Mapbox API：

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

您的隐私

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

第三方数据使用

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

支持与联系

对于 MCP 服务器问题

对于 Mapbox API 问题

维护承诺

此 MCP 服务器由 Mapbox, Inc. 官方维护。我们提供：

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

MIT 许可证