Mapbox

Mapbox MCP Server

Máy chủ Node.js triển khai Model Context Protocol (MCP) cho các API của Mapbox.

Mở khóa trí tuệ không gian địa lý cho các ứng dụng AI của bạn

Mapbox MCP Server biến mọi tác nhân hoặc ứng dụng AI thành một hệ thống có nhận thức về không gian địa lý bằng cách cung cấp quyền truy cập liền mạch vào nền tảng trí tuệ vị trí toàn diện của Mapbox. Với máy chủ này, AI của bạn có thể hiểu và suy luận về các địa điểm, điều hướng trong thế giới thực và truy cập dữ liệu không gian địa lý phong phú, bao gồm:

• Mã hóa địa lý toàn cầu để chuyển đổi địa chỉ và tên địa điểm thành tọa độ và ngược lại
• Tìm kiếm điểm quan tâm (POI) trên hàng triệu doanh nghiệp, địa danh và địa điểm trên toàn thế giới
• Định tuyến đa phương thức cho lái xe, đi bộ và đi xe đạp với thông tin giao thông theo thời gian thực
• Ma trận thời gian di chuyển để phân tích khả năng tiếp cận và tối ưu hóa hậu cần
• Tối ưu hóa tuyến đường để tìm thứ tự ghé thăm tối ưu cho nhiều điểm dừng (bài toán người bán hàng)
• Khớp bản đồ để căn chỉnh các vệt GPS với mạng lưới đường nhằm trực quan hóa tuyến đường rõ ràng
• Tạo vùng đẳng thời gian để trực quan hóa các khu vực có thể đến được trong giới hạn thời gian hoặc khoảng cách cụ thể
• Hiển thị bản đồ trực tiếp, tương tác (render_map_tool) để hiển thị tuyến đường, kết quả tìm kiếm và GeoJSON tùy chỉnh của bạn trên bản đồ Mapbox GL JS thực ngay bên trong cuộc trò chuyện
• Ảnh bản đồ tĩnh để tạo hình ảnh trực quan về địa điểm, tuyến đường và dữ liệu địa lý
• Tính toán không gian địa lý ngoại tuyến về khoảng cách, diện tích, phương vị, vùng đệm và phân tích không gian mà không cần gọi API

Dù bạn đang xây dựng trợ lý du lịch AI, công cụ tối ưu hóa hậu cần, hệ thống đề xuất dựa trên vị trí hay bất kỳ ứng dụng nào cần hiểu “ở đâu”, Mapbox MCP Server cung cấp trí tuệ không gian để biến điều đó thành hiện thực. Bạn cũng có thể bật máy chủ này trên các ứng dụng phổ biến như Claude Desktop và VS Code. Xem chi tiết bên dưới

Cách sử dụng

Cần có mã thông báo truy cập Mapbox để sử dụng MCP server này.

MCP Endpoint được lưu trữ

Để truy cập nhanh, bạn có thể sử dụng MCP endpoint được lưu trữ của chúng tôi:

Endpoint: https://mcp.mapbox.com/mcp

Để xem hướng dẫn thiết lập chi tiết cho các ứng dụng khách khác nhau và cách sử dụng API, hãy xem Hướng dẫn Hosted MCP Server.

Để lấy mã thông báo truy cập Mapbox:

1. Đăng ký tài khoản Mapbox miễn phí tại mapbox.com/signup
2. Truy cập trang Tài khoản
3. Tạo mã thông báo mới hoặc sử dụng mã thông báo công khai mặc định

Để biết thêm thông tin về mã thông báo truy cập Mapbox, hãy xem tài liệu Mapbox về mã thông báo truy cập.

Hướng dẫn tích hợp

Để xem hướng dẫn thiết lập chi tiết cho các tích hợp khác nhau, hãy tham khảo các hướng dẫn sau:

• Thiết lập Claude Desktop - Hướng dẫn cấu hình Claude Desktop để hoạt động với MCP server này
• Thiết lập Goose - Thiết lập khung tác nhân AI Goose
• Thiết lập VS Code - Thiết lập môi trường phát triển trong Visual Studio Code
• Thiết lập Cursor AI IDE - Thiết lập môi trường phát triển trong Cursor AI IDE
• Tích hợp Smolagents - Ví dụ về cách kết nối các tác nhân AI Smolagents với các công cụ của Mapbox
• Nhập trực tiếp các công cụ - Sử dụng các công cụ Mapbox trong ứng dụng của riêng bạn mà không cần chạy MCP server
• Hướng dẫn render_map_tool - Thành phần trực quan hóa bản đồ: lược đồ payload đầy đủ và cách hiển thị dữ liệu của riêng bạn độc lập, không cần bất kỳ công cụ Mapbox nào khác
• Yêu cầu người dùng cung cấp thông tin - Cách search_and_geocode_tool và directions_tool yêu cầu người dùng phân biệt kết quả hoặc chọn tuyến đường, cũng như cách chúng xử lý linh hoạt khi ứng dụng khách không hỗ trợ tính năng này

Prompt mẫu

Sau khi thiết lập, hãy thử các prompt này với Claude Desktop hoặc các ứng dụng khách MCP khác:

Định vị theo tọa độ

Với các truy vấn ưu tiên tọa độ — “có gì gần tôi”, “đây là khu phố nào”, “có thể đến đâu trong N phút” — hãy dùng ground_location_tool. Công cụ này kết hợp mã hóa địa lý ngược, tìm kiếm theo danh mục và vùng đẳng thời gian trong một lần gọi, tự động chọn chiến lược phù hợp dựa trên truy vấn và trả về các bản ghi có kiểu dữ liệu rõ ràng (tên, địa chỉ, tọa độ, khoảng cách, đa giác vùng có thể đến) kèm trích dẫn.

Mỗi prompt trong bốn prompt dưới đây kiểm tra một chiến lược khác nhau trong một lần gọi công cụ:

