MCP Server

🚀 Mapbox MCP 服务器

Mapbox MCP 服务器是一个基于 Node.js 的服务器，它实现了适用于 Mapbox API 的模型上下文协议（MCP）。该服务器可让任何 AI 代理或应用程序无缝访问 Mapbox 全面的位置智能平台，从而将其转变为具备地理空间感知能力的系统。

🚀 快速开始

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

托管的 MCP 端点

若要快速访问，可使用托管的 MCP 端点：

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

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

获取 Mapbox 访问令牌的步骤如下：

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

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

集成指南

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

• Claude Desktop 设置 - 配置 Claude Desktop 以与此 MCP 服务器配合使用的说明。
• Goose 设置 - 使用支持 MCP - UI 的 Goose AI 代理框架进行设置。
• VS Code 设置 - 在 Visual Studio Code 中设置开发环境。
• Cursor AI IDE 设置 - 在 Cursor AI IDE 中设置开发环境。
• Smolagents 集成 - 展示如何将 Smolagents AI 代理连接到 Mapbox 工具的示例。

示例提示

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

位置发现

• “查找帝国大厦步行距离内的咖啡店”
• “显示从波士顿到纽约路线上的加油站”
• “时代广场附近有哪些餐厅？”

导航与旅行

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

可视化与地图

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

分析与规划

• “显示驾车 30 分钟内可到达波特兰市中心的区域”
• “计算丹佛的 3 家酒店（万豪酒店、喜来登酒店和希尔顿酒店）与会议中心之间的旅行时间矩阵”
• “找出游览旧金山的 3 个旅游景点（金门大桥、音乐阶梯和渔人码头）的最佳路线”

获得更好结果的提示

• 明确指定位置（使用完整地址或地标名称）
• 指定首选的出行方式（驾车、步行、骑自行车）
• 相关时包含时间限制（“高峰时段”、“下午 3 点”）
• 需要时请求特定的输出格式（“作为地图图像”、“以 JSON 格式”）

✨ 主要特性

Mapbox MCP 服务器可让 AI 理解和推理地点、在现实世界中导航，并访问丰富的地理空间数据，包括：

• 全球地理编码：将地址和地名转换为坐标，反之亦然。
• 兴趣点 (POI) 搜索：可搜索全球数百万个企业、地标和地点。
• 多模式路线规划：支持驾车、步行和骑自行车，考虑实时交通情况。
• 旅行时间矩阵：用于分析可达性和优化物流。
• 等时线生成：可视化在特定时间或距离限制内可到达的区域。
• 静态地图图像：创建位置、路线和地理数据的可视化表示。

📦 安装指南

检查服务器

使用 Node.js

# 运行构建后的镜像
npm run inspect:build

使用 Docker

# 构建 Docker 镜像
docker build -t mapbox-mcp-server .

# 运行并检查服务器
npx @modelcontextprotocol/inspector docker run -i --rm --env MAPBOX_ACCESS_TOKEN="YOUR_TOKEN" mapbox-mcp-server

创建新工具

npx plop create-tool
# 提供不带后缀的工具名称（例如 Search）

OpenTelemetry 跟踪

此 MCP 服务器包含全面的 OpenTelemetry 跟踪，用于生产可观测性：

快速演示

# 1. 复制示例配置
cp .env.example .env

# 2. 编辑 .env 文件，添加 MAPBOX_ACCESS_TOKEN 并配置跟踪

# 3. 启动 Jaeger 进行本地开发
npm run tracing:jaeger:start

# 4. 运行服务器（它将自动使用 .env 配置）
npm run inspect:build

# 5. 在 http://localhost:16686 查看跟踪信息

# 6. 完成后停止 Jaeger
npm run tracing:jaeger:stop

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

支持的可观测性平台

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

• 云提供商：
  • ☁️ AWS X - Ray
  • ☁️ Azure Monitor（应用程序洞察）
  • ☁️ Google Cloud Trace
• SaaS 平台：
  • 📊 Datadog
  • 📊 New Relic
  • 📊 Honeycomb
  • 📊 任何支持 OTLP 的后端

生产配置

有关完整的设置说明，包括特定平台的配置指南、身份验证和端点设置、自定义跟踪属性和上下文、性能优化（最小开销）以及故障排除和调试，请参阅 docs/tracing.md。

跟踪功能：

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

💻 使用示例

资源读取工具

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

• 参数：
  • uri：要读取的资源 URI（例如，mapbox://categories，mapbox://categories/ja）
• 示例用法：
  • 读取默认类别：{"uri": "mapbox://categories"}
  • 读取日语类别：{"uri": "mapbox://categories/ja"}

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

Mapbox API 工具

