Mapbox

Server MCP Mapbox

Server Node.js yang mengimplementasikan Model Context Protocol (MCP) untuk API Mapbox.

Buka Kecerdasan Geospasial untuk Aplikasi AI Anda

Server MCP Mapbox mengubah agen atau aplikasi AI apa pun menjadi sistem yang sadar geospasial dengan menyediakan akses tanpa hambatan ke platform intelijen lokasi komprehensif Mapbox. Dengan server ini, AI Anda dapat memahami dan bernalar tentang tempat, menavigasi dunia fisik, dan mengakses data geospasial yang kaya termasuk:

• Geocoding global untuk mengonversi alamat dan nama tempat menjadi koordinat dan sebaliknya
• Pencarian titik menarik (POI) di jutaan bisnis, landmark, dan tempat di seluruh dunia
• Penentuan rute multi-modal untuk berkendara, berjalan kaki, dan bersepeda dengan lalu lintas waktu nyata
• Matriks waktu perjalanan untuk menganalisis aksesibilitas dan mengoptimalkan logistik
• Optimasi rute untuk menemukan urutan kunjungan optimal untuk beberapa pemberhentian (masalah traveling salesman)
• Pencocokan peta untuk menempelkan jejak GPS ke jaringan jalan demi visualisasi rute yang bersih
• Generasi isokron untuk memvisualisasikan area yang dapat dijangkau dalam batasan waktu atau jarak tertentu
• Rendering peta interaktif langsung (render_map_tool) untuk menampilkan rute, hasil pencarian, dan GeoJSON kustom Anda sendiri di peta Mapbox GL JS sungguhan langsung di dalam obrolan
• Gambar peta statis untuk membuat representasi visual lokasi, rute, dan data geografis
• Perhitungan geospasial offline untuk jarak, luas, azimuth, buffer, dan analisis spasial tanpa memerlukan panggilan API

Baik Anda membangun asisten perjalanan AI, pengoptimal logistik, pemberi rekomendasi berbasis lokasi, atau aplikasi apa pun yang perlu memahami "di mana", Server MCP Mapbox menyediakan kecerdasan spasial untuk mewujudkannya. Anda juga dapat mengaktifkannya di klien populer seperti Claude Desktop dan VS Code. Lihat detail di bawah

Penggunaan

Token akses Mapbox diperlukan untuk menggunakan server MCP ini.

Endpoint MCP yang Dihosting

Untuk akses cepat, Anda dapat menggunakan endpoint MCP yang kami hosting:

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

Untuk petunjuk penyiapan terperinci untuk berbagai klien dan penggunaan API, lihat Panduan Server MCP yang Dihosting.

Untuk mendapatkan token akses Mapbox:

1. Daftar untuk akun Mapbox gratis di mapbox.com/signup
2. Navigasikan ke halaman Akun Anda
3. Buat token baru atau gunakan token publik bawaan

Untuk informasi lebih lanjut tentang token akses Mapbox, lihat dokumentasi Mapbox tentang token akses.

Panduan Integrasi

Untuk petunjuk penyiapan terperinci untuk berbagai integrasi, lihat panduan berikut:

• Penyiapan Claude Desktop - Petunjuk untuk mengonfigurasi Claude Desktop agar bekerja dengan server MCP ini
• Penyiapan Goose - Menyiapkan kerangka kerja agen AI Goose
• Penyiapan VS Code - Menyiapkan lingkungan pengembangan di Visual Studio Code
• Penyiapan Cursor AI IDE - Menyiapkan lingkungan pengembangan di Cursor AI IDE
• Integrasi Smolagents - Contoh yang menunjukkan cara menghubungkan agen AI Smolagents ke alat Mapbox
• Mengimpor Alat Secara Langsung - Gunakan alat Mapbox di aplikasi Anda sendiri tanpa menjalankan server MCP
• Panduan render_map_tool - Primitif visualisasi peta: skema payload lengkap dan cara merender data Anda sendiri secara mandiri, tanpa alat Mapbox lainnya
• Elisitasi - Bagaimana search_and_geocode_tool dan directions_tool meminta pengguna untuk membedakan hasil atau memilih rute, dan bagaimana mereka melakukan fallback dengan baik saat klien tidak mendukungnya

Contoh Perintah

Coba perintah-perintah ini dengan Claude Desktop atau klien MCP lainnya setelah penyiapan:

