Mapbox

官方

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

GitHub
370

你可以用 Mapbox MCP 做什麼？

  • 地理編碼與搜尋地點 — 將地址轉換為座標，或搜尋咖啡店、加油站等興趣點，使用 search_and_geocode_tool。
  • 取得路線指引 — 使用 directions_tool 取得駕車、步行或騎自行車路線，並查看交通狀況、替代路線與排除項目。
  • 尋找可到達區域 — 使用 isochrone_tool 產生等時圈多邊形，顯示在指定時間或距離內可到達的範圍。
  • 定位座標 — 使用 ground_location_tool 一次詢問座標所在的街區、附近的興趣點，以及可到達範圍。
  • 在聊天中呈現地圖 — 使用 render_map_tool 將路線、搜尋結果或自訂 GeoJSON 顯示為即時互動地圖。
  • 查詢類別 — 透過 mapbox://categories 以英文、日文或西班牙文讀取類別 ID 清單。

文件

Mapbox MCP Server

npm version

以 Node.js 實作的伺服器，透過 Model Context Protocol (MCP) 提供 Mapbox API。

為 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 Server 指南。

取得 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 工具
  • 使用者詢問 - 說明 search_and_geocode_tool 和 directions_tool 如何請使用者釐清結果或選擇路線，以及用戶端不支援此功能時如何妥善處理

範例提示

設定完成後，請在 Claude Desktop 或其他 MCP 用戶端試用以下提示：

位置定位

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

以下四個提示各自在一次工具呼叫中運用不同策略：

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

地點探索

  • 「找出帝國大廈步行可達範圍內的咖啡店」
  • 「我想從西雅圖前往波特蘭，沿途有 Starbucks 嗎？」
  • 「顯示從波士頓到紐約路線沿途的加油站」
  • 「時代廣場附近有哪些餐廳？」

導航與旅行

  • 「提供從 LAX 到好萊塢的駕車路線，並納入目前交通狀況」
  • 「從中央公園步行到時代廣場需要多久？」
  • 「計算尖峰時段從我的飯店（Four Seasons）搭計程車到 JFK 機場的時間」

視覺化與地圖

  • 「使用 Mapbox 地圖呈現工具，顯示從舊金山金門大橋到聯合廣場的路線」— 在真正的 Mapbox 地圖上呈現即時互動路線
  • 「建立地圖影像，顯示從金門大橋到漁人碼頭的路線，並在兩個地點加上標記」
  • 「顯示曼哈頓的衛星影像，並標示重要地標」
  • 「產生一張地圖，標出西雅圖市中心一英里範圍內的所有 Starbucks 門市」
  • 「在這些座標上顯示填色多邊形：[...]，並在 [...] 加上標示為 'Warehouse' 的標記」— 透過 render_map_tool 直接呈現您自己的 GeoJSON，無需使用其他 Mapbox 工具

分析與規劃

  • 「顯示從波特蘭市中心開車 30 分鐘內可抵達的區域」
  • 「計算這 3 間飯店（Marriott、Sheraton 和 Hilton）與丹佛會議中心之間的旅行時間矩陣」
  • 「找出在舊金山造訪這 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