• Khu phố — “47.6097, -122.3408 thuộc khu phố nào và xung quanh tôi có gì?”
• POI — “Quán cà phê cách 40.7580, -73.9855 trong vòng 10 phút đi bộ”
• Khu vực — “Tôi có thể đi bộ đến đâu trong 15 phút từ 37.7749, -122.4194?”
• Định tuyến — “Điểm gần nhất có thể tiếp cận bằng đường để đón người tại 34.0522, -118.2437”

Khám phá địa điểm

• “Tìm quán cà phê trong khoảng cách đi bộ từ Empire State Building”
• “Tôi muốn đi từ Seattle đến Portland, trên đường có Starbucks nào không?”
• “Cho tôi xem các trạm xăng dọc tuyến đường từ Boston đến New York”
• “Có nhà hàng nào gần Times Square?”

Điều hướng & di chuyển

• “Tìm đường lái xe từ LAX đến Hollywood với tình hình giao thông hiện tại”
• “Đi bộ từ Central Park đến Times Square mất bao lâu?”
• “Tính thời gian di chuyển bằng taxi từ khách sạn của tôi (Four Seasons) đến JFK Airport vào giờ cao điểm”

Trực quan hóa & bản đồ

• “Dùng công cụ hiển thị bản đồ Mapbox, chỉ đường từ Golden Gate Bridge đến Union Square ở San Francisco” — hiển thị tuyến đường trực tiếp, tương tác trên bản đồ Mapbox thực
• “Tạo ảnh bản đồ hiển thị tuyến đường từ Golden Gate Bridge đến Fisherman's Wharf, với điểm đánh dấu ở cả hai địa điểm”
• “Cho tôi xem ảnh vệ tinh của Manhattan với các địa danh chính được đánh dấu”
• “Tạo bản đồ làm nổi bật tất cả địa điểm Starbucks trong phạm vi một dặm quanh trung tâm Seattle”
• “Hiển thị một đa giác tô màu trên các tọa độ này: [...], với điểm đánh dấu có nhãn 'Warehouse' tại [...]” — hiển thị trực tiếp GeoJSON của bạn qua render_map_tool, không cần công cụ Mapbox nào khác

Phân tích & lập kế hoạch