类别列表工具（已弃用）

⚠️ 已弃用：请使用 resource_reader_tool 和 URI mapbox://categories，或者如果客户端支持 MCP 资源，可直接访问 mapbox://categories 资源。此工具仅用于与不支持 MCP 资源或 resource_reader_tool 的客户端保持向后兼容。

矩阵工具

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

• 高效的一对多、多对一或多对多路线计算。
• 支持不同的旅行配置文件（driving - traffic、driving、walking、cycling）。
• 指定出发时间以进行考虑交通情况的计算。
• 路线汇总，包含距离和持续时间指标。
• 控制接近方式（路边/无限制）和允许的出发方位范围。

静态图像工具

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

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

类别搜索工具

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

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

反向地理编码工具

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

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

路线规划工具

使用 Mapbox Directions API 获取路线规划。功能包括：

• 支持不同的路线配置文件：驾车（实时交通或典型情况）、步行和骑自行车。
• 支持多个路点（2 - 25 个坐标对）的路线规划。
• 可选替代路线。
• 路线注释（距离、持续时间、速度、拥堵情况）。
• 调度选项：
  • 驾车和 driving - traffic 配置文件的未来出发时间 (depart_at)。
  • 仅驾车配置文件的期望到达时间 (arrive_by)。
• 特定配置文件的优化：
  • 驾车：车辆尺寸限制（高度、宽度、重量）。
• 路线排除选项：
  • 常见排除项：渡轮路线、仅收现金的收费站。
  • 驾车特定排除项：收费站、高速公路、未铺砌道路、隧道、国界、州界。
  • 自定义点排除（最多 50 个要避开的地理点）。
• GeoJSON 几何输出格式。

等时线工具

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

• 支持不同的旅行配置文件（驾车、步行、骑自行车）。
• 可自定义旅行时间或距离。
• 多轮廓生成（例如，15、30、45 分钟范围）。
• 可选的出发或到达时间指定。
• 可视化颜色自定义。

搜索和地理编码工具

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

📚 详细文档

MCP 资源

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

• 可用资源：
  • Mapbox 类别资源：
    • URI 模式：mapbox://categories 或 mapbox://categories/{language}
    • 访问可用于类别搜索工具的完整类别 ID 列表。类别可用于按类型过滤搜索结果（例如，“餐厅”、“酒店”、“加油站”）。
    • 示例：
      • mapbox://categories - 默认（英语）类别列表
      • mapbox://categories/ja - 日语类别名称
      • mapbox://categories/es - 西班牙语类别名称
    • 访问资源：
      • 支持原生 MCP 资源的客户端：使用 resources/read MCP 协议方法
      • 不支持资源的客户端：使用 resource_reader_tool 和资源 URI

MCP - UI 支持

此 MCP 服务器支持 MCP - UI，这是一个开放规范，允许兼容的客户端渲染交互式 UI 元素，如嵌入式 iframe。这提供了更丰富的视觉体验，同时与不支持 MCP - UI 的客户端保持完全向后兼容。

• 什么是 MCP - UI：MCP - UI 使工具能够在其标准输出之外返回交互式 UI 资源。兼容的客户端可以将这些资源渲染为嵌入式 iframe，而不支持 MCP - UI 的客户端则简单地忽略它们并使用标准输出。
• 支持的工具：
  • 静态地图图像工具：返回图像数据和可嵌入的 iframe URL，用于内联地图可视化。
• 优点：
  • 增强体验：兼容的客户端（例如 Goose）可以在不离开聊天界面的情况下内联显示地图。
  • 向后兼容：不支持的客户端（例如 Claude Desktop）继续正常工作。
  • 无需配置：MCP - UI 默认启用。
• 配置：MCP - UI 默认启用。若要禁用它：
  • 通过环境变量：

ENABLE_MCP_UI=false npm run build

• 通过命令行标志：

node dist/esm/index.js --disable-mcp-ui

• 在 Claude Desktop 配置中：

{
  "mcpServers": {
    "mapbox": {
      "command": "npx",
      "args": ["-y", "@mapbox/mcp-server", "--disable-mcp-ui"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

有关更详细的信息，包括兼容的客户端、技术实现细节和故障排除，请参阅 MCP - UI 文档。

🔧 技术细节

数据使用与隐私

发送到 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 服务器问题

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

关于 Mapbox API 问题

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

维护承诺

此 MCP 服务器由 Mapbox, Inc. 正式维护。提供以下服务：

• 为新的 Mapbox API 功能提供定期更新。
• 修复错误和进行安全更新。
• 与最新的 MCP 协议版本保持兼容。
• 通过 GitHub 问题提供社区支持。

📄 许可证

MIT 许可证