Penentuan Lokasi

Untuk kueri berbasis koordinat — "apa yang dekat dengan saya", "lingkungan apa ini", "apa yang dapat dijangkau dalam N menit" — gunakan ground_location_tool. Alat ini menggabungkan reverse geocoding, pencarian kategori, dan isokron dalam satu panggilan, secara adaptif memilih strategi yang tepat berdasarkan kueri, dan mengembalikan catatan bertipe (nama, alamat, koordinat, jarak, poligon keterjangkauan) dengan kutipan.

Masing-masing dari empat perintah di bawah ini menggunakan strategi berbeda dalam satu panggilan alat:

• Lingkungan — "Lingkungan apa 47.6097, -122.3408, dan apa yang ada di sekitar saya?"
• POI — "Kedai kopi dalam jarak 10 menit berjalan kaki dari 40.7580, -73.9855"
• Wilayah — "Apa yang dapat saya jangkau dalam 15 menit berjalan kaki dari 37.7749, -122.4194?"
• Penentuan Rute — "Titik yang dapat dirute terdekat untuk menurunkan seseorang di 34.0522, -118.2437"

Penemuan Lokasi

• "Temukan kedai kopi dalam jarak berjalan kaki dari Empire State Building"
• "Saya ingin pergi dari Seattle ke Portland, apakah ada Starbucks di sepanjang jalan?"
• "Tunjukkan stasiun pengisian bahan bakar di sepanjang rute dari Boston ke New York"
• "Restoran apa yang dekat dengan Times Square?"

Navigasi & Perjalanan

• "Dapatkan petunjuk arah berkendara dari LAX ke Hollywood dengan lalu lintas saat ini"
• "Berapa lama waktu yang dibutuhkan untuk berjalan kaki dari Central Park ke Times Square?"
• "Hitung waktu perjalanan dari hotel saya (Four Seasons) ke Bandara JFK dengan taksi saat jam sibuk"

Visualisasi & Peta

• "Menggunakan alat render peta Mapbox, tunjukkan petunjuk arah dari Jembatan Golden Gate ke Union Square di San Francisco" — merender rute interaktif langsung di peta Mapbox sungguhan
• "Buat gambar peta yang menampilkan rute dari Jembatan Golden Gate ke Fisherman's Wharf dengan penanda di kedua lokasi"
• "Tunjukkan tampilan satelit Manhattan dengan landmark utama yang ditandai"
• "Buat peta yang menyoroti semua lokasi Starbucks dalam jarak satu mil dari pusat kota Seattle"
• "Tampilkan poligon isian di atas koordinat ini: [...], dengan penanda berlabel 'Warehouse' di [...]" — merender GeoJSON Anda sendiri secara langsung melalui render_map_tool, tanpa alat Mapbox lain yang diperlukan

Analisis & Perencanaan

• "Tunjukkan area yang dapat dijangkau dalam 30 menit dari pusat kota Portland dengan mobil"
• "Hitung matriks waktu perjalanan antara 3 lokasi hotel ini (Marriott, Sheraton, dan Hilton) dan pusat konvensi di Denver"
• "Temukan rute optimal yang mengunjungi 3 objek wisata ini (Golden Gate, Musical Stairs, dan Fisherman's Wharf) di San Francisco"
• "Optimalkan rute pengiriman untuk 8 alamat ini: [daftar alamat]"

GPS & Pencocokan Rute

• "Bersihkan jejak GPS ini dan tampilkan rute sebenarnya di jalan: [daftar koordinat dengan stempel waktu]"
• "Tempelkan perjalanan sepeda yang direkam ini ke jaringan bersepeda: [koordinat GPS]"
• "Cocokkan rute berkendara ini dengan jaringan jalan dan tampilkan tingkat kemacetan lalu lintas"

Perhitungan Geospasial Offline

• "Berapa jarak dalam mil antara dua koordinat ini?"
• "Hitung luas poligon ini dalam kilometer persegi"
• "Apakah titik di 37.7749°LU, 122.4194°BB berada di dalam poligon area layanan ini?"
• "Berapa azimuth dari San Francisco ke New York?"
• "Temukan titik tengah antara London dan Paris"
• "Buat zona buffer 5 mil di sekitar lokasi ini"
• "Hitung sentroid dari batas lingkungan ini"
• "Berapa kotak pembatas untuk koordinat rute ini?"
• "Sederhanakan poligon kompleks ini untuk mengurangi jumlah titik"