豐富的地圖預覽 (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 以北 5km 的點」或建立搜尋偏移
  • 不需要 API 呼叫

使用範例：「太空針塔東北方 10km 的位置在哪裡？」

方位角工具

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

功能：

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

使用範例：「從這裡前往機場，我該往哪個方向走？」

中點工具

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

功能：

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

使用範例：「舊金山和紐約的中間點在哪裡？」

質心工具

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

功能：

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

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

面積工具

計算多邊形的面積。

功能：

  • 支援多種單位：平方公尺、平方公里、英畝、公頃、平方英里、平方英尺
  • 可精確計算地球表面的面積
  • 適用於任何大小的多邊形

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

邊界框工具

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

功能：

  • 適用於點、線、多邊形和多重多邊形
  • 傳回 [minLongitude, minLatitude, maxLongitude, maxLatitude]
  • 適用於視窗範圍計算和空間索引

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

緩衝區工具

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

功能：

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

使用範例：「顯示這個位置周圍 5km 的緩衝區」

簡化工具

使用 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 計算多個點之間的行程時間和距離。功能包括：

  • 高效率計算一對多、多對一或多對多路線
  • 支援不同的交通方式設定檔（driving-traffic、driving、walking、cycling）
  • 可指定出發時間，以進行交通狀況感知計算
  • 提供包含距離和時間指標的路線摘要
  • 控制行進方向（路邊／不限）和允許的出發方位角範圍

靜態影像工具

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

  • 自訂地圖樣式（街道、戶外、衛星等）
  • 可調整影像尺寸和縮放層級
  • 支援使用自訂顏色和標籤的多個標記
  • 可疊加折線和多邊形等圖層
  • 自動調整至指定座標範圍

類別搜尋工具

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

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

反向地理編碼工具

使用 Mapbox geocoding 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 組座標）
  • 可選擇替代路線
  • 路線註記（距離、時間、速度、壅塞情況）
  • 排程選項：
    • 駕車和 driving-traffic 設定檔可指定未來出發時間（depart_at）
    • 僅駕車設定檔可指定預計抵達時間（arrive_by）
  • 依設定檔提供的最佳化選項：
    • 駕車：車輛尺寸限制（高度、寬度、重量）
  • 路線排除選項：
    • 常見排除項目：渡輪路線、僅收現金的收費道路
    • 駕車專用排除項目：收費道路、高速公路、未鋪設道路、隧道、國界、州界
    • 自訂排除點（最多可避開 50 個地理位置）
  • GeoJSON 幾何圖形輸出格式

等時圈工具

使用 Mapbox Isochrone API 計算從某個位置出發，在指定時間內可抵達的區域。功能包括：

  • 支援不同的交通方式設定檔（駕車、步行、騎自行車）
  • 可自訂行程時間或距離
  • 可產生多個等值線（例如 15、30、45 分鐘範圍）
  • 可選擇指定出發或抵達時間
  • 可自訂視覺化顏色

搜尋與地理編碼工具

使用 Mapbox Search Box Text Search API 端點，搜尋並對興趣點、地址、地點及該 API 支援的其他類型進行地理編碼。 此工具整合了先前由 ForwardGeocodeTool 和 PoiSearchTool（此 MCP 伺服器的舊版工具）提供的功能。

地圖匹配工具

使用 Mapbox Map Matching API 將 GPS 軌跡吸附至道路網路。功能包括：

  • 將含有雜訊的 GPS 軌跡轉換為道路網路上的乾淨路線
  • 支援不同的交通方式設定檔（driving、driving-traffic、walking、cycling）
  • 每次請求最多可處理 100 組座標
  • 可選擇提供時間戳記，以根據速度提升準確度
  • 可依不同 GPS 品質等級設定吸附半徑
  • 路線註記（速限、距離、時間、交通壅塞情況）
  • 多種幾何圖形輸出格式（GeoJSON、polyline）

使用範例：「清理這段 GPS 軌跡並將其吸附至道路：[含時間戳記的座標]」

最佳化工具

使用 Mapbox Optimization API 找出經過多個地點的最佳路線。功能包括：

  • 為 2-12 個地點求解旅行推銷員問題（TSP）
  • 支援不同的交通方式設定檔（driving、driving-traffic、walking、cycling）
  • 可彈性設定起點和終點
  • 可最佳化往返或單程行程
  • 可選擇提供逐轉導航指示
  • 路線註記（距離、時間、速度）
  • 多種幾何圖形輸出格式（GeoJSON、polyline）

使用範例：「找出造訪這 5 個停靠點的最佳路線：[地址或座標清單]」

注意：具備進階功能（時間範圍、容量限制、多輛車）的 V2 API 已開放使用，但需要取得 beta 存取權。V2 實作已包含在程式碼庫中，但預設未註冊。

意見回饋工具

透過 Mapbox Feedback API（公開預覽版）將使用者對應用程式或代理程式的意見回饋傳送給其開發者。意見回饋會歸入擁有存取權杖的帳戶，因此當您使用自己的權杖在此伺服器上建置應用程式或代理程式時，使用者的意見回饋會與您應用程式的 Feedback Agent 報告出現在同一個動態消息中，您可以在 Feedback Explorer 中檢視。此工具不會向 Mapbox 回報問題。與 Feedback Agent 一樣，您可以透過此工具收集任何有助於了解使用者需求的產品意見，例如：

  • 已關閉、資訊有誤或位置標錯的地點
  • 找不到的地點或地址
  • 已封閉的道路、錯誤的速限或顯示錯誤的交通狀況
  • 有違規轉彎或入口的路線，或完全沒有路線
  • 與應用程式本身相關的問題，例如錯誤或建議 (application_issue)

它會傳送回饋文字、類別和位置，並傳回項目的 ID 和狀態。位置為選填，適用於與地點無關的回饋；API 要求提供位置，因此目前工具會依照 Feedback API 團隊的建議傳送 0, 0。未經使用者同意，不會傳送任何內容：支援 elicitation 的用戶端會先顯示確認提示，其他情況下，工具說明會要求模型在聊天中確認。

Public Preview 期間，Feedback API 免費。正式推出後，Feedback Agent 每筆回饋收費 $0.02。為避免重複回報同一問題，工具會在傳送前檢查該帳戶過去 30 天內的回報。如果同一類別中 50 m 範圍內有一筆仍在等待審查的回報（不會檢查未提供位置的回饋），工具會傳回該回報，而不會傳送新的回報。Feedback API 只會列出該帳戶自己的回報，因此無法偵測其他帳戶的回報。使用者表示這是不同問題時，send_anyway: true 會略過檢查。

需求：存取權杖需要 user-feedback:write 範圍才能傳送，並需要 user-feedback:read 範圍才能檢查重複回報。若沒有寫入範圍，工具會傳回錯誤訊息說明原因。若沒有讀取範圍，工具會略過檢查並在結果中說明。若要停用此工具，請使用 --disable-tools feedback_tool 啟動伺服器。

使用範例：「Mint St 上的 Blue Bottle 去年就關了，可以幫我回報嗎？」

Report 工具

將有關 Mapbox MCP 伺服器本身的回饋傳送給負責開發它的 Mapbox 團隊，例如錯誤、工具傳回錯誤或令人困惑的結果、缺少的功能或建議。回饋會以 Mapbox 自己的帳戶提交，而非你的帳戶，因此不需要額外的權杖範圍，且提交後無法讀取或撤回。此工具不適用於回報地圖、地點或路線資料錯誤。

伺服器會在文字末尾附上自身版本、用戶端名稱和版本，以及回饋所涉及的工具。未經使用者同意，不會傳送任何內容：支援 elicitation 的用戶端會先顯示確認提示，其他情況下，工具說明會要求模型在聊天中確認。

此工具使用 Feedback API 團隊為 Mapbox CLI 的 mapbox report 命令新增的端點。若要停用此工具，請使用 --disable-tools report_tool 啟動伺服器。

使用範例：「地圖沒有繪製出我的任何等時圈。可以通知 Mapbox MCP 團隊嗎？」

列出公開權杖工具

列出帳戶的公開 (pk.) 存取權杖，供代理程式在聊天以外建置網頁或應用程式時使用，以載入 Mapbox GL JS 或從瀏覽器呼叫 Mapbox API。在聊天中，render_map_tool 不需要權杖。每個權杖都會附上名稱、是否為預設權杖、URL 限制和範圍。

傳入 site_url（網頁的執行位置），若帳戶中有受該 URL 限制的權杖，工具會建議使用該權杖。否則，工具會建議使用預設公開權杖，並說明已發布的網站應改用受 URL 限制的權杖，且附上建立權杖的連結。任何人只要複製未受限制的公開權杖就能使用，相關用量會計入該帳戶。

此工具絕不會傳回秘密或臨時權杖，也無法建立權杖（建立權杖需要 tokens:write；DevKit server 的 create_token_tool 可建立權杖）。

需求：列出權杖需要 tokens:read 範圍，與聊天中的地圖用來尋找預設公開權杖的範圍相同。若使用 pk. 存取權杖，或伺服器使用自身的 MAPBOX_ACCESS_TOKEN 且已設定 MAPBOX_PUBLIC_TOKEN 時，列出權杖作業失敗，工具會改為傳回該權杖。使用自身 bearer 權杖的呼叫端（代管伺服器）絕不會取得 MAPBOX_PUBLIC_TOKEN，而受其他 URL 限制的權杖絕不會被推薦。若要停用此工具，請使用 --disable-tools list_public_tokens_tool 啟動伺服器。

使用範例：「幫我建立一個單頁網站，在 Mapbox 地圖上顯示我們三間門市的位置。」

開發

檢查伺服器

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

參與貢獻

歡迎為 Mapbox MCP Server 貢獻！提交 pull request 前，請先閱讀 CONTRIBUTING.md。

完整標準與指南：

貢獻者快速入門

  1. Fork 儲存庫並複製你的 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
  • 權杖安全性：你的 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 License