Mapbox MCP Server

Mapbox MCP 伺服器

實作 Mapbox API 模型內容協定 (MCP) 的 Node.js 伺服器。

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

Mapbox MCP 伺服器能將任何 AI 代理或應用程式轉變為具備地理空間感知能力的系統，提供對 Mapbox 全方位位置智慧平台的無縫存取。透過此伺服器，您的 AI 可以理解並推理地點、導航實體世界，並存取豐富的地理空間資料，包括：

• 全球地理編碼：將地址和地名轉換為座標，反之亦然
• 興趣點 (POI) 搜尋：搜尋全球數百萬個商家、地標和地點
• 多模式路線規劃：提供開車、步行和自行車路線，並包含即時交通資訊
• 旅行時間矩陣：分析可及性並最佳化物流
• 路線最佳化：為多個停靠點找出最佳造訪順序（旅行推銷員問題）
• 地圖匹配：將 GPS 軌跡對應到道路網路，以獲得清晰的路線視覺化
• 等時圈生成：視覺化在特定時間或距離限制內可到達的區域
• 靜態地圖圖片：建立地點、路線和地理資料的視覺化呈現
• 離線地理空間計算：無需 API 呼叫即可進行距離、面積、方位角、緩衝區和空間分析

無論您正在建構 AI 旅遊助理、物流最佳化工具、基於位置的推薦系統，或任何需要理解「地點」的應用程式，Mapbox MCP 伺服器都能提供實現這一切的空間智慧。您也可以在 Claude Desktop 和 VS Code 等熱門客戶端上啟用它。詳情請見下方

使用方式

使用此 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 伺服器

提示範例

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

地點探索

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

導航與旅遊

• 「取得從洛杉磯國際機場到好萊塢的開車路線，包含當前交通狀況」
• 「從中央公園步行到時代廣場需要多長時間？」
• 「計算從我的飯店（四季酒店）到甘迺迪機場在尖峰時段搭乘計程車的旅行時間」

視覺化與地圖

• 「建立一張地圖圖片，顯示從金門大橋到漁人碼頭的路線，並在兩個地點標記」
• 「顯示曼哈頓的衛星視圖，並標記主要地標」
• 「生成一張地圖，突顯西雅圖市中心一英里範圍內的所有星巴克位置」

分析與規劃

• 「顯示波特蘭市中心開車 30 分鐘內可到達的區域」
• 「計算丹佛這 3 個飯店地點（萬豪、喜來登和希爾頓）與會議中心之間的旅行時間矩陣」
• 「找出造訪舊金山這 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 的完整清單，以便與類別搜尋工具搭配使用。類別可用於按類型篩選搜尋結果（例如「餐廳」、「飯店」、「加油站」）。

範例：

• mapbox://categories - 預設（英文）類別清單
• mapbox://categories/ja - 日文類別名稱
• mapbox://categories/es - 西班牙文類別名稱

存取資源：

• 支援原生 MCP 資源的客戶端：使用 resources/read MCP 協定方法
• 不支援資源的客戶端：使用 resource_reader_tool 搭配資源 URI

豐富的地圖預覽（MCP Apps）

static_map_image_tool 在相容的客戶端中提供互動式地圖預覽面板，這是所有客戶端都會收到的 base64 圖片之外的附加功能。

此伺服器實作了 MCP Apps 協定 (@modelcontextprotocol/ext-apps)，它會在聊天中直接呈現一個獨立的 HTML 應用程式面板。支援的客戶端會顯示一個帶有全螢幕切換功能的互動式地圖：

• Claude Desktop ✅
• VS Code（搭配 GitHub Copilot） ✅
• Claude Code ✅
• Goose ✅

無論協定支援與否，所有客戶端都會收到 base64 編碼的地圖圖片 — 互動式預覽是在標準圖片回應之上的漸進增強功能。

舊版：MCP-UI

此伺服器也保留了對 MCP-UI (@mcp-ui/server) 的支援，這是一個較早的嵌入式 iframe 預覽開放規範。MCP Apps 是建議使用的協定；保留 MCP-UI 支援是為了向下相容。

MCP-UI 預設為啟用。若要停用它，請傳遞 --disable-mcp-ui 作為命令列旗標，或設定 ENABLE_MCP_UI=false。詳情請參閱 MCP-UI 文件。

CLIENT_NEEDS_RESOURCE_FALLBACK

資源備用工具（針對不相容的客戶端選擇性加入）