Tips untuk Hasil yang Lebih Baik

• Bersikap spesifik tentang lokasi (gunakan alamat lengkap atau nama landmark)
• Tentukan metode perjalanan pilihan Anda (berkendara, berjalan kaki, bersepeda)
• Sertakan batasan waktu saat relevan ("saat jam sibuk", "pukul 3 sore")
• Minta format keluaran spesifik saat diperlukan ("sebagai gambar peta", "dalam format JSON")

Contoh terperinci: Lihat examples/search-along-route.md untuk contoh komprehensif perintah search-along-route dengan berbagai kasus penggunaan dan petunjuk pengujian MCP Inspector.

Sumber Daya

Server MCP mengekspos data referensi statis sebagai sumber daya MCP. Sumber daya menyediakan akses hanya-baca ke data yang dapat dirujuk klien secara langsung tanpa melakukan panggilan alat.

Sumber Daya yang Tersedia

Sumber Daya Kategori Mapbox

Pola URI: mapbox://categories atau mapbox://categories/{language}

Akses daftar lengkap ID kategori yang tersedia untuk digunakan dengan alat pencarian kategori. Kategori dapat digunakan untuk memfilter hasil pencarian berdasarkan jenis (misalnya, "restaurant", "hotel", "gas_station").

Contoh:

• mapbox://categories - Daftar kategori bawaan (Inggris)
• mapbox://categories/ja - Nama kategori Jepang
• mapbox://categories/es - Nama kategori Spanyol

Mengakses Sumber Daya:

• Klien dengan dukungan sumber daya MCP asli: Gunakan metode protokol MCP resources/read
• Klien tanpa dukungan sumber daya: Gunakan resource_reader_tool dengan URI sumber daya

Pratinjau Peta Kaya (render_map_tool)

Setiap alat geospasial di server ini (petunjuk arah, isokron, pencarian, dan lainnya) dapat menampilkan hasilnya sebagai peta Mapbox GL JS interaktif langsung melalui render_map_tool — primitif visualisasi tunggal server. Alat ini merender melalui protokol MCP Apps (@modelcontextprotocol/ext-apps) sebagai panel HTML mandiri langsung di dalam obrolan, dengan toggle Fullscreen, di klien yang didukung:

• Claude Desktop ✅
• VS Code with GitHub Copilot ✅
• Claude Code ✅
• Goose ✅

Anda tidak memerlukan alat lain dari server ini untuk menggunakannya. render_map_tool juga menerima GeoJSON yang disusun manual secara langsung — poligon, penanda, dan rute Anda sendiri — tanpa ketergantungan pada directions_tool, isochrone_tool, atau panggilan API Mapbox lainnya. Lihat panduan render_map_tool lengkap untuk skema payload dan contoh mandiri yang lengkap.

Jika Anda memerlukan gambar statis yang dijamin di klien tanpa dukungan MCP Apps, gunakan static_map_image_tool sebagai gantinya — alat ini mengembalikan PNG/JPEG yang dienkode base64 yang dapat ditampilkan oleh setiap klien.

CLIENT_NEEDS_RESOURCE_FALLBACK

Alat Fallback Sumber Daya (Opsional untuk Klien yang Tidak Sesuai)

Sumber daya adalah fitur inti MCP yang didukung oleh sebagian besar klien (Claude Desktop, VS Code, MCP Inspector, dll.). Namun, beberapa klien (seperti smolagents) tidak mendukung sumber daya sama sekali. Untuk klien ini, server dapat menyediakan "alat fallback sumber daya" yang mengirimkan konten yang sama dengan sumber daya tetapi melalui panggilan alat.

Alat Fallback:

• resource_reader_tool - Fallback generik untuk membaca sumber daya apa pun berdasarkan URI
• category_list_tool - Menyediakan akses ke daftar kategori (mapbox://categories)

Secara bawaan, alat-alat ini TIDAK disertakan (mengasumsikan klien Anda mendukung sumber daya). Jika klien Anda tidak mendukung sumber daya, aktifkan alat fallback:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Kapan mengatur ini:

• ✅ Atur ke true jika menggunakan smolagents atau klien lain tanpa dukungan sumber daya
• ❌ Biarkan tidak diatur (bawaan) jika menggunakan Claude Desktop, VS Code, MCP Inspector, atau klien yang mendukung sumber daya
• ❌ Biarkan tidak diatur jika ragu (sebagian besar klien mendukung sumber daya)

Alat

Alat Utilitas

Resource Reader Tool

Menyediakan akses ke sumber daya MCP untuk klien yang tidak mendukung API sumber daya MCP asli. Gunakan alat ini untuk membaca sumber daya seperti daftar kategori.

Parameter:

• uri: URI sumber daya yang akan dibaca (misalnya, mapbox://categories, mapbox://categories/ja)

Contoh Penggunaan:

• Baca kategori bawaan: {"uri": "mapbox://categories"}
• Baca kategori Jepang: {"uri": "mapbox://categories/ja"}

Catatan: Jika klien MCP Anda mendukung sumber daya asli, lebih baik gunakan API sumber daya secara langsung untuk performa yang lebih baik.

Alat Geospasial Offline

Alat-alat ini melakukan perhitungan geospasial sepenuhnya offline tanpa memerlukan panggilan API Mapbox. Alat-alat ini menggunakan Turf.js untuk perhitungan geografis yang akurat dan dapat bekerja di mana saja, bahkan tanpa koneksi internet.

Distance Tool

Menghitung jarak antara dua koordinat geografis menggunakan rumus Haversine.

Fitur:

• Mendukung beberapa satuan: kilometer, mil, meter, kaki, mil laut
• Perhitungan jarak lingkaran besar yang akurat
• Tidak memerlukan panggilan API

Contoh Penggunaan: "Berapa jarak antara San Francisco (37.7749°LU, 122.4194°BB) dan New York (40.7128°LU, 74.0060°BB)?"

Points Within Polygon Tool

Menguji satu atau lebih titik terhadap poligon atau multipoligon, hanya mengembalikan titik yang berada di dalamnya. Menangani satu titik atau sekumpulan titik dalam satu panggilan.

Fitur:

• Bekerja dengan poligon kompleks termasuk lubang
• Mendukung multipoligon
• Menguji batch sejumlah titik dalam satu panggilan
• Berguna untuk geofencing, validasi zona pengiriman, dan segmentasi pelanggan

Contoh Penggunaan: "Alamat pengiriman mana yang berada di dalam area layanan kita?"

Alat Tujuan

Menghitung titik tujuan berdasarkan titik awal, arah bearing, dan jarak menggunakan offset geodesik (lingkaran besar).

Fitur:

• Offset garis lurus, bukan jalur yang dirutekan
• Berguna untuk "temukan titik 5 km utara dari X" atau membuat offset pencarian
• Tidak memerlukan panggilan API

Contoh Penggunaan: "Apa titik 10 km timur laut dari Space Needle?"

Alat Bearing

Menghitung arah kompas (bearing) dari satu koordinat ke koordinat lainnya.

Fitur:

• Mengembalikan bearing dalam derajat (0-360°)
• Menyediakan arah mata angin (U, TL, T, TG, S, BD, B, BL)
• Berguna untuk navigasi dan kueri arah

Contoh Penggunaan: "Ke arah mana saya harus pergi dari sini ke bandara?"

Alat Titik Tengah

Menemukan titik tengah geografis antara dua koordinat di sepanjang jalur lingkaran besar.

Fitur:

• Menghitung titik tengah yang sebenarnya pada permukaan bumi yang melengkung
• Berguna untuk saran titik pertemuan
• Menangani perhitungan jarak jauh dengan benar

Contoh Penggunaan: "Apa titik di tengah antara San Francisco dan New York?"

Alat Centroid

Menghitung pusat geometris (centroid) dari poligon atau multipoligon.

Fitur:

• Bekerja dengan bentuk kompleks
• Mengembalikan rata-rata aritmetika dari semua titik
• Berguna untuk menempatkan label atau penanda

Contoh Penggunaan: "Di mana saya harus menempatkan penanda untuk batas lingkungan ini?"

Alat Luas

Menghitung luas poligon.

Fitur:

• Mendukung beberapa satuan: meter persegi, kilometer persegi, acre, hektar, mil persegi, kaki persegi
• Perhitungan luas yang akurat di permukaan bumi
• Bekerja dengan poligon dalam berbagai ukuran

Contoh Penggunaan: "Berapa luas taman ini dalam acre?"

Alat Kotak Batas

Menghitung kotak batas minimum (bbox) yang berisi geometri.

Fitur:

• Bekerja dengan titik, garis, poligon, dan multipoligon
• Mengembalikan [bujurMin, lintangMin, bujurMaks, lintangMaks]
• Berguna untuk perhitungan viewport dan indeks spasial

Contoh Penggunaan: "Apa kotak batas untuk rute ini?"

Alat Buffer

Membuat zona buffer (poligon) di sekitar titik, garis, atau poligon.

Fitur:

• Mendukung beberapa satuan jarak
• Membuat buffer melingkar di sekitar titik
• Berguna untuk analisis kedekatan dan membuat zona pengaruh

Contoh Penggunaan: "Tampilkan zona buffer 5 km di sekitar lokasi ini"

Alat Penyederhanaan

Mengurangi jumlah titik sudut pada garis atau poligon menggunakan algoritma Douglas-Peucker.

Fitur:

• Toleransi yang dapat dikonfigurasi untuk tingkat detail
• Mempertahankan bentuk keseluruhan sambil mengurangi kompleksitas
• Berguna untuk mengurangi ukuran file dan meningkatkan performa render
• Opsi untuk mempertahankan topologi (mencegah perpotongan sendiri)

Contoh Penggunaan: "Sederhanakan batas kompleks ini untuk mengurangi jumlah titik"

Alat Panjang

Mengukur total panjang garis yang didefinisikan oleh serangkaian koordinat.

Fitur:

• Mendukung kilometer, mil, meter, dan kaki
• Berguna untuk mengukur rute yang digambar, jalur, atau batas tanpa panggilan API routing

Contoh Penggunaan: "Berapa panjang jalur pendakian ini?"

Alat Convex Hull

Menghitung convex hull dari sekumpulan titik — poligon cembung terkecil yang memuat semua titik tersebut.

Fitur:

• Berguna untuk analisis area pembatas atau memperkirakan area cakupan
• Bekerja offline tanpa panggilan API

Contoh Penggunaan: "Apa poligon terkecil yang memuat semua lokasi toko ini?"

Alat Titik Terdekat

Menemukan titik terdekat dalam kumpulan ke titik target tertentu.

Fitur:

• Lebih efisien daripada memanggil distance_tool untuk setiap kandidat lalu mengurutkannya
• Berguna untuk menemukan toko, halte, atau landmark terdekat dari suatu lokasi

Contoh Penggunaan: "Toko mana yang paling dekat dengan lokasi saya saat ini?"

Alat Titik Terdekat pada Garis

Menempelkan titik ke posisi terdekat pada garis atau rute, mengembalikan titik tersebut dan jaraknya.

Fitur:

• Berguna untuk "titik mana pada rute ini yang paling dekat dengan lokasi saya?" atau pencocokan peta tanpa panggilan API

Contoh Penggunaan: "Di mana saya paling dekat dengan jalur pendakian ini saat ini?"

Alat Gabungan, Irisan, dan Selisih

Menggabungkan atau membandingkan dua atau lebih poligon — union_tool menggabungkannya menjadi satu geometri, intersect_tool menemukan area yang mereka bagikan, dan difference_tool mengurangkan satu dari yang lain.

Fitur:

• Berguna untuk menggabungkan area layanan, menemukan tumpang tindih cakupan, atau menghitung zona pengecualian (misalnya "apa yang dicakup oleh zona A tetapi bukan zona B?")
• Bekerja sepenuhnya offline — tidak memerlukan panggilan API
• Masing-masing mengembalikan referensi render_map_tool sehingga hasil dapat divisualisasikan langsung

Contoh Penggunaan: "Gabungkan dua zona pengiriman ini menjadi satu area cakupan" / "Di mana dua isokron ini tumpang tindih?" / "Bagian mana dari area layanan ini yang tidak dicakup oleh isokron 15 menit kita?"

Alat API Mapbox

Alat Daftar Kategori (Tidak digunakan lagi)

⚠️ Tidak digunakan lagi: Gunakan resource_reader_tool dengan URI mapbox://categories sebagai gantinya, atau akses sumber daya mapbox://categories secara langsung jika klien Anda mendukung sumber daya MCP.

Alat ini dipertahankan untuk kompatibilitas mundur dengan klien yang tidak mendukung sumber daya MCP atau resource_reader_tool.

Alat Matriks

Menghitung waktu tempuh dan jarak antara beberapa titik menggunakan Mapbox Matrix API. Fitur meliputi:

• Perhitungan routing satu-ke-banyak, banyak-ke-satu, atau banyak-ke-banyak yang efisien
• Dukungan untuk berbagai profil perjalanan (driving-traffic, driving, walking, cycling)
• Spesifikasi waktu keberangkatan untuk perhitungan yang sadar lalu lintas
• Ringkasan rute dengan metrik jarak dan durasi
• Kontrol pendekatan (batas jalan/tanpa batas) dan rentang keberangkatan bearing yang diizinkan

Alat Gambar Statis

Menghasilkan gambar peta statis menggunakan Mapbox static image API. Fitur meliputi:

• Gaya peta khusus (streets, outdoors, satellite, dll.)
• Dimensi gambar dan tingkat zoom yang dapat disesuaikan
• Dukungan untuk beberapa penanda dengan warna dan label khusus
• Opsi overlay termasuk polyline dan poligon
• Penyesuaian otomatis ke koordinat yang ditentukan

Alat Pencarian Kategori

Melakukan pencarian kategori menggunakan Mapbox Search Box category search API. Fitur meliputi:

• Mencari tempat menarik berdasarkan kategori (restoran, hotel, pom bensin, dll.)
• Penyaringan berdasarkan kedekatan geografis
• Batas hasil yang dapat disesuaikan
• Metadata kaya untuk setiap hasil
• Dukungan untuk banyak bahasa

Alat Geocoding Terbalik

Melakukan geocoding terbalik menggunakan Mapbox geocoding V6 API. Fitur meliputi:

• Mengubah koordinat geografis menjadi alamat yang dapat dibaca manusia
• Tingkat detail yang dapat disesuaikan (jalan, lingkungan, kota, dll.)
• Penyaringan hasil berdasarkan jenis (alamat, poi, lingkungan, dll.)
• Dukungan untuk banyak bahasa
• Informasi konteks lokasi yang kaya

Alat Lokasi Tanah

Menjawab pertanyaan "apa yang dekat dengan koordinat ini" dalam satu panggilan — nama tempat, tempat menarik terdekat, dan jangkauan waktu tempuh — bersumber dari data Mapbox langsung dengan kutipan. Gunakan ini sebagai gantinya dari merangkai reverse_geocode_tool dengan pencarian web.

Fitur:

• Mengklasifikasikan kueri (routing, konteks lingkungan, pencarian POI, atau wilayah/jangkauan) dan hanya mengambil data yang relevan
• Pencarian POI terdekat berdasarkan kategori, jika diminta
• Ringkasan jangkauan waktu tempuh (berbasis isokron)
• Mengembalikan referensi render_map_tool dengan lokasi berkelanjutan dan POI terdekat yang diplot

Contoh Penggunaan: "Di lingkungan mana koordinat ini berada, dan adakah kedai kopi di dekatnya?"

Alat Detail Tempat

Mengambil informasi terperinci tentang tempat tertentu menggunakan ID Mapbox-nya — foto, jam buka, peringkat, nomor telepon, dan URL situs web. Gunakan setelah search_and_geocode_tool, category_search_tool, atau reverse_geocode_tool untuk mendapatkan detail lebih lanjut tentang hasil tertentu.

Contoh Penggunaan: "Ceritakan lebih lanjut tentang hasil kedai kopi pertama itu — jam buka, nomor telepon, dan situs web"

Alat Petunjuk Arah

Mengambil petunjuk arah routing menggunakan Mapbox Directions API. Fitur meliputi:

• Dukungan untuk berbagai profil routing: driving (dengan lalu lintas langsung atau tipikal), walking, dan cycling
• Rute dari beberapa titik jalan (2-25 pasang koordinat)
• Opsi rute alternatif
• Anotasi rute (jarak, durasi, kecepatan, kemacetan)
• Opsi penjadwalan:
  • Waktu keberangkatan di masa depan (depart_at) untuk profil driving dan driving-traffic
  • Waktu kedatangan yang diinginkan (arrive_by) hanya untuk profil driving
• Optimasi khusus profil:
  • Driving: batasan dimensi kendaraan (tinggi, lebar, berat)
• Opsi pengecualian untuk routing:
  • Pengecualian umum: rute feri, tol tunai saja
  • Pengecualian khusus driving: tol, jalan tol, jalan tidak beraspal, terowongan, perbatasan negara, perbatasan negara bagian
  • Pengecualian titik khusus (hingga 50 titik geografis yang harus dihindari)
• Format keluaran geometri GeoJSON

Alat Isokron

Menghitung area yang dapat dijangkau dalam jumlah waktu tertentu dari suatu lokasi menggunakan Mapbox Isochrone API. Fitur meliputi:

• Dukungan untuk berbagai profil perjalanan (driving, walking, cycling)
• Waktu perjalanan atau jarak yang dapat disesuaikan
• Pembuatan beberapa kontur (misalnya, rentang 15, 30, 45 menit)
• Spesifikasi waktu keberangkatan atau kedatangan opsional
• Kustomisasi warna untuk visualisasi

Alat Pencarian dan Geocoding

Menggunakan endpoint Mapbox Search Box Text Search API untuk mendukung pencarian dan geocoding POI, alamat, tempat, dan jenis lain yang didukung oleh API tersebut. Alat ini menggabungkan fungsionalitas yang sebelumnya disediakan oleh ForwardGeocodeTool dan PoiSearchTool (dari versi sebelumnya dari server MCP ini) menjadi satu alat.

Alat Pencocokan Peta

Menempelkan jejak GPS ke jaringan jalan menggunakan Mapbox Map Matching API. Fitur meliputi:

• Mengubah jejak GPS yang berisik menjadi rute bersih di jaringan jalan
• Dukungan untuk berbagai profil perjalanan (driving, driving-traffic, walking, cycling)
• Menangani hingga 100 pasang koordinat per permintaan
• Stempel waktu opsional untuk akurasi yang lebih baik berdasarkan kecepatan
• Radius penempelan yang dapat dikonfigurasi untuk tingkat kualitas GPS yang berbeda
• Anotasi rute (batas kecepatan, jarak, durasi, kemacetan lalu lintas)
• Beberapa format keluaran geometri (GeoJSON, polyline)

Contoh Penggunaan: "Bersihkan jejak GPS ini dan tempelkan ke jalan: [koordinat dengan stempel waktu]"

Alat Optimasi

Menemukan rute optimal melalui beberapa lokasi menggunakan Mapbox Optimization API. Fitur meliputi:

• Menyelesaikan masalah penjual keliling (TSP) untuk 2-12 lokasi
• Dukungan untuk berbagai profil perjalanan (driving, driving-traffic, walking, cycling)
• Konfigurasi titik awal dan akhir yang fleksibel
• Optimasi pulang-pergi atau satu arah
• Instruksi navigasi belokan demi belokan (opsional)
• Anotasi rute (jarak, durasi, kecepatan)
• Beberapa format keluaran geometri (GeoJSON, polyline)

Contoh Penggunaan: "Temukan rute optimal untuk mengunjungi 5 pemberhentian ini: [daftar alamat atau koordinat]"

Catatan: API V2 dengan fitur lanjutan (jendela waktu, batasan kapasitas, banyak kendaraan) tersedia tetapi memerlukan akses beta. Implementasi V2 disertakan dalam basis kode tetapi tidak terdaftar secara default.

Pengembangan

Memeriksa Server

Menggunakan Node.js

# Run the built image
npm run inspect:build

Menggunakan 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

Membuat Alat Baru

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

Merilis Versi Baru

# 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

Penting: Alur kerja penerbit memvalidasi bahwa versi package.json dan server.json cocok dengan versi rilis. Melewatkan pembaruan versi atau sinkronisasi manifes akan menyebabkan kegagalan penerbitan.

Tracing OpenTelemetry

Server MCP ini menyertakan tracing OpenTelemetry yang komprehensif untuk observabilitas produksi:

Demo Cepat

# 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

Catatan: Server secara otomatis memuat konfigurasi dari file .env Anda saat startup. File .env.example berisi contoh konfigurasi untuk berbagai platform observabilitas.

Platform Observabilitas yang Didukung

Contoh konfigurasi yang disertakan dalam .env.example untuk:

Penyedia Cloud:

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

Platform SaaS:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Backend apa pun yang kompatibel dengan OTLP

Konfigurasi Produksi

Lihat docs/tracing.md untuk petunjuk pengaturan lengkap termasuk:

• 🔧 Panduan konfigurasi khusus platform
• 📊 Pengaturan autentikasi dan endpoint
• 🎯 Atribut dan konteks trace kustom
• 🚀 Optimasi kinerja (overhead minimal)
• 🔍 Pemecahan masalah dan debugging

Fitur Tracing:

• ✅ Pelacakan pemuatan konfigurasi (pemuatan file .env)
• ✅ Pelacakan eksekusi alat otomatis
• ✅ Instrumentasi permintaan HTTP dengan ID korelasi CloudFront
• ✅ Eksportir yang dapat dikonfigurasi (console, OTLP)
• ✅ Sadar keamanan (perlindungan data, validasi JWT)
• ✅ Siap produksi (overhead CPU <1%)

Kontribusi

Kami menyambut kontribusi untuk Mapbox MCP Server! Silakan baca CONTRIBUTING.md sebelum mengirimkan pull request.

Standar dan pedoman lengkap:

• CONTRIBUTING.md - Memulai, proses PR, referensi cepat
• Engineering Standards (docs/engineering_standards.md) - Standar kualitas kode, pengujian, dokumentasi, dan kolaborasi yang lengkap
• Claude Code Guide (CLAUDE.md) - Standar dan pola untuk kontributor yang menggunakan Claude Code
• AI Agent Instructions (AGENTS.md) - Panduan untuk asisten pengkodean AI lainnya (Cursor, Continue, Aider, dll.)
• GitHub Copilot Guidelines - Praktik terbaik untuk menggunakan GitHub Copilot secara bertanggung jawab

Panduan Cepat untuk Kontributor

1. Fork repositori dan clone fork Anda
2. Instal dependensi: npm install
3. Buat perubahan Anda mengikuti standar pengkodean kami
4. Jalankan pengujian dan linting: npm test && npm run lint
5. Tambahkan pengujian untuk semua fungsionalitas baru
6. Kirimkan pull request dengan deskripsi yang jelas

Semua kontribusi harus lulus pemeriksaan CI dan proses peninjauan kode kami. Lihat docs/engineering_standards.md untuk persyaratan terperinci.

Penggunaan Data & Privasi

Data apa yang dikirim ke API Mapbox

Saat Anda menggunakan alat server MCP, data berikut dikirim langsung dari lingkungan Anda ke API Mapbox:

• Alat geocoding: Teks alamat/lokasi, koordinat, filter negara/wilayah
• Alat pencarian: Kueri pencarian, koordinat lokasi untuk kedekatan, filter kategori
• Alat petunjuk arah: Koordinat awal/akhir, titik jalan, preferensi rute, batasan kendaraan
• Alat matriks: Beberapa pasangan koordinat, profil perjalanan, waktu keberangkatan
• Alat peta statis: Koordinat, tingkat zoom, preferensi gaya, informasi penanda
• Alat isokron: Koordinat asal, parameter waktu/jarak, profil perjalanan

Privasi Anda

• Eksekusi lokal: Semua panggilan API dibuat langsung dari lingkungan Anda ke API Mapbox
• Keamanan token: Token API Mapbox Anda tetap berada di mesin lokal Anda dan tidak pernah dikirimkan ke atau disimpan oleh server MCP ini
• Tanpa penyimpanan data: Server MCP ini tidak menyimpan, mencatat, atau mengumpulkan data atau permintaan API Anda
• Komunikasi langsung: Tidak ada server perantara antara Anda dan API Mapbox

Penggunaan data pihak ketiga

• Kebijakan privasi Mapbox mengatur data yang dikirim ke API mereka: https://www.mapbox.com/legal/privacy/
• Penggunaan API: Ketentuan standar API Mapbox berlaku untuk semua permintaan yang dibuat melalui alat-alat ini
• Retensi data: Lihat dokumentasi Mapbox untuk kebijakan retensi data mereka

Dukungan & Kontak

Untuk Masalah Server MCP

• Email: mcp-feedback@mapbox.com
• GitHub Issues: Laporkan bug dan permintaan fitur

Untuk Pertanyaan API Mapbox

• Dukungan Mapbox: https://support.mapbox.com/
• Dokumentasi: https://docs.mapbox.com/
• Status API: https://status.mapbox.com/

Komitmen Pemeliharaan

Server MCP ini secara resmi dipelihara oleh Mapbox, Inc. Kami menyediakan:

• Pembaruan rutin untuk fitur API Mapbox baru
• Perbaikan bug dan pembaruan keamanan
• Kompatibilitas dengan versi protokol MCP terbaru
• Dukungan komunitas melalui GitHub issues

---

MIT License