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 許可證