資源是大多數客戶端（Claude Desktop、VS Code、MCP Inspector 等）支援的核心 MCP 功能。但是，某些客戶端（如 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) 之間的距離是多少？」

點在多邊形內工具

測試一個點是否在多邊形或多多邊形內。

功能：

• 適用於包含孔洞的複雜多邊形
• 支援多多邊形
• 適用於地理圍欄和服務區域檢查

使用範例：「這個送貨地址在我們的服務區域內嗎？」

方位角工具

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

功能：

• 返回以度為單位的方位角 (0-360°)
• 提供基本方向（北、東北、東、東南、南、西南、西、西北）
• 適用於導航和方向查詢

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

中點工具

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

功能：

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

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

中心點工具

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

功能：

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

使用範例：「我應該在哪裡為這個鄰里邊界放置標記？」

面積工具

計算多邊形的面積。

功能：

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

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

邊界框工具

計算包含一個幾何圖形的最小邊界框 (bbox)。

功能：

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

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

緩衝區工具

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

功能：

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

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

簡化工具

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

功能：

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

使用範例：「簡化此複雜邊界以減少點數」

Mapbox API 工具

類別清單工具（已棄用）

⚠️ 已棄用：請改用 resource_reader_tool 搭配 URI mapbox://categories，或若您的客戶端支援 MCP 資源，可直接存取 mapbox://categories 資源。

此工具保留用於向後相容不支援 MCP 資源或 resource_reader_tool 的客戶端。

矩陣工具

使用 Mapbox Matrix API 計算多點之間的旅行時間與距離。功能包括：

• 高效率的一對多、多對一或多對多路徑計算
• 支援不同的旅行設定檔（開車-交通、開車、步行、騎自行車）
• 可指定出發時間以進行交通感知計算
• 包含距離與時間指標的路線摘要
• 控制接近方式（路邊/無限制）及允許的出發方位範圍

靜態圖片工具

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

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

類別搜尋工具

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

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

反向地理編碼工具

使用 Mapbox 地理編碼 V6 API 執行反向地理編碼。功能包括：

• 將地理座標轉換為人類可讀的地址
• 可自訂的詳細程度（街道、鄰里、城市等）
• 按類型篩選結果（地址、興趣點、鄰里等）
• 支援多種語言
• 豐富的位置脈絡資訊

路線工具

使用 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 版本是否與發行版本相符。跳過版本遞增或清單同步將導致發佈失敗。

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 檔案載入）
• ✅ 自動工具執行追蹤
• ✅ 帶有 CloudFront 關聯 ID 的 HTTP 請求檢測
• ✅ 可設定的匯出器（主控台、OTLP）
• ✅ 安全意識（資料保護、JWT 驗證）
• ✅ 生產就緒（<1% CPU 負擔）

貢獻

我們歡迎對 Mapbox MCP 伺服器的貢獻！在提交拉取請求前，請閱讀 CONTRIBUTING.md。

完整的標準與指南：

• CONTRIBUTING.md - 入門、PR 流程、快速參考
• 工程標準 (docs/engineering_standards.md) - 完整的程式碼品質、測試、文件與協作標準
• Claude Code 指南 (CLAUDE.md) - 使用 Claude Code 的貢獻者標準與模式
• AI 代理指令 (AGENTS.md) - 其他 AI 編碼助手（Cursor、Continue、Aider 等）的指南
• GitHub Copilot 指南 - 負責任地使用 GitHub Copilot 的最佳實務

貢獻者快速入門

1. Fork 儲存庫並複製您的 fork
2. 安裝相依套件：npm install
3. 遵循我們的編碼標準進行變更
4. 執行測試與程式碼檢查：npm test && npm run lint
5. 為任何新功能新增測試
6. 提交帶有清晰描述的拉取請求

所有貢獻都必須通過我們的 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 伺服器問題

• 電子郵件：[email protected]
• GitHub Issues：回報錯誤與功能請求

針對 Mapbox API 問題

• Mapbox 支援：https://support.mapbox.com/
• 文件：https://docs.mapbox.com/
• API 狀態：https://status.mapbox.com/

維護承諾

此 MCP 伺服器由 Mapbox, Inc. 正式維護。我們提供：

• 針對新 Mapbox API 功能的定期更新
• 錯誤修正與安全性更新
• 與最新 MCP 協定版本的相容性
• 透過 GitHub issues 的社群支援

---

MIT 授權