• “Cho tôi xem các khu vực có thể đến trong vòng 30 phút lái xe từ trung tâm Portland”
• “Tính ma trận thời gian di chuyển giữa 3 khách sạn này (Marriott, Sheraton và Hilton) và trung tâm hội nghị ở Denver”
• “Tìm tuyến đường tối ưu để ghé thăm 3 điểm tham quan này (Golden Gate, Musical Stairs và Fisherman's Wharf) ở San Francisco”
• “Tối ưu hóa tuyến giao hàng cho 8 địa chỉ này: [danh sách địa chỉ]”

GPS & khớp tuyến đường

• “Làm sạch vệt GPS này và hiển thị tuyến đường thực tế trên đường: [danh sách tọa độ kèm dấu thời gian]”
• “Căn chỉnh chuyến đi xe đạp đã ghi này với mạng lưới đường dành cho xe đạp: [tọa độ GPS]”
• “Khớp tuyến đường lái xe này với mạng lưới đường và hiển thị mức độ ùn tắc giao thông”

Tính toán không gian địa lý ngoại tuyến

• “Khoảng cách tính bằng dặm giữa hai tọa độ này là bao nhiêu?”
• “Tính diện tích của đa giác này theo kilômét vuông”
• “Điểm tại 37.7749°N, 122.4194°W có nằm trong đa giác khu vực dịch vụ này không?”
• “Phương vị từ San Francisco đến New York là bao nhiêu?”
• “Tìm điểm giữa London và Paris”
• “Tạo vùng đệm 5 dặm quanh địa điểm này”
• “Tính trọng tâm của ranh giới khu phố này”
• “Hộp giới hạn của các tọa độ tuyến đường này là gì?”
• “Đơn giản hóa đa giác phức tạp này để giảm số điểm”

Mẹo để có kết quả tốt hơn

• Nêu rõ địa điểm (dùng địa chỉ đầy đủ hoặc tên địa danh)
• Nêu phương thức di chuyển bạn muốn (lái xe, đi bộ, đi xe đạp)
• Thêm giới hạn thời gian khi phù hợp (“vào giờ cao điểm”, “lúc 3 PM”)
• Yêu cầu định dạng đầu ra cụ thể khi cần (“dưới dạng ảnh bản đồ”, “ở định dạng JSON”)

Ví dụ chi tiết: Xem examples/search-along-route.md để biết các ví dụ toàn diện về prompt tìm kiếm dọc tuyến đường với nhiều trường hợp sử dụng khác nhau và hướng dẫn kiểm thử bằng MCP Inspector.

Tài nguyên

MCP server cung cấp dữ liệu tham khảo tĩnh dưới dạng tài nguyên MCP. Tài nguyên cho phép truy cập chỉ đọc vào dữ liệu mà ứng dụng khách có thể tham chiếu trực tiếp mà không cần gọi công cụ.

Tài nguyên hiện có

Tài nguyên danh mục Mapbox

Mẫu URI: mapbox://categories hoặc mapbox://categories/{language}

Truy cập danh sách đầy đủ các ID danh mục hiện có để sử dụng với công cụ tìm kiếm theo danh mục. Có thể dùng danh mục để lọc kết quả tìm kiếm theo loại (ví dụ: “restaurant”, “hotel”, “gas_station”).

Ví dụ:

• mapbox://categories - Danh sách danh mục mặc định (tiếng Anh)
• mapbox://categories/ja - Tên danh mục bằng tiếng Nhật
• mapbox://categories/es - Tên danh mục bằng tiếng Tây Ban Nha

Truy cập tài nguyên:

• Ứng dụng khách hỗ trợ tài nguyên MCP gốc: Dùng phương thức giao thức MCP resources/read
• Ứng dụng khách không hỗ trợ tài nguyên: Dùng resource_reader_tool với URI tài nguyên

Bản xem trước bản đồ phong phú (render_map_tool)

Mọi công cụ không gian địa lý trong máy chủ này (chỉ đường, vùng đẳng thời gian, tìm kiếm, v.v.) đều có thể hiển thị kết quả dưới dạng bản đồ Mapbox GL JS trực tiếp, tương tác thông qua render_map_tool — thành phần trực quan hóa duy nhất của máy chủ. Công cụ này hiển thị bản đồ trong một bảng HTML độc lập ngay bên trong cuộc trò chuyện thông qua giao thức MCP Apps (@modelcontextprotocol/ext-apps), có nút chuyển sang chế độ toàn màn hình, trên các ứng dụng khách được hỗ trợ:

• Claude Desktop ✅
• VS Code với GitHub Copilot ✅
• Claude Code ✅
• Goose ✅

Bạn không cần bất kỳ công cụ nào khác của máy chủ này để sử dụng tính năng này. render_map_tool cũng chấp nhận GeoJSON được tạo thủ công — các đa giác, điểm đánh dấu và tuyến đường của riêng bạn — mà không phụ thuộc vào directions_tool, isochrone_tool hay bất kỳ lệnh gọi API Mapbox nào khác. Xem hướng dẫn đầy đủ về render_map_tool để biết lược đồ payload và ví dụ độc lập hoàn chỉnh.

Nếu bạn cần ảnh tĩnh được đảm bảo hiển thị trên các ứng dụng khách không hỗ trợ MCP Apps, hãy dùng static_map_image_tool thay thế — công cụ này trả về PNG/JPEG được mã hóa base64 mà mọi ứng dụng khách đều có thể hiển thị.

CLIENT_NEEDS_RESOURCE_FALLBACK

Công cụ dự phòng cho tài nguyên (Bật tùy chọn cho ứng dụng khách không tuân thủ)

Tài nguyên là tính năng cốt lõi của MCP được hầu hết ứng dụng khách hỗ trợ (Claude Desktop, VS Code, MCP Inspector, v.v.). Tuy nhiên, một số ứng dụng khách (như smolagents) hoàn toàn không hỗ trợ tài nguyên. Với các ứng dụng khách này, máy chủ có thể cung cấp “công cụ dự phòng cho tài nguyên”, cung cấp cùng nội dung như tài nguyên nhưng thông qua các lệnh gọi công cụ.

Công cụ dự phòng:

• resource_reader_tool - Công cụ dự phòng tổng quát để đọc mọi tài nguyên theo URI
• category_list_tool - Cung cấp quyền truy cập vào danh sách danh mục (mapbox://categories)

Theo mặc định, các công cụ này KHÔNG được đưa vào (giả định ứng dụng khách của bạn hỗ trợ tài nguyên). Nếu ứng dụng khách không hỗ trợ tài nguyên, hãy bật các công cụ dự phòng:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Khi nào cần đặt giá trị này:

• ✅ Đặt thành true nếu dùng smolagents hoặc ứng dụng khách khác không hỗ trợ tài nguyên
• ❌ Để trống (mặc định) nếu dùng Claude Desktop, VS Code, MCP Inspector hoặc ứng dụng khách hỗ trợ tài nguyên
• ❌ Để trống nếu không chắc chắn (hầu hết ứng dụng khách đều hỗ trợ tài nguyên)

Công cụ

Công cụ tiện ích

Công cụ đọc tài nguyên

Cung cấp quyền truy cập vào tài nguyên MCP cho các ứng dụng khách không hỗ trợ API tài nguyên MCP gốc. Dùng công cụ này để đọc tài nguyên như danh sách danh mục.

Tham số:

• uri: URI tài nguyên cần đọc (ví dụ: mapbox://categories, mapbox://categories/ja)

Ví dụ sử dụng:

• Đọc danh mục mặc định: {"uri": "mapbox://categories"}
• Đọc danh mục tiếng Nhật: {"uri": "mapbox://categories/ja"}

Lưu ý: Nếu ứng dụng khách MCP của bạn hỗ trợ tài nguyên gốc, hãy ưu tiên dùng trực tiếp API tài nguyên để có hiệu suất tốt hơn.

Công cụ không gian địa lý ngoại tuyến

Các công cụ này thực hiện tính toán không gian địa lý hoàn toàn ngoại tuyến mà không cần gọi API Mapbox. Chúng sử dụng Turf.js để tính toán địa lý chính xác và hoạt động ở mọi nơi, kể cả khi không có kết nối internet.

Công cụ tính khoảng cách

Tính khoảng cách giữa hai tọa độ địa lý bằng công thức Haversine.

Tính năng:

• Hỗ trợ nhiều đơn vị: kilômét, dặm, mét, feet, hải lý
• Tính khoảng cách cung lớn chính xác
• Không cần gọi API

Ví dụ sử dụng: “Khoảng cách giữa San Francisco (37.7749°N, 122.4194°W) và New York (40.7128°N, 74.0060°W) là bao nhiêu?”

Công cụ xác định điểm nằm trong đa giác

Kiểm tra một hoặc nhiều điểm với một đa giác hoặc đa đa giác, chỉ trả về những điểm nằm bên trong. Hỗ trợ một điểm đơn lẻ hoặc một nhóm điểm trong một lần gọi.

Tính năng:

• Hoạt động với các đa giác phức tạp, bao gồm cả lỗ
• Hỗ trợ đa đa giác
• Kiểm tra hàng loạt số lượng điểm bất kỳ trong một lần gọi
• Hữu ích cho việc thiết lập hàng rào địa lý, xác thực vùng giao hàng và phân khúc khách hàng

Ví dụ sử dụng: "Trong số các địa chỉ giao hàng này, địa chỉ nào nằm trong khu vực phục vụ của chúng ta?"

Công cụ tính điểm đích

Tính điểm đích dựa trên điểm xuất phát, phương vị và khoảng cách bằng phép dịch chuyển trắc địa (đường tròn lớn).

Tính năng:

• Dịch chuyển theo đường thẳng, không phải tuyến đường đã định tuyến
• Hữu ích cho các yêu cầu như "tìm một điểm cách X 5km về phía bắc" hoặc tạo các điểm dịch chuyển để tìm kiếm
• Không cần gọi API

Ví dụ sử dụng: "Điểm nào cách Space Needle 10km về phía đông bắc?"

Công cụ tính phương vị

Tính hướng la bàn (phương vị) từ tọa độ này đến tọa độ khác.

Tính năng:

• Trả về phương vị theo độ (0-360°)
• Cung cấp hướng chính (N, NE, E, SE, S, SW, W, NW)
• Hữu ích cho việc điều hướng và các truy vấn về phương hướng

Ví dụ sử dụng: "Tôi nên đi theo hướng nào để đến sân bay từ đây?"

Công cụ tính trung điểm

Tìm trung điểm địa lý giữa hai tọa độ dọc theo đường tròn lớn.

Tính năng:

• Tính trung điểm thực sự trên bề mặt cong của Trái Đất
• Hữu ích để đề xuất địa điểm gặp mặt
• Xử lý chính xác các phép tính khoảng cách xa

Ví dụ sử dụng: "Điểm giữa San Francisco và New York là ở đâu?"

Công cụ tính trọng tâm

Tính tâm hình học (trọng tâm) của một đa giác hoặc đa đa giác.

Tính năng:

• Hoạt động với các hình dạng phức tạp
• Trả về trung bình cộng của tất cả các điểm
• Hữu ích để đặt nhãn hoặc điểm đánh dấu

Ví dụ sử dụng: "Tôi nên đặt điểm đánh dấu ở đâu cho ranh giới khu phố này?"

Công cụ tính diện tích

Tính diện tích của một đa giác.

Tính năng:

• Hỗ trợ nhiều đơn vị: mét vuông, kilômét vuông, mẫu Anh, hecta, dặm vuông, foot vuông
• Tính diện tích chính xác trên bề mặt Trái Đất
• Hoạt động với đa giác ở mọi kích thước

Ví dụ sử dụng: "Công viên này có diện tích bao nhiêu mẫu Anh?"

Công cụ tính hộp giới hạn

Tính hộp giới hạn tối thiểu (bbox) chứa một hình học.

Tính năng:

• Hoạt động với điểm, đường, đa giác và đa đa giác
• Trả về [minLongitude, minLatitude, maxLongitude, maxLatitude]
• Hữu ích cho việc tính toán khung nhìn và lập chỉ mục không gian

Ví dụ sử dụng: "Hộp giới hạn của tuyến đường này là gì?"

Công cụ tạo vùng đệm

Tạo vùng đệm (đa giác) xung quanh một điểm, đường hoặc đa giác.

Tính năng:

• Hỗ trợ nhiều đơn vị khoảng cách
• Tạo vùng đệm hình tròn quanh các điểm
• Hữu ích cho phân tích khoảng cách gần và tạo vùng ảnh hưởng

Ví dụ sử dụng: "Hiển thị vùng đệm 5km quanh vị trí này"

Công cụ đơn giản hóa

Giảm số lượng đỉnh trong một đường hoặc đa giác bằng thuật toán Douglas-Peucker.

Tính năng:

• Có thể cấu hình dung sai để điều chỉnh mức độ chi tiết
• Giữ nguyên hình dạng tổng thể trong khi giảm độ phức tạp
• Hữu ích để giảm kích thước tệp và cải thiện hiệu suất kết xuất
• Có tùy chọn duy trì cấu trúc liên kết (ngăn giao cắt với chính nó)

Ví dụ sử dụng: "Đơn giản hóa ranh giới phức tạp này để giảm số lượng điểm"

Công cụ tính độ dài

Đo tổng chiều dài của một đường được xác định bằng một chuỗi tọa độ.

Tính năng:

• Hỗ trợ kilômét, dặm, mét và foot
• Hữu ích để đo tuyến đường, lối đi hoặc ranh giới đã vẽ mà không cần gọi API định tuyến

Ví dụ sử dụng: "Đường mòn đi bộ đường dài này dài bao nhiêu?"

Công cụ tính bao lồi

Tính bao lồi của một tập hợp điểm — đa giác lồi nhỏ nhất chứa tất cả các điểm đó.

Tính năng:

• Hữu ích cho phân tích vùng bao hoặc ước tính phạm vi bao phủ
• Hoạt động ngoại tuyến mà không cần gọi API

Ví dụ sử dụng: "Đa giác nhỏ nhất chứa tất cả các vị trí cửa hàng này là gì?"

Công cụ tìm điểm gần nhất

Tìm điểm gần nhất trong một tập hợp so với một điểm đích cho trước.

Tính năng:

• Hiệu quả hơn so với việc gọi distance_tool cho từng ứng viên rồi sắp xếp
• Hữu ích để tìm cửa hàng, trạm dừng hoặc địa danh gần nhất với một vị trí

Ví dụ sử dụng: "Cửa hàng nào trong số này gần vị trí hiện tại của tôi nhất?"

Công cụ tìm điểm gần nhất trên đường

Chiếu một điểm lên vị trí gần nhất trên một đường hoặc tuyến đường, trả về điểm đó cùng khoảng cách đến nó.

Tính năng:

• Hữu ích cho các câu hỏi như "điểm nào trên tuyến đường này gần vị trí của tôi nhất?" hoặc khớp bản đồ mà không cần gọi API

Ví dụ sử dụng: "Hiện tại tôi đang ở gần vị trí nào nhất trên đường mòn đi bộ đường dài này?"

Công cụ hợp nhất, giao và hiệu

Kết hợp hoặc so sánh hai hay nhiều đa giác — union_tool hợp nhất chúng thành một hình học, intersect_tool tìm vùng giao nhau và difference_tool lấy một đa giác trừ đi đa giác còn lại.

Tính năng:

• Hữu ích để kết hợp các khu vực phục vụ, tìm vùng bao phủ chồng lấn hoặc tính vùng loại trừ (ví dụ: "vùng nào được khu vực A bao phủ nhưng không được khu vực B bao phủ?")
• Hoạt động hoàn toàn ngoại tuyến — không cần gọi API
• Mỗi công cụ trả về một tham chiếu render_map_tool để có thể trực quan hóa trực tiếp kết quả

Ví dụ sử dụng: "Kết hợp hai vùng giao hàng này thành một khu vực bao phủ" / "Hai vùng đẳng thời này chồng lấn ở đâu?" / "Phần nào của khu vực phục vụ này không nằm trong vùng đẳng thời 15 phút của chúng ta?"

Công cụ API Mapbox

Công cụ liệt kê danh mục (Không còn được khuyến nghị)

⚠️ Không còn được khuyến nghị: Thay vào đó, hãy dùng resource_reader_tool với URI mapbox://categories, hoặc truy cập trực tiếp tài nguyên mapbox://categories nếu ứng dụng khách của bạn hỗ trợ tài nguyên MCP.

Công cụ này được duy trì để tương thích ngược với các ứng dụng khách không hỗ trợ tài nguyên MCP hoặc resource_reader_tool.

Công cụ ma trận

Tính thời gian và khoảng cách di chuyển giữa nhiều điểm bằng Mapbox Matrix API. Các tính năng bao gồm:

• Tính toán định tuyến một-nhiều, nhiều-một hoặc nhiều-nhiều hiệu quả
• Hỗ trợ các hồ sơ di chuyển khác nhau (driving-traffic, driving, walking, cycling)
• Chỉ định thời gian khởi hành để tính toán có xét đến tình hình giao thông
• Tóm tắt tuyến đường với các chỉ số khoảng cách và thời lượng
• Kiểm soát hướng tiếp cận (lề đường/tự do) và phạm vi phương vị khởi hành được phép

Công cụ ảnh tĩnh

Tạo ảnh bản đồ tĩnh bằng Mapbox static image API. Các tính năng bao gồm:

• Kiểu bản đồ tùy chỉnh (đường phố, ngoài trời, vệ tinh, v.v.)
• Có thể điều chỉnh kích thước ảnh và mức thu phóng
• Hỗ trợ nhiều điểm đánh dấu với màu sắc và nhãn tùy chỉnh
• Các tùy chọn lớp phủ, bao gồm đường gấp khúc và đa giác
• Tự động căn khung theo tọa độ được chỉ định

Công cụ tìm kiếm danh mục

Thực hiện tìm kiếm danh mục bằng Mapbox Search Box category search API. Các tính năng bao gồm:

• Tìm kiếm địa điểm đáng chú ý theo danh mục (nhà hàng, khách sạn, trạm xăng, v.v.)
• Lọc theo khoảng cách địa lý
• Có thể tùy chỉnh giới hạn kết quả
• Siêu dữ liệu phong phú cho từng kết quả
• Hỗ trợ nhiều ngôn ngữ

Công cụ mã hóa địa lý ngược

Thực hiện mã hóa địa lý ngược bằng Mapbox geocoding V6 API. Các tính năng bao gồm:

• Chuyển tọa độ địa lý thành địa chỉ dễ đọc
• Có thể tùy chỉnh mức độ chi tiết (đường phố, khu phố, thành phố, v.v.)
• Lọc kết quả theo loại (địa chỉ, địa điểm đáng chú ý, khu phố, v.v.)
• Hỗ trợ nhiều ngôn ngữ
• Thông tin ngữ cảnh vị trí phong phú

Công cụ xác định địa điểm

Trả lời câu hỏi "có gì gần tọa độ này" chỉ trong một lần gọi — tên địa điểm, các địa điểm đáng chú ý lân cận và khả năng tiếp cận theo thời gian di chuyển — dựa trên dữ liệu Mapbox trực tiếp kèm trích dẫn. Hãy dùng công cụ này thay vì kết hợp reverse_geocode_tool với tìm kiếm trên web.

Tính năng:

• Phân loại truy vấn (định tuyến, ngữ cảnh khu vực lân cận, tìm kiếm địa điểm đáng chú ý hoặc khu vực/khả năng tiếp cận) và chỉ lấy dữ liệu liên quan
• Tìm kiếm địa điểm đáng chú ý lân cận theo danh mục khi được yêu cầu
• Tóm tắt khả năng tiếp cận theo thời gian di chuyển (dựa trên vùng đẳng thời)
• Trả về tham chiếu render_map_tool với vị trí đã xác thực và các địa điểm đáng chú ý lân cận được đánh dấu trên bản đồ

Ví dụ sử dụng: "Tọa độ này nằm trong khu phố nào, và gần đó có quán cà phê nào không?"

Công cụ chi tiết địa điểm

Truy xuất thông tin chi tiết về một địa điểm cụ thể bằng ID Mapbox của địa điểm đó — ảnh, giờ mở cửa, xếp hạng, số điện thoại và URL trang web. Dùng sau search_and_geocode_tool, category_search_tool hoặc reverse_geocode_tool để xem thêm chi tiết về một kết quả cụ thể.

Ví dụ sử dụng: "Cho tôi biết thêm về kết quả quán cà phê đầu tiên — giờ mở cửa, số điện thoại và trang web"

Công cụ chỉ đường

Lấy chỉ đường định tuyến bằng Mapbox Directions API. Các tính năng bao gồm:

• Hỗ trợ các hồ sơ định tuyến khác nhau: lái xe (với giao thông trực tiếp hoặc thông thường), đi bộ và đi xe đạp
• Định tuyến qua nhiều điểm trung gian (2-25 cặp tọa độ)
• Tùy chọn tuyến đường thay thế
• Chú giải tuyến đường (khoảng cách, thời lượng, tốc độ, tình trạng ùn tắc)
• Tùy chọn lập lịch:
  • Thời gian khởi hành trong tương lai (depart_at) cho các hồ sơ driving và driving-traffic
  • Thời gian đến mong muốn (arrive_by) chỉ dành cho hồ sơ driving
• Tối ưu hóa theo từng hồ sơ:
  • Lái xe: giới hạn kích thước phương tiện (chiều cao, chiều rộng, trọng lượng)
• Tùy chọn loại trừ khi định tuyến:
  • Các loại trừ phổ biến: tuyến phà, trạm thu phí chỉ nhận tiền mặt
  • Các loại trừ dành riêng cho lái xe: trạm thu phí, đường cao tốc, đường chưa trải nhựa, đường hầm, biên giới quốc gia, biên giới tiểu bang
  • Loại trừ các điểm tùy chỉnh (tối đa 50 điểm địa lý cần tránh)
• Định dạng đầu ra hình học GeoJSON

Công cụ vùng đẳng thời

Tính các khu vực có thể đến được từ một vị trí trong khoảng thời gian xác định bằng Mapbox Isochrone API. Các tính năng bao gồm:

• Hỗ trợ các hồ sơ di chuyển khác nhau (lái xe, đi bộ, đi xe đạp)
• Có thể tùy chỉnh thời gian hoặc khoảng cách di chuyển
• Tạo nhiều đường đồng mức (ví dụ: các khoảng 15, 30, 45 phút)
• Tùy chọn chỉ định thời gian khởi hành hoặc đến nơi
• Tùy chỉnh màu sắc để trực quan hóa

Công cụ tìm kiếm và mã hóa địa lý

Sử dụng điểm cuối Mapbox Search Box Text Search API để tìm kiếm và mã hóa địa lý các địa điểm đáng chú ý, địa chỉ, địa điểm và mọi loại khác được API đó hỗ trợ. Công cụ này hợp nhất chức năng trước đây do ForwardGeocodeTool và PoiSearchTool (trong các phiên bản trước của máy chủ MCP này) cung cấp thành một công cụ duy nhất.

Công cụ khớp bản đồ

Khớp các vệt GPS với mạng lưới đường bằng Mapbox Map Matching API. Các tính năng bao gồm:

• Chuyển các vệt GPS nhiễu thành tuyến đường rõ ràng trên mạng lưới đường
• Hỗ trợ các hồ sơ di chuyển khác nhau (driving, driving-traffic, walking, cycling)
• Xử lý tối đa 100 cặp tọa độ cho mỗi yêu cầu
• Tùy chọn dấu thời gian để cải thiện độ chính xác dựa trên tốc độ
• Có thể cấu hình bán kính khớp cho các mức chất lượng GPS khác nhau
• Chú giải tuyến đường (giới hạn tốc độ, khoảng cách, thời lượng, tình trạng ùn tắc)
• Nhiều định dạng đầu ra hình học (GeoJSON, polyline)

Ví dụ sử dụng: "Làm sạch vệt GPS này và khớp nó với các con đường: [tọa độ kèm dấu thời gian]"

Công cụ tối ưu hóa

Tìm tuyến đường tối ưu qua nhiều địa điểm bằng Mapbox Optimization API. Các tính năng bao gồm:

• Giải bài toán người bán hàng du lịch (TSP) cho 2-12 địa điểm
• Hỗ trợ các hồ sơ di chuyển khác nhau (driving, driving-traffic, walking, cycling)
• Cấu hình linh hoạt điểm bắt đầu và điểm kết thúc
• Tối ưu hóa chuyến đi khứ hồi hoặc một chiều
• Hướng dẫn điều hướng từng chặng (tùy chọn)
• Chú giải tuyến đường (khoảng cách, thời lượng, tốc độ)
• Nhiều định dạng đầu ra hình học (GeoJSON, polyline)

Ví dụ sử dụng: "Tìm tuyến đường tối ưu để ghé thăm 5 điểm dừng này: [danh sách địa chỉ hoặc tọa độ]"

Lưu ý: API V2 với các tính năng nâng cao (khung thời gian, giới hạn sức chứa, nhiều phương tiện) hiện có nhưng cần quyền truy cập beta. Phần triển khai V2 có trong mã nguồn nhưng không được đăng ký theo mặc định.

Công cụ phản hồi

Gửi phản hồi của người dùng về ứng dụng hoặc tác nhân đến nhà phát triển thông qua Mapbox Feedback API (Bản xem trước công khai). Phản hồi được ghi nhận trong tài khoản sở hữu access token, vì vậy khi bạn xây dựng ứng dụng hoặc tác nhân trên máy chủ này bằng token của riêng mình, phản hồi của người dùng sẽ xuất hiện trong cùng nguồn cấp dữ liệu với báo cáo của Feedback Agent từ các ứng dụng của bạn, và bạn có thể xem lại trong Feedback Explorer. Công cụ này không báo cáo sự cố cho Mapbox. Giống như Feedback Agent, công cụ này dành cho mọi phản hồi về sản phẩm giúp bạn hiểu nhu cầu của người dùng, chẳng hạn như:

• Một địa điểm đã đóng cửa, có thông tin sai hoặc được đánh dấu sai vị trí
• Một địa điểm hoặc địa chỉ không tìm thấy được
• Một con đường đã đóng, giới hạn tốc độ sai hoặc tình trạng giao thông hiển thị không chính xác
• Một tuyến đường có chỗ rẽ hoặc lối vào trái phép, hoặc không có tuyến đường nào
• Vấn đề về chính ứng dụng, chẳng hạn như lỗi hoặc đề xuất (application_issue)

Công cụ gửi nội dung phản hồi, danh mục và vị trí, rồi trả về mã định danh và trạng thái của mục đó. Vị trí là tùy chọn đối với phản hồi không liên quan đến địa điểm; API yêu cầu vị trí, nên hiện tại công cụ gửi 0, 0 theo khuyến nghị của nhóm Feedback API. Không có gì được gửi đi nếu chưa được người dùng đồng ý: các ứng dụng hỗ trợ elicitation sẽ hiển thị lời nhắc xác nhận trước, còn ở những nơi khác, phần mô tả công cụ yêu cầu mô hình xác nhận trong cuộc trò chuyện.

Feedback API miễn phí trong giai đoạn Public Preview. Khi đạt General Availability, Feedback Agent tính phí $0.02 cho mỗi mục phản hồi. Để tránh gửi cùng một vấn đề hai lần, trước khi gửi, công cụ kiểm tra các báo cáo của chính tài khoản trong 30 ngày gần nhất. Nếu có báo cáo cùng danh mục trong phạm vi 50 m vẫn đang chờ xem xét (không kiểm tra phản hồi không có vị trí), công cụ trả về báo cáo đó thay vì gửi báo cáo mới. Feedback API chỉ liệt kê báo cáo của chính tài khoản, nên không thể phát hiện báo cáo từ các tài khoản khác. send_anyway: true bỏ qua bước kiểm tra nếu người dùng cho biết vấn đề của họ khác với vấn đề đã báo cáo.

Yêu cầu: mã thông báo truy cập cần có phạm vi user-feedback:write để gửi phản hồi và user-feedback:read để kiểm tra trùng lặp. Nếu không có phạm vi ghi, công cụ trả về lỗi cho biết điều đó. Nếu không có phạm vi đọc, công cụ sẽ gửi mà không kiểm tra và nêu rõ điều này trong kết quả. Để không đưa công cụ vào, hãy khởi động máy chủ với --disable-tools feedback_tool.

Ví dụ sử dụng: "Blue Bottle trên Mint St đã đóng cửa từ năm ngoái, bạn có thể gửi phản hồi đó không?"

Công cụ Report

Gửi phản hồi về chính máy chủ Mapbox MCP đến nhóm Mapbox phát triển máy chủ này: lỗi, kết quả sai hoặc khó hiểu do một công cụ trả về, tính năng còn thiếu hoặc đề xuất. Phản hồi được gửi bằng tài khoản riêng của Mapbox, không phải tài khoản của bạn, nên không cần phạm vi mã thông báo bổ sung; sau đó bạn cũng không thể xem lại hoặc rút lại phản hồi. Công cụ này không dùng để báo cáo dữ liệu bản đồ, địa điểm hoặc định tuyến sai.

Máy chủ thêm phiên bản của máy chủ, tên và phiên bản của ứng dụng khách, cùng tên công cụ liên quan đến phản hồi vào cuối nội dung. Không có gì được gửi đi nếu chưa được người dùng đồng ý: các ứng dụng hỗ trợ elicitation sẽ hiển thị lời nhắc xác nhận trước, còn ở những nơi khác, phần mô tả công cụ yêu cầu mô hình xác nhận trong cuộc trò chuyện.

Công cụ sử dụng endpoint mà nhóm Feedback API đã thêm cho lệnh mapbox report của Mapbox CLI. Để không đưa công cụ vào, hãy khởi động máy chủ với --disable-tools report_tool.

Ví dụ sử dụng: "Bản đồ không vẽ bất kỳ isochrone nào của tôi. Bạn có thể báo cho nhóm Mapbox MCP biết không?"

Công cụ List public tokens

Liệt kê các mã thông báo truy cập công khai (pk.) của tài khoản, dành cho tác nhân đang xây dựng trang web hoặc ứng dụng bên ngoài cuộc trò chuyện, có tải Mapbox GL JS hoặc gọi Mapbox APIs từ trình duyệt. Trong cuộc trò chuyện, render_map_tool không cần mã thông báo. Mỗi mã thông báo đi kèm tên, thông tin cho biết đó có phải là mã mặc định hay không, các giới hạn URL và phạm vi của mã.

Truyền site_url (nơi trang sẽ chạy), công cụ sẽ đề xuất mã thông báo được giới hạn cho URL đó nếu tài khoản có mã phù hợp. Nếu không, công cụ đề xuất mã thông báo công khai mặc định và cho biết trang đã xuất bản nên dùng mã thông báo bị giới hạn theo URL, kèm liên kết để tạo mã. Bất kỳ ai sao chép mã thông báo công khai không bị giới hạn đều có thể sử dụng mã đó, và chi phí sử dụng sẽ tính vào tài khoản.

Công cụ không bao giờ trả về mã thông báo bí mật hoặc tạm thời, và không thể tạo mã thông báo (việc đó cần tokens:write; create_token_tool của máy chủ DevKit thực hiện).

Yêu cầu: để liệt kê, cần có phạm vi tokens:read, cũng là phạm vi mà bản đồ trong cuộc trò chuyện hiện dùng để tìm mã thông báo công khai mặc định. Với mã thông báo truy cập pk., hoặc khi việc liệt kê thất bại trên MAPBOX_ACCESS_TOKEN của chính máy chủ và MAPBOX_PUBLIC_TOKEN được đặt, công cụ sẽ trả về mã thông báo đó. Người gọi có mã bearer riêng (máy chủ được lưu trữ) sẽ không bao giờ nhận được MAPBOX_PUBLIC_TOKEN, và mã thông báo bị giới hạn cho các URL khác sẽ không bao giờ được đề xuất. Để không đưa công cụ vào, hãy khởi động máy chủ với --disable-tools list_public_tokens_tool.

Ví dụ sử dụng: "Hãy tạo cho tôi một trang web một trang hiển thị ba địa điểm cửa hàng của chúng tôi trên bản đồ Mapbox."

Phát triển

Kiểm tra máy chủ

Dùng Node.js

# Run the built image
npm run inspect:build

Dùng 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

Tạo công cụ mới

npx plop create-tool
# provide tool name without suffix (e.g. Search)

Phát hành phiên bản mới

# 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

Quan trọng: Quy trình publisher xác thực rằng các phiên bản package.json và server.json khớp với phiên bản phát hành. Bỏ qua việc tăng phiên bản hoặc đồng bộ manifest sẽ khiến quá trình xuất bản thất bại.

Theo dõi OpenTelemetry

Máy chủ MCP này tích hợp khả năng theo dõi OpenTelemetry toàn diện để giám sát trong môi trường production:

Bản demo nhanh

# 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

Lưu ý: Máy chủ tự động tải cấu hình từ tệp .env khi khởi động. Tệp .env.example có các ví dụ cấu hình cho nhiều nền tảng giám sát.

Các nền tảng giám sát được hỗ trợ

Các ví dụ cấu hình có trong .env.example dành cho:

Nhà cung cấp dịch vụ đám mây:

• ☁️ AWS X-Ray
• ☁️ Azure Monitor (Application Insights)
• ☁️ Google Cloud Trace

Nền tảng SaaS:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Mọi backend tương thích với OTLP

Cấu hình production

Xem docs/tracing.md để biết hướng dẫn thiết lập đầy đủ, bao gồm:

• 🔧 Hướng dẫn cấu hình theo từng nền tảng
• 📊 Thiết lập xác thực và endpoint
• 🎯 Thuộc tính trace và ngữ cảnh tùy chỉnh
• 🚀 Tối ưu hóa hiệu năng (mức hao tốn tối thiểu)
• 🔍 Khắc phục sự cố và gỡ lỗi

Tính năng theo dõi:

• ✅ Theo dõi quá trình tải cấu hình (tải tệp .env)
• ✅ Tự động theo dõi quá trình thực thi công cụ
• ✅ Gắn kết đo lường cho yêu cầu HTTP với mã tương quan CloudFront
• ✅ Exporter có thể cấu hình (console, OTLP)
• ✅ Chú trọng bảo mật (bảo vệ dữ liệu, xác thực JWT)
• ✅ Sẵn sàng cho production (mức hao tốn CPU <1%)

Đóng góp

Chúng tôi hoan nghênh các đóng góp cho Mapbox MCP Server! Vui lòng đọc CONTRIBUTING.md trước khi gửi pull request.

Các tiêu chuẩn và hướng dẫn đầy đủ:

• CONTRIBUTING.md - Bắt đầu, quy trình PR, tài liệu tham khảo nhanh
• Engineering Standards (docs/engineering_standards.md) - Tiêu chuẩn đầy đủ về chất lượng mã, kiểm thử, tài liệu và cộng tác
• Claude Code Guide (CLAUDE.md) - Tiêu chuẩn và mẫu dành cho người đóng góp sử dụng Claude Code
• AI Agent Instructions (AGENTS.md) - Hướng dẫn dành cho các trợ lý lập trình AI khác (Cursor, Continue, Aider, v.v.)
• GitHub Copilot Guidelines - Các phương pháp tốt nhất để sử dụng GitHub Copilot một cách có trách nhiệm

Bắt đầu nhanh cho người đóng góp

1. Fork kho lưu trữ và clone fork của bạn
2. Cài đặt các phần phụ thuộc: npm install
3. Thực hiện thay đổi theo tiêu chuẩn lập trình của chúng tôi
4. Chạy kiểm thử và lint: npm test && npm run lint
5. Thêm kiểm thử cho mọi chức năng mới
6. Gửi pull request kèm mô tả rõ ràng

Mọi đóng góp đều phải vượt qua các bước kiểm tra CI và quy trình đánh giá mã của chúng tôi. Xem docs/engineering_standards.md để biết các yêu cầu chi tiết.

Sử dụng dữ liệu và quyền riêng tư

Dữ liệu nào được gửi đến Mapbox APIs

Khi bạn sử dụng các công cụ của máy chủ MCP, dữ liệu sau được gửi trực tiếp từ môi trường của bạn đến Mapbox APIs:

• Công cụ geocoding: Văn bản địa chỉ/vị trí, tọa độ, bộ lọc quốc gia/khu vực
• Công cụ tìm kiếm: Truy vấn tìm kiếm, tọa độ vị trí để tính độ gần, bộ lọc danh mục
• Công cụ chỉ đường: Tọa độ điểm đầu/cuối, điểm dừng, tùy chọn định tuyến, giới hạn phương tiện
• Công cụ ma trận: Nhiều cặp tọa độ, hồ sơ di chuyển, thời gian khởi hành
• Công cụ bản đồ tĩnh: Tọa độ, mức thu phóng, tùy chọn kiểu hiển thị, thông tin điểm đánh dấu
• Công cụ isochrone: Tọa độ điểm xuất phát, tham số thời gian/khoảng cách, hồ sơ di chuyển

Quyền riêng tư của bạn

• Thực thi cục bộ: Mọi lệnh gọi API đều được thực hiện trực tiếp từ môi trường của bạn đến Mapbox APIs
• Bảo mật mã thông báo: Mã thông báo API Mapbox của bạn vẫn nằm trên máy cục bộ và không bao giờ được máy chủ MCP này truyền đi hoặc lưu trữ
• Không lưu trữ dữ liệu: Máy chủ MCP này không lưu trữ, ghi nhật ký hoặc thu thập bất kỳ dữ liệu hay yêu cầu API nào của bạn
• Giao tiếp trực tiếp: Không có máy chủ trung gian giữa bạn và Mapbox APIs

Việc sử dụng dữ liệu của bên thứ ba

• Chính sách quyền riêng tư của Mapbox điều chỉnh dữ liệu được gửi đến các API của họ: https://www.mapbox.com/legal/privacy/
• Việc sử dụng API: Các điều khoản API tiêu chuẩn của Mapbox áp dụng cho mọi yêu cầu được thực hiện qua những công cụ này
• Lưu giữ dữ liệu: Tham khảo tài liệu của Mapbox để biết chính sách lưu giữ dữ liệu của họ

Hỗ trợ và liên hệ

Vấn đề về MCP Server

• Email: mcp-feedback@mapbox.com
• GitHub Issues: Báo lỗi và yêu cầu tính năng

Câu hỏi về Mapbox API

• Hỗ trợ Mapbox: https://support.mapbox.com/
• Tài liệu: https://docs.mapbox.com/
• Trạng thái API: https://status.mapbox.com/

Cam kết bảo trì

Máy chủ MCP này được Mapbox, Inc. chính thức bảo trì. Chúng tôi cung cấp:

• Cập nhật thường xuyên cho các tính năng Mapbox API mới
• Sửa lỗi và cập nhật bảo mật
• Khả năng tương thích với các phiên bản MCP protocol mới nhất
• Hỗ trợ cộng đồng qua GitHub issues

---

Giấy phép MIT