MCP服务器

Name: MCP服务器
Author: mapbox

作者：mapbox282 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

Mapbox MCP Server

这是一个使用 Node.js 实现的 Model Context Protocol (MCP) 服务器，用于 Mapbox API。

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

Mapbox MCP Server 可以通过提供无缝访问 Mapbox 综合位置智能平台的方式，将任何 AI 代理或应用程序转变为具有地理空间感知能力的系统。有了这个服务器，您的 AI 可以理解并推理地点，导航物理世界，并访问丰富的地理空间数据，包括：

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

无论您是在构建一个 AI 旅行助手、物流优化器、基于位置的推荐系统，还是任何需要理解“在哪里”的应用程序，Mapbox MCP Server 都提供了实现这一目标的空间智能。您还可以在流行的客户端（如 Claude Desktop 和 VS Code）上启用它。详情如下：

Mapbox MCP Server 演示

使用方法

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

托管 MCP 端点

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

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

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

获取 Mapbox 访问令牌的方法：

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

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

集成指南

对于不同的集成，详细的设置说明，请参阅以下指南：

Claude Desktop 设置 - 配置 Claude Desktop 与该 MCP 服务器协同工作的说明
Goose 设置 - 设置 Goose AI 代理框架，支持 MCP-UI
VS Code 设置 - 在 Visual Studio Code 中设置开发环境
Cursor AI IDE 设置 - 在 Cursor AI IDE 中设置开发环境
Smolagents 集成 - 示例展示如何连接 Smolagents AI 代理到 Mapbox 的工具

示例提示

设置后，尝试使用 Claude Desktop 或其他 MCP 客户端的这些提示：

地点发现

"找到帝国大厦附近步行范围内的咖啡店"
"显示从波士顿到纽约沿途的加油站"
"时代广场附近有哪些餐厅？"

导航与旅行

"获取从 LAX 到好莱坞的驾驶方向，考虑当前交通状况"
"从中央公园到时代广场步行需要多长时间？"
"计算高峰时段从我的酒店（四季酒店）到 JFK 机场打车的旅行时间"

可视化与地图

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

分析与规划

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

提高结果的小贴士

对地点具体描述（使用完整的地址或地标名称）
指定首选的出行方式（驾驶、步行、骑自行车）
当相关时包含时间限制（“高峰时段”，“下午3点”）
需要时指定具体的输出格式（“作为地图图像”，“JSON 格式”）

资源

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，这是一个开放规范，允许兼容客户端渲染嵌入式 iframe 等交互式 UI 元素。这提供了更丰富的视觉体验，同时保持与不支持 MCP-UI 的客户端的完全向后兼容性。

什么是 MCP-UI？

MCP-UI 允许工具返回标准输出之外的交互式 UI 资源。兼容客户端可以将这些资源渲染为嵌入式 iframe，而不支持 MCP-UI 的客户端则忽略它们并使用标准输出。

支持的工具

静态地图图像工具：返回图像数据和嵌入式 iframe URL，用于在线地图可视化

优点

增强体验：兼容客户端（例如，Goose）可以在聊天中内联显示地图，无需离开聊天界面
向后兼容：不支持 MCP-UI 的客户端（例如，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 文档。

工具

实用工具

资源阅读器工具

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

参数：

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

示例用法：

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

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

Mapbox API 工具

类别列表工具（已弃用）

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

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

矩阵工具

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

高效的一对多、多对一或多对多路线计算
支持不同的旅行配置文件（驾驶-交通、驾驶、步行、骑自行车）
出发时间指定，用于考虑交通状况的计算
路线总结，包括距离和持续时间指标
控制接近方式（路边/不限制）和允许的出发方向范围

静态图像工具

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

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

类别搜索工具

使用 Mapbox 搜索框类别搜索 API 进行类别搜索。功能包括：

按类别搜索兴趣点（餐厅、酒店、加油站等）
按地理位置筛选
自定义结果限制
每个结果的丰富元数据
支持多种语言

逆地理编码工具

使用 Mapbox 地理编码 V6 API 进行逆地理编码。功能包括：

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

方向工具

使用 Mapbox 方向 API 获取路线方向。功能包括：

支持不同的路线配置文件：驾驶（带实时交通或典型情况）、步行和骑自行车
多个途经点（2-25 个坐标对）
替代路线选项
路线注释（距离、持续时间、速度、拥堵）
时间安排选项：
- 未来出发时间（depart_at）适用于驾驶和驾驶-交通配置文件
- 希望到达时间（arrive_by）仅适用于驾驶配置文件
配置文件特定的优化：
- 驾驶：车辆尺寸约束（高度、宽度、重量）
路线排除选项：
- 常见排除项：渡轮路线、现金支付的收费公路
- 驾驶特定排除项：收费公路、高速公路、未铺设道路、隧道、国家边界、州边界
- 自定义点排除（最多 50 个地理点以避免）
GeoJSON 几何输出格式

等时线工具

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

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

搜索和地理编码工具

使用 Mapbox 搜索框文本搜索 API 端点来驱动 POI、地址、地点和其他受该 API 支持类型的搜索和地理编码。此工具整合了之前由 ForwardGeocodeTool 和 PoiSearchTool（来自此 MCP 服务器早期版本）提供的功能。

开发

检查服务器

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

贡献

我们欢迎对 Mapbox MCP Server 的贡献！请在贡献前查阅我们的标准和指南：

工程标准 (CLAUDE.md) - 所有贡献者的代码质量、测试、文档和协作标准
AI 代理指令 (AGENTS.md) - 与本代码库合作的 AI 代理的综合指南
GitHub Copilot 指南 - 在本项目中负责任地使用 GitHub Copilot 的最佳实践

贡献者快速入门

分叉仓库并克隆您的分叉
遵循我们的工程标准中的开发设置
按照我们的编码标准进行更改
为任何新功能添加测试
提交清晰描述的拉取请求

所有贡献必须通过我们的 CI 检查和代码审查过程。请参阅 CLAUDE.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 服务器问题

电子邮件：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 问题的社区