Mapbox

Máy chủ MCP Mapbox

Máy chủ Node.js triển khai Giao thức Mô hình Ngữ cảnh (MCP) cho các API Mapbox.

Khai phá Trí tuệ Không gian Địa lý cho Ứng dụng AI của Bạn

Máy chủ MCP Mapbox biến bất kỳ tác nhân AI hoặc ứng dụng nào 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 thông tin 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ề địa điểm, điều hướng thế giới vật lý, 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 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ự tham quan tối ưu cho nhiều điểm dừng (bài toán người bán hàng)
• Khớp bản đồ để gắn dấu vết GPS vào mạng lưới đường bộ nhằm hiển thị tuyến đường rõ ràng
• Tạo đẳng thời để trực quan hóa các khu vực có thể đến được trong các ràng buộc thời gian hoặc khoảng cách cụ thể
• Hiển thị bản đồ tương tác trực tiếp (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 trong cuộc trò chuyện
• Hình ảnh bản đồ tĩnh để tạo biểu diễn trực quan về vị trí, tuyến đường và dữ liệu địa lý
• Tính toán không gian địa lý ngoại tuyến cho 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, bộ tối ưu hóa hậu cần, hệ thống gợi ý dựa trên vị trí, hay bất kỳ ứng dụng nào cần hiểu "ở đâu", máy chủ MCP Mapbox cung cấp trí tuệ không gian để biến điều đó thành hiện thực. Bạn cũng có thể kích hoạt nó 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ã truy cập Mapbox để sử dụng máy chủ MCP này.

Điểm cuối MCP được lưu trữ

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

Điểm cuối: https://mcp.mapbox.com/mcp

Để biết 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, xem Hướng dẫn Máy chủ MCP được lưu trữ.

Để lấy mã truy cập Mapbox:

1. Đăng ký tài khoản Mapbox miễn phí tại mapbox.com/signup
2. Điều hướng đến Trang Tài khoản của bạn
3. Tạo mã mới hoặc sử dụng mã công khai mặc định

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

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

Để biết hướng dẫn thiết lập chi tiết cho các tích hợp khác nhau, 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 máy chủ MCP 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ụ cho thấy 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ô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 máy chủ MCP
• Hướng dẫn render_map_tool - Nguyên thủy trực quan hóa bản đồ: lược đồ tải trọng đầy đủ và cách hiển thị dữ liệu của riêng bạn một cách độc lập, không cần bất kỳ công cụ Mapbox nào khác
• Elicitations - Cách search_and_geocode_tool và directions_tool yêu cầu người dùng làm rõ kết quả hoặc chọn tuyến đường, và cách chúng dự phòng một cách linh hoạt khi ứng dụng khách không hỗ trợ

Ví dụ về Lời nhắc

Hãy thử các lời nhắc này với Claude Desktop hoặc các ứng dụng khách MCP khác sau khi thiết lập:

Định vị Vị trí

Đối với các truy vấn ưu tiên tọa độ — "cái gì ở gần tôi", "khu phố này là gì", "cái gì đến được trong N phút" — sử dụng ground_location_tool. Nó kết hợp mã hóa địa lý ngược, tìm kiếm danh mục và đẳng thời trong một lần gọi, chọn chiến lược phù hợp một cách thích ứng dựa trên truy vấn, và trả về các bản ghi có kiểu (tên, địa chỉ, tọa độ, khoảng cách, đa giác khả năng tiếp cận) kèm trích dẫn.

Mỗi lời nhắc trong bốn lời nhắc dưới đây sử dụng một chiến lược khác nhau trong một lần gọi công cụ:

• Khu phố — "Khu phố nào là 47.6097, -122.3408, và xung quanh tôi có gì?"
• POI — "Quán cà phê trong phạm vi đi bộ 10 phút từ 40.7580, -73.9855"
• Khu vực — "Tôi có thể đến đâu trong 15 phút đi bộ từ 37.7749, -122.4194?"
• Định tuyến — "Điểm có thể điều hướng gần nhất để thả ai đó tại 34.0522, -118.2437"

Khám phá Vị trí

• "Tìm quán cà phê trong khoảng cách đi bộ từ Tòa nhà Empire State"
• "Tôi muốn đi từ Seattle đến Portland, có Starbucks nào trên đường không?"
• "Cho tôi xem các trạm xăng dọc theo tuyến đường từ Boston đến New York"
• "Nhà hàng nào gần Quảng trường Thời Đại?"

Điều hướng & Du lịch

• "Chỉ đường lái xe từ LAX đến Hollywood với giao thông hiện tại"
• "Mất bao lâu để đi bộ từ Công viên Trung tâm đến Quảng trường Thời Đại?"
• "Tính thời gian di chuyển từ khách sạn của tôi (Four Seasons) đến Sân bay JFK bằng taxi vào giờ cao điểm"

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

• "Sử dụng công cụ hiển thị bản đồ Mapbox, cho tôi xem chỉ đường từ Cầu Cổng Vàng đến Quảng trường Union ở San Francisco" — hiển thị tuyến đường tương tác trực tiếp trên bản đồ Mapbox thực
• "Tạo hình ảnh bản đồ hiển thị tuyến đường từ Cầu Cổng Vàng đến Bến Cá Fisherman's Wharf với điểm đánh dấu tại cả hai vị trí"
• "Cho tôi xem chế độ xem 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ả các địa điểm Starbucks trong phạm vi một dặm quanh trung tâm Seattle"
• "Hiển thị đa giác tô màu trên các tọa độ này: [...], với điểm đánh dấu có nhãn 'Kho hàng' tại [...]" — hiển thị GeoJSON của riêng bạn trực tiếp 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 đến được trong 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 vị trí 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 tham quan 3 điểm du lịch này (Cổng Vàng, Cầu thang Âm nhạc và Bến Cá Fisherman's Wharf) ở San Francisco"
• "Tối ưu hóa tuyến đường giao hàng cho 8 địa chỉ này: [danh sách địa chỉ]"

Khớp GPS & Tuyến đường

• "Làm sạch dấu vết GPS này và hiển thị tuyến đường thực tế trên đường: [danh sách tọa độ với dấu thời gian]"
• "Gắn chuyến đi xe đạp đã ghi lại này vào mạng lưới xe đạp: [tọa độ GPS]"
• "Khớp tuyến đường lái xe này vào mạng lưới đường bộ và hiển thị mức độ tắc nghẽn giao thông"

Tính toán Không gian Địa lý Ngoại tuyến

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

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

• Cụ thể về vị trí (sử dụng địa chỉ đầy đủ hoặc tên địa danh)
• Chỉ định phương thức di chuyển ưa thích của bạn (lái xe, đi bộ, đi xe đạp)
• Bao gồm các ràng buộc thời gian khi phù hợp ("trong giờ cao điểm", "lúc 3 giờ chiều")
• Yêu cầu định dạng đầu ra cụ thể khi cần ("dưới dạng hình ả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ề lời nhắc tìm kiếm dọc theo tuyến đường với các trường hợp sử dụng khác nhau và hướng dẫn kiểm tra MCP Inspector.

Tài nguyên

Máy chủ MCP hiển thị dữ liệu tham chiếu tĩnh dưới dạng tài nguyên MCP. Tài nguyên cung cấp quyền 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 thực hiện lệnh gọi công cụ.

Tài nguyên Có sẵn

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 có sẵn để sử dụng với công cụ tìm kiếm danh mục. Danh mục có thể được dùng để 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 tiếng Nhật
• mapbox://categories/es - Tên danh mục tiếng Tây Ban Nha

Truy cập Tài nguyên:

• Ứng dụng khách có hỗ trợ tài nguyên MCP gốc: Sử 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: Sử dụng resource_reader_tool với URI tài nguyê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, đẳng thời, tìm kiếm, v.v.) đều có thể hiển thị kết quả của mình dưới dạng bản đồ Mapbox GL JS tương tác trực tiếp thông qua render_map_tool — nguyên thủy trực quan hóa duy nhất của máy chủ. Nó hiển thị qua giao thức MCP Apps (@modelcontextprotocol/ext-apps) dưới dạng bảng HTML độc lập ngay trong cuộc trò chuyện, với nút chuyển Toàn màn hình, trong 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 nó. render_map_tool cũng chấp nhận GeoJSON được soạn thủ công trực tiếp — đ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 hoặc 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 đồ tải trọng và ví dụ độc lập hoàn chỉnh.

Nếu bạn cần hình ảnh tĩnh đảm bảo trong các ứng dụng khách không hỗ trợ MCP Apps, hãy sử dụng static_map_image_tool để thay thế — nó 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 Tài nguyên (Tham gia Tùy chọn cho Ứng dụng khách Không tuân thủ)

Tài nguyên là một tính năng MCP cốt lõi được hỗ trợ bởi hầu hết các ứng dụng khách (Claude Desktop, VS Code, MCP Inspector, v.v.). Tuy nhiên, một số ứng dụng khách (như smolagents) không hỗ trợ tài nguyên nào cả. Đối 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 tài nguyên" cung cấp cùng nội dung như tài nguyên nhưng qua các lệnh gọi công cụ.

Công cụ Dự phòng:

• resource_reader_tool - Dự phòng chung để đọc bất kỳ tài nguyên nào 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 bao gồm (giả định ứng dụng khách của bạn hỗ trợ tài nguyên). Nếu ứng dụng khách của bạn không hỗ trợ tài nguyên, hãy kích hoạt các công cụ dự phòng:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Khi nào nên đặt:

• ✅ Đặt thành true nếu bạn sử dụng smolagents hoặc các ứng dụng khách khác không hỗ trợ tài nguyên
• ❌ Để trống (mặc định) nếu bạn sử dụng Claude Desktop, VS Code, MCP Inspector hoặc bất kỳ ứng dụng khách nào có khả năng 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 các 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. Sử dụng công cụ này để đọc cá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 sử dụng API tài nguyên trực tiếp để 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, ngay cả khi không có kết nối internet.

Công cụ 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 toán khoảng cách vòng tròn 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ụ Điểm Trong Đa giác

Kiểm tra một hoặc nhiều điểm so 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. Xử lý một điểm đơn lẻ hoặc một lô 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ả đa giác có lỗ hổng
• Hỗ trợ đa đa giác (multipolygon)
• 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 geofencing, xác thực vùng giao hàng và phân khúc khách hàng

Ví dụ sử dụng: "Địa chỉ giao hàng nào trong số này nằm trong khu vực phục vụ của chúng tôi?"

Công cụ Điểm Đích

Tính điểm đích khi có điểm bắt đầu, hướng (bearing) và khoảng cách bằng cách sử dụng độ lệch trắc địa (great-circle offset).

Tính năng:

• Độ lệch đường thẳng, không phải tuyến đường có lộ trình
• Hữu ích cho việc "tìm điểm cách X 5km về phía bắc" hoặc xây dựng các độ lệch tìm kiếm
• Không yêu cầu gọi API

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

Công cụ Hướng (Bearing)

Tính hướng la bàn (bearing) từ một tọa độ đến một tọa độ khác.

Tính năng:

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

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

Công cụ Điểm Giữa

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

Tính năng:

• Tính toán điểm giữa thực sự trên bề mặt cong của Trái Đất
• Hữu ích cho việc gợi ý đ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ụ Trọng tâm (Centroid)

Tính trọng tâm hình học (centroid) 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 cho việc đặ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ụ 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 (acres), héc-ta, dặm vuông, feet 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: "Diện tích của công viên này là bao nhiêu mẫu Anh?"

Công cụ Hộp Giới hạn (Bounding Box)

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 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 cho tuyến đường này là gì?"

Công cụ Vùng đệm (Buffer)

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 xung 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ị cho tôi vùng đệm 5km xung quanh vị trí này"

Công cụ Đơn giản hóa (Simplify)

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 cho 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 cho việc giảm kích thước tệp và cải thiện hiệu suất kết xuất
• Tùy chọn duy trì cấu trúc liên kết (ngăn chặn tự giao cắt)

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ụ Chiều dài (Length)

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

Tính năng:

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

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

Công cụ Lồi (Convex)

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

Tính năng:

• Hữu ích cho phân tích diện tích bao phủ hoặc ước tính vùng phủ sóng
• 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ụ Điểm Gần nhất

Tìm điểm gần nhất trong một tập hợp với một điểm mục tiêu nhất định.

Tính năng:

• Hiệu quả hơn so với việc gọi distance_tool cho từng ứng viên và sắp xếp
• Hữu ích cho việc tìm cửa hàng, điể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ụ Điểm Gần nhất trên Đường

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

Tính năng:

• Hữu ích cho câu hỏi "đ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 đồ (map-matching) mà không cần gọi API

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

Công cụ Hợp nhất, Giao nhau và Hiệu (Union, Intersect, Difference)

Kết hợp hoặc so sánh hai hoặc 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 khu vực chúng chia sẻ, và difference_tool trừ một đa giác khỏi đa giác khác.

Tính năng:

• Hữu ích cho việc kết hợp các khu vực dịch vụ, tìm vùng phủ chồng lấn hoặc tính toán vùng loại trừ (ví dụ: "khu vực nào được phủ bởi vùng A nhưng không phải vùng B?")
• 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 để kết quả có thể được hiển thị trực tiếp

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

Công cụ API Mapbox

Công cụ Danh mục Danh sách (Không được dùng nữa)

⚠️ Không được dùng nữa: Sử dụng resource_reader_tool với URI mapbox://categories để thay thế, hoặc truy cập trực tiếp vào tài nguyên mapbox://categories nếu máy 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 máy khách không hỗ trợ tài nguyên MCP hoặc resource_reader_tool.

Công cụ Ma trận (Matrix)

Tính toán thời gian di chuyển và khoảng cách 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 điểm khởi hành cho các phép tính có nhận biết 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 cách tiếp cận (curb/unrestricted) và phạm vi hướng khởi hành được phép

Công cụ Hình ảnh tĩnh

Tạo hình ả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 (streets, outdoors, satellite, v.v.)
• Kích thước hình ảnh và mức thu phóng có thể điều chỉnh
• 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 đa giác (polyline) và đa giác (polygon)
• Tự động khớp với các tọa độ được chỉ định

Công cụ Tìm kiếm theo danh mục

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

• Tìm kiếm các điểm quan tâm (POI) 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ý
• Giới hạn kết quả có thể tùy chỉnh
• Siêu dữ liệu phong phú cho mỗi kết quả
• Hỗ trợ nhiều ngôn ngữ

Công cụ Mã hóa địa lý ngược (Reverse geocoding)

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

Công cụ Vị trí mặt đất

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

Tính năng:

• Phân loại truy vấn (định tuyến, ngữ cảnh khu phố, tìm kiếm POI hoặc vùng/khả năng tiếp cận) và chỉ tìm nạp dữ liệu liên quan
• Tìm kiếm POI gầ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 isochrone)
• Trả về tham chiếu render_map_tool với vị trí được xác định và các POI gần đó được vẽ trên bản đồ

Ví dụ sử dụng: "Tọa độ này thuộc khu phố nào và có quán cà phê nào gần đó 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 nó — ảnh, giờ mở cửa, xếp hạng, số điện thoại và URL trang web. Sử dụng sau search_and_geocode_tool, category_search_tool hoặc reverse_geocode_tool để biết 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 (Directions)

Tìm nạp hướng dẫn đị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 (có giao thông trực tiếp hoặc thông thường), đi bộ và đi xe đạp
• Tuyến đường từ nhiều điểm dừng (2-25 cặp tọa độ)
• Tùy chọn tuyến đường thay thế
• Chú thích tuyến đường (khoảng cách, thời lượng, tốc độ, tắc nghẽn)
• Các tùy chọn lên lịch:
  • Thời điểm khởi hành trong tương lai (depart_at) cho hồ sơ driving và driving-traffic
  • Thời điểm đến mong muốn (arrive_by) chỉ cho hồ sơ driving
• Tối ưu hóa theo hồ sơ cụ thể:
  • Lái xe: các ràng buộc về kích thước xe (chiều cao, chiều rộng, trọng lượng)
• Các tùy chọn loại trừ cho định tuyến:
  • Loại trừ phổ biến: tuyến phà, trạm thu phí chỉ thanh toán bằng tiền mặt
  • Loại trừ riêng cho lái xe: trạm thu phí, đường cao tốc, đường không trải nhựa, đường hầm, biên giới quốc gia, biên giới tiểu bang
  • Loại trừ đ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ụ Isochrone

Tính toán các khu vực có thể đến được trong một khoảng thời gian nhất định từ một vị trí 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 (driving, walking, cycling)
• Thời gian hoặc khoảng cách di chuyển có thể tùy chỉnh
• Tạo nhiều đường đồng mức (ví dụ: phạm vi 15, 30, 45 phút)
• Tùy chọn chỉ định thời điểm khởi hành hoặc đến
• Tùy chỉnh màu sắc cho việ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 để hỗ trợ tìm kiếm và mã hóa địa lý POI, đị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 được cung cấp bởi ForwardGeocodeTool và PoiSearchTool (từ các phiên bản trước của máy chủ MCP này) thành một công cụ duy nhất.

Công cụ Khớp bản đồ (Map matching)

Gắn các vết GPS vào mạng lưới đường bộ bằng Mapbox Map Matching API. Các tính năng bao gồm:

• Chuyển đổi các vết GPS nhiễu thành các tuyến đường sạch trên mạng lưới đường bộ
• 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 độ mỗi yêu cầu
• Dấu thời gian tùy chọn để cải thiện độ chính xác dựa trên tốc độ
• Bán kính gắn (snap radius) có thể cấu hình cho các mức chất lượng GPS khác nhau
• Chú thích tuyến đường (giới hạn tốc độ, khoảng cách, thời lượng, tắc nghẽn giao thông)
• 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à gắn nó vào đườ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 vị trí 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 (TSP) cho 2-12 vị trí
• 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 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ú thích 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 (cửa sổ thời gian, ràng buộc công suất, nhiều phương tiện) có sẵn nhưng yêu cầu quyền truy cập beta. Việc triển khai V2 được bao gồm trong mã nguồn nhưng không được đăng ký theo mặc định.

Phát triển

Kiểm tra máy chủ

Sử dụng Node.js

# Run the built image
npm run inspect:build

Sử 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 xuất bản 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ẽ gây ra lỗi xuất bản.

Truy vết OpenTelemetry

Máy chủ MCP này bao gồm truy vết OpenTelemetry toàn diện cho khả năng quan sát sản xuất:

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 của bạn khi khởi động. Tệp .env.example bao gồm các ví dụ cấu hình cho nhiều nền tảng quan sát (observability).

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

Các ví dụ cấu hình được bao gồm trong .env.example cho:

Nhà cung cấp đám mây:

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

Nền tảng SaaS:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Bất kỳ backend tương thích OTLP nào

Cấu hình sản xuất

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 và ngữ cảnh trace tùy chỉnh
• 🚀 Tối ưu hiệu suất (chi phí tối thiểu)
• 🔍 Xử lý sự cố và gỡ lỗi

Các tính năng Tracing:

• ✅ Theo dõi quá trình tải cấu hình (tải tệp .env)
• ✅ Tự động theo dõi thực thi công cụ
• ✅ Công cụ đo lường yêu cầu HTTP với ID tương quan CloudFront
• ✅ Bộ xuất dữ liệu 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 sản xuất (chi phí CPU dưới 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à nguyên tắc đầy đủ:

• CONTRIBUTING.md - Bắt đầu, quy trình PR, tham khảo nhanh
• Engineering Standards (docs/engineering_standards.md) - Các tiêu chuẩn hoàn chỉnh về chất lượng mã, kiểm thử, tài liệu và cộng tác
• Claude Code Guide (CLAUDE.md) - Các tiêu chuẩn và mẫu cho người đóng góp sử dụng Claude Code
• AI Agent Instructions (AGENTS.md) - Hướng dẫn cho các trợ lý mã hóa 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 bản fork của bạn
2. Cài đặt các phụ thuộc: npm install
3. Thực hiện các thay đổi theo tiêu chuẩn mã hóa của chúng tôi
4. Chạy kiểm thử và linting: 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 với mô tả rõ ràng

Tất cả các đóng góp phải vượt qua quy trình kiểm tra CI và đá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 & 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 đây được gửi trực tiếp từ môi trường của bạn đến Mapbox APIs:

• Công cụ mã hóa địa lý (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í cho tìm kiếm lân cận, bộ lọc danh mục
• Công cụ chỉ đường: Tọa độ điểm đầu/điểm cuối, điểm dừng, tùy chọn định tuyến, ràng buộc 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 dáng, 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ộ: Tất cả các lệnh gọi API đượ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 token: Token API Mapbox của bạn vẫn nằm trên máy cục bộ và không bao giờ được truyền đến hoặc lưu trữ bởi máy chủ MCP này
• 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 hoặc 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 nào giữa bạn và Mapbox APIs

Sử dụng dữ liệu 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 API của họ: https://www.mapbox.com/legal/privacy/
• Sử dụng API: Các điều khoản chuẩn của Mapbox API áp dụng cho mọi yêu cầu được thực hiện qua các 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ợ & Liên hệ

Về các vấn đề của MCP Server

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

Về các 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 duy trì chính thức bởi Mapbox, Inc. Chúng tôi cung cấp:

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

---

MIT License