Mapbox

官方

透過 Mapbox API 解鎖地理空間智慧，包括地理編碼、興趣點搜尋、路線規劃、等時線等功能。

GitHub
351

你可以用 Mapbox MCP 做什麼？

  • 搜尋與地理編碼地點 — 透過 search_and_geocode_tool 查詢地址、興趣點或地標，並可選擇類別篩選與語言支援。
  • 取得逐步導航路線 — 使用 directions_tool 請求開車、步行或騎車路線，支援即時交通、中途點與排除條件。
  • 在即時地圖上視覺化結果 — 利用 render_map_tool 在聊天中將路線、搜尋結果或自訂 GeoJSON 顯示為互動式地圖。
  • 執行離線地理空間計算 — 使用 distance_tool 與 buffer_tool 等工具在本機計算距離、面積、方位角、緩衝區與中心點，無需呼叫 API。
  • 將 GPS 軌跡對齊至道路 — 使用 map_matching_tool 清理雜訊座標並比對至道路網路，可選擇加入時間戳記。
  • 最佳化多站點路線 — 使用 optimization_tool 解決最多 12 個地點的旅行推銷員問題，支援往返或單程行程。

文件

Mapbox MCP Server

npm version

Node.js 伺服器，為 Mapbox API 實作模型上下文協定（Model Context Protocol，MCP）。

為您的 AI 應用程式解鎖地理空間智慧

Mapbox MCP Server 將任何 AI 代理程式或應用程式轉變為具備地理空間感知能力的系統，提供對 Mapbox 全面位置智慧平台的無縫存取。透過此伺服器，您的 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 伺服器指南。

若要取得 Mapbox 存取權杖：

  1. 在 mapbox.com/signup 免費註冊 Mapbox 帳戶
  2. 前往您的帳戶頁面
  3. 建立新權杖或使用預設的公開權杖

有關 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 工具的範例
  • 直接匯入工具 - 在您自己的應用程式中使用 Mapbox 工具，無需執行 MCP 伺服器
  • render_map_tool 指南 - 地圖視覺化原語：完整的負載結構描述，以及如何獨立渲染您自己的資料，無需任何其他 Mapbox 工具
  • Elicitations - search_and_geocode_tool 和 directions_tool 如何要求使用者釐清結果或選擇路線，以及在用戶端不支援時如何優雅地退回

範例提示詞

設定完成後，請在 Claude Desktop 或其他 MCP 用戶端嘗試這些提示詞：

位置定位

對於以座標為主的查詢 — 「我附近有什麼」、「這是哪個街區」、「N 分鐘內可到達什麼」— 請使用 ground_location_tool。它會在單一呼叫中組合反向地理編碼、類別搜尋和等時線，根據查詢自適應地選擇正確的策略，並傳回帶有引用的型別化記錄（名稱、地址、座標、距離、可及性多邊形）。

以下四個提示詞分別在單一工具呼叫中演練不同的策略：

  • 街區 — 「47.6097, -122.3408 是哪個街區，我附近有什麼？」
  • 興趣點 — 「40.7580, -73.9855 步行 10 分鐘內的咖啡店」
  • 區域 — 「從 37.7749, -122.4194 步行 15 分鐘內可以到達什麼？」
  • 路線規劃 — 「距離 34.0522, -118.2437 最近的可行駛點，以便讓人在那裡下車」

地點探索

  • 「尋找帝國大廈步行距離內的咖啡店」
  • 「我想從西雅圖去波特蘭，沿途有星巴克嗎？」
  • 「顯示從波士頓到紐約沿途的加油站」
  • 「時代廣場附近有哪些餐廳？」

導航與旅行

  • 「取得從 LAX 到好萊塢的開車路線，包含目前交通狀況」
  • 「從中央公園步行到時代廣場需要多長時間？」
  • 「計算尖峰時段從我的飯店（四季飯店）搭計程車到 JFK 機場的旅行時間」

視覺化與地圖

  • 「使用 Mapbox 地圖渲染工具，顯示從金門大橋到舊金山聯合廣場的路線」— 在真實的 Mapbox 地圖上渲染即時互動式路線
  • 「建立一張地圖影像，顯示從金門大橋到漁人碼頭的路線，並在兩個位置標記」
  • 「顯示曼哈頓的衛星檢視，並標記主要地標」
  • 「生成一張地圖，標示西雅圖市中心一英里內的所有星巴克位置」
  • 「在這些座標上顯示填色多邊形：[...]，並在 [...] 放置標記為『倉庫』的標記」— 直接透過 render_map_tool 渲染您自己的 GeoJSON，無需其他 Mapbox 工具

分析與規劃

  • 「顯示波特蘭市中心開車 30 分鐘內可到達的區域」
  • 「計算丹佛這 3 家飯店位置（萬豪、喜來登和希爾頓）與會議中心之間的旅行時間矩陣」
  • 「找出造訪舊金山這 3 個旅遊景點（金門大橋、音樂階梯和漁人碼頭）的最佳路線」
  • 「最佳化這 8 個地址的配送路線：[地址清單]」

GPS 與路線匹配

  • 「清理這條 GPS 軌跡，並在道路上顯示實際路線：[帶時間戳記的座標清單]」
  • 「將這段記錄的自行車騎乘路線對齊到自行車網路：[GPS 座標]」
  • 「將這條開車路線匹配到道路網路，並顯示交通壅塞程度」

離線地理空間計算

  • 「這兩個座標之間的距離是多少英里？」
  • 「計算這個多邊形的面積（平方公里）」
  • 「座標 37.7749°N, 122.4194°W 的點是否在此服務區域多邊形內？」
  • 「從舊金山到紐約的方位角是多少？」
  • 「找出倫敦和巴黎之間的中點」
  • 「在此位置周圍建立 5 英里緩衝區」
  • 「計算此街區邊界的質心」
  • 「這些路線座標的邊界框是什麼？」
  • 「簡化這個複雜的多邊形以減少點的數量」

獲得更好結果的提示

  • 具體說明位置（使用完整地址或地標名稱）
  • 指定您偏好的旅行方式（開車、步行、騎自行車）
  • 在相關時包含時間限制（「尖峰時段」、「下午 3 點」）
  • 在需要時要求特定輸出格式（「作為地圖影像」、「以 JSON 格式」）

詳細範例： 請參閱 examples/search-along-route.md 以取得 search-along-route 提示詞在不同使用案例下的完整範例，以及 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

豐富地圖預覽（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

資源退回工具（針對不符合規範的用戶端選擇性啟用）

資源是 MCP 的核心功能，大多數用戶端（Claude Desktop、VS Code、MCP Inspector 等）都支援。然而，某些用戶端（如 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 以北 5 公里的點」或建構搜尋偏移
  • 無需 API 呼叫

範例用法：「太空針塔東北方 10 公里的點在哪裡？」

方位角工具

計算從一個座標到另一個座標的羅盤方向（方位角）。

功能：

  • 以度數（0-360°）回傳方位角
  • 提供主要方位（N、NE、E、SE、S、SW、W、NW）
  • 適用於導航與方向查詢

範例用法：「從這裡到機場應該朝哪個方向前進？」

中點工具

沿著大圓路徑找出兩個座標之間的地理中點。

功能：

  • 計算地球曲面上的真實中點
  • 適用於會面點建議
  • 正確處理長距離計算

範例用法：「舊金山與紐約之間的中點在哪裡？」

質心工具

計算多邊形或多重多邊形的幾何中心（質心）。

功能：

  • 支援複雜形狀
  • 回傳所有點的算術平均
  • 適用於放置標籤或標記

範例用法：「我應該把這個社區邊界的標記放在哪裡？」

面積工具

計算多邊形的面積。

功能：

  • 支援多種單位：平方公尺、平方公里、英畝、公頃、平方英里、平方英尺
  • 在地球表面上進行精確的面積計算
  • 支援任意大小的多邊形

範例用法：「這個公園的面積是多少英畝？」

邊界框工具

計算包含幾何形狀的最小邊界框（bbox）。

功能：

  • 支援點、線、多邊形與多重多邊形
  • 回傳 [最小經度, 最小緯度, 最大經度, 最大緯度]
  • 適用於視窗計算與空間索引

範例用法：「這條路線的邊界框是什麼？」

緩衝區工具

在點、線或多邊形周圍建立緩衝區（多邊形）。

功能：

  • 支援多種距離單位
  • 在點周圍建立圓形緩衝區
  • 適用於鄰近分析與建立影響範圍

範例用法：「顯示此位置周圍 5 公里的緩衝區」

簡化工具

使用 Douglas-Peucker 演算法減少線或多邊形中的頂點數量。

功能：

  • 可設定的容差以控制細節程度
  • 在降低複雜度的同時保留整體形狀
  • 適用於減少檔案大小與提升渲染效能
  • 可選擇維持拓撲（防止自相交）

範例用法：「簡化這個複雜邊界以減少點的數量」

長度工具

測量由一系列座標定義的線的總長度。

功能：

  • 支援公里、英里、公尺與英尺
  • 適用於測量繪製的路線、路徑或邊界，無需路由 API 呼叫

範例用法：「這條健行步道有多長？」

凸包工具

計算一組點的凸包——包含所有點的最小凸多邊形。

功能：

  • 適用於邊界區域分析或估算覆蓋範圍
  • 離線運作，無需 API 呼叫

範例用法：「包含所有這些商店位置的最小多邊形是什麼？」

最近點工具

在集合中找出距離指定目標點最近的點。

功能：

  • 比對每個候選點呼叫 distance_tool 再排序更有效率
  • 適用於找出距離某位置最近的商店、站點或地標

範例用法：「這些商店中哪一家離我目前位置最近？」

線上最近點工具

將點吸附到線或路線上的最近位置，回傳該點及其距離。

功能：

  • 適用於「這條路線上哪個點離我最近？」或無需 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 計算多個點之間的旅行時間與距離。功能包括：

  • 高效的一對多、多對一或多對多路由計算
  • 支援不同的旅行設定檔（即時交通駕駛、駕駛、步行、騎乘）
  • 可指定出發時間以進行交通感知計算
  • 路線摘要，包含距離與持續時間指標
  • 控制接近方式（路緣/不受限制）與允許的出發方位角範圍

靜態影像工具

使用 Mapbox 靜態影像 API 產生靜態地圖影像。功能包括：

  • 自訂地圖樣式（街道、戶外、衛星等）
  • 可調整的影像尺寸與縮放等級
  • 支援多個標記，可自訂顏色與標籤
  • 疊加選項，包括折線與多邊形
  • 自動調整以符合指定座標

類別搜尋工具

使用 Mapbox Search Box 類別搜尋 API 執行類別搜尋。功能包括：

  • 依類別搜尋興趣點（餐廳、飯店、加油站等）
  • 依地理鄰近性篩選
  • 可自訂結果數量上限
  • 每個結果的豐富中繼資料
  • 支援多種語言

反向地理編碼工具

使用 Mapbox 地理編碼 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 個座標對）規劃路線
  • 替代路線選項
  • 路線註解（距離、持續時間、速度、壅塞程度）
  • 排程選項：
    • 未來出發時間（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 可用，但需要 Beta 存取權限。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 版本是否與發佈版本相符。跳過版本提升或 manifest 同步將導致發佈失敗。

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 檔案載入）
  • ✅ 自動工具執行追蹤
  • ✅ HTTP 請求監測，包含 CloudFront 關聯 ID
  • ✅ 可設定的匯出器（console、OTLP）
  • ✅ 注重安全性（資料保護、JWT 驗證）
  • ✅ 可投入生產環境（CPU 額外負擔低於 1%）

貢獻

我們歡迎您對 Mapbox MCP Server 做出貢獻！請在提交 pull request 前閱讀 CONTRIBUTING.md。

完整的標準與指南：

貢獻者快速入門

  1. Fork 儲存庫並 clone 您的 fork
  2. 安裝相依套件：npm install
  3. 依照我們的程式碼標準進行修改
  4. 執行測試與 lint：npm test && npm run lint
  5. 為任何新功能新增測試
  6. 提交附有清楚說明的 pull request

所有貢獻都必須通過我們的 CI 檢查與程式碼審查流程。詳細要求請參閱 docs/engineering_standards.md。

資料使用與隱私

傳送至 Mapbox API 的資料

當您使用 MCP 伺服器工具時，以下資料會直接從您的環境傳送至 Mapbox API：

  • 地理編碼工具：地址/地點文字、座標、國家/地區篩選條件
  • 搜尋工具：搜尋查詢、用於鄰近搜尋的地點座標、類別篩選條件
  • 路線規劃工具：起點/終點座標、中途點、路線偏好、車輛限制
  • 矩陣工具：多組座標對、行進設定檔、出發時間
  • 靜態地圖工具：座標、縮放等級、樣式偏好、標記資訊
  • 等時線工具：起點座標、時間/距離參數、行進設定檔

您的隱私

  • 本機執行：所有 API 呼叫皆直接從您的環境傳送至 Mapbox API
  • Token 安全性：您的 Mapbox API token 會保留在您的本機機器上，絕不會傳輸至或儲存在此 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 授權