Mapbox

Mapbox MCP Server

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

Buka Kecerdasan Geospasial untuk Aplikasi AI Anda

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

• Geokode global untuk mengonversi alamat dan nama tempat menjadi koordinat, dan sebaliknya
• Pencarian tempat menarik (POI) di jutaan bisnis, landmark, dan tempat di seluruh dunia
• Perutean multimoda 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 bagi beberapa perhentian (masalah penjual keliling)
• Pencocokan peta untuk menyesuaikan jejak GPS ke jaringan jalan demi visualisasi rute yang rapi
• Pembuatan isokron untuk memvisualisasikan area yang dapat dijangkau dalam batas waktu atau jarak tertentu
• Perenderan peta langsung dan interaktif (render_map_tool) untuk menampilkan rute, hasil pencarian, dan GeoJSON kustom Anda sendiri pada peta Mapbox GL JS sungguhan langsung di dalam obrolan
• Gambar peta statis untuk membuat representasi visual lokasi, rute, dan data geografis
• Perhitungan geospasial luring untuk jarak, luas, arah, buffer, dan analisis spasial tanpa memerlukan panggilan API

Baik Anda sedang membangun asisten perjalanan AI, pengoptimal logistik, sistem rekomendasi berbasis lokasi, maupun aplikasi apa pun yang perlu memahami "di mana", Mapbox MCP Server menyediakan kecerdasan spasial yang memungkinkan semuanya. Anda juga dapat mengaktifkannya di klien populer seperti Claude Desktop dan VS Code. Lihat detailnya di bawah.

Penggunaan

Token akses Mapbox diperlukan untuk menggunakan server MCP ini.

Endpoint MCP Terhosting

Untuk akses cepat, Anda dapat menggunakan endpoint MCP terhosting kami:

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

Untuk petunjuk penyiapan terperinci bagi berbagai klien dan penggunaan API, lihat Panduan MCP Server Terhosting.

Untuk mendapatkan token akses Mapbox:

1. Daftar akun Mapbox gratis di mapbox.com/signup
2. Buka halaman Akun Anda
3. Buat token baru atau gunakan token publik default

Untuk informasi selengkapnya tentang token akses Mapbox, lihat dokumentasi Mapbox tentang token akses.

Panduan Integrasi

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

• Penyiapan Claude Desktop - Petunjuk untuk mengonfigurasi Claude Desktop agar berfungsi 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 MCP server
• Panduan render_map_tool - Primitif visualisasi peta: skema payload lengkap dan cara merender data Anda sendiri secara mandiri, tanpa alat Mapbox lainnya
• Permintaan Klarifikasi - Cara search_and_geocode_tool dan directions_tool meminta pengguna memperjelas hasil yang ambigu atau memilih rute, serta cara keduanya menangani situasi dengan baik jika klien tidak mendukungnya

Contoh Prompt

Coba prompt berikut dengan Claude Desktop atau klien MCP lainnya setelah penyiapan:

Penentuan Lokasi

Untuk kueri yang mengutamakan koordinat — "apa yang ada di dekat saya", "ini lingkungan apa", "apa yang bisa dijangkau dalam N menit" — gunakan ground_location_tool. Alat ini menggabungkan geokode balik, pencarian kategori, dan isokron dalam satu panggilan, memilih strategi yang tepat secara adaptif berdasarkan kueri, serta mengembalikan rekaman bertipe (nama, alamat, koordinat, jarak, poligon jangkauan) beserta sitasi.

Keempat prompt di bawah masing-masing menguji strategi berbeda dalam satu panggilan alat:

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

Penemuan Lokasi

• "Temukan kedai kopi yang dapat dijangkau dengan berjalan kaki dari Empire State Building"
• "Saya ingin pergi dari Seattle ke Portland, apakah ada Starbucks di sepanjang jalan?"
• "Tunjukkan pom bensin di sepanjang rute dari Boston ke New York"
• "Restoran apa saja yang berada di dekat Times Square?"

Navigasi & Perjalanan

• "Dapatkan petunjuk arah berkendara dari LAX ke Hollywood dengan kondisi 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

• "Dengan alat perender peta Mapbox, tunjukkan petunjuk arah dari Golden Gate Bridge ke Union Square di San Francisco" — merender rute langsung dan interaktif pada peta Mapbox sungguhan
• "Buat gambar peta yang menunjukkan rute dari Golden Gate Bridge 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 memerlukan alat Mapbox lainnya

Analisis & Perencanaan

• "Tunjukkan area yang dapat dijangkau dalam 30 menit berkendara dari pusat kota Portland"
• "Hitung matriks waktu perjalanan antara 3 lokasi hotel ini (Marriott, Sheraton, dan Hilton) dan pusat konvensi di Denver"
• "Temukan rute optimal untuk 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

• "Rapikan jejak GPS ini dan tunjukkan rute sebenarnya di jalan: [daftar koordinat dengan stempel waktu]"
• "Sesuaikan perjalanan sepeda yang direkam ini ke jaringan jalur sepeda: [koordinat GPS]"
• "Cocokkan rute berkendara ini dengan jaringan jalan dan tunjukkan tingkat kemacetan lalu lintas"

Perhitungan Geospasial Luring

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

Tips untuk Hasil yang Lebih Baik

• Jelaskan lokasi secara spesifik (gunakan alamat lengkap atau nama landmark)
• Sebutkan metode perjalanan yang Anda inginkan (berkendara, berjalan kaki, bersepeda)
• Sertakan batasan waktu jika relevan ("saat jam sibuk", "pukul 3 sore")
• Minta format keluaran tertentu jika diperlukan ("sebagai gambar peta", "dalam format JSON")

Contoh terperinci: Lihat examples/search-along-route.md untuk contoh lengkap prompt pencarian di sepanjang rute dengan berbagai kasus penggunaan dan petunjuk pengujian MCP Inspector.

Resources

MCP server menyediakan data referensi statis sebagai resource MCP. Resource memberikan akses hanya-baca ke data yang dapat dirujuk langsung oleh klien tanpa melakukan panggilan alat.

Resource yang Tersedia

Resource 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 default (Bahasa Inggris)
• mapbox://categories/ja - Nama kategori dalam bahasa Jepang
• mapbox://categories/es - Nama kategori dalam bahasa Spanyol

Mengakses Resource:

• Klien dengan dukungan resource MCP bawaan: Gunakan metode protokol MCP resources/read
• Klien tanpa dukungan resource: Gunakan resource_reader_tool dengan URI resource

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 langsung dan interaktif melalui render_map_tool — satu-satunya primitif visualisasi server ini. Peta dirender melalui protokol MCP Apps (@modelcontextprotocol/ext-apps) sebagai panel HTML mandiri langsung di dalam obrolan, dengan tombol Layar Penuh, pada klien yang didukung:

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

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

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

CLIENT_NEEDS_RESOURCE_FALLBACK

Alat Fallback Resource (Opsional untuk Klien yang Tidak Patuh)

Resource adalah fitur inti MCP yang didukung oleh sebagian besar klien (Claude Desktop, VS Code, MCP Inspector, dan lainnya). Namun, beberapa klien (seperti smolagents) sama sekali tidak mendukung resource. Untuk klien tersebut, server dapat menyediakan "alat fallback resource" yang menyajikan konten yang sama seperti resource, tetapi melalui panggilan alat.

Alat Fallback:

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

Secara default, alat ini TIDAK disertakan (dengan asumsi klien Anda mendukung resource). Jika klien Anda tidak mendukung resource, aktifkan alat fallback:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Kapan mengaturnya:

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

Alat

Alat Utilitas

Alat Pembaca Resource

Menyediakan akses ke resource MCP bagi klien yang tidak mendukung API resource MCP bawaan. Gunakan alat ini untuk membaca resource seperti daftar kategori.

Parameter:

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

Contoh Penggunaan:

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

Catatan: Jika klien MCP Anda mendukung resource bawaan, sebaiknya gunakan API resource secara langsung untuk kinerja yang lebih baik.

Alat Geospasial Luring

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

Alat Jarak

Hitung 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°N, 122.4194°W) dan New York (40.7128°N, 74.0060°W)?"

Alat Titik di Dalam Poligon

Uji satu atau beberapa titik terhadap poligon atau multipoligon, lalu hanya kembalikan titik yang berada di dalamnya. Menangani satu titik atau sekumpulan titik dalam satu panggilan.

Fitur:

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

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

Tool Tujuan

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

Fitur:

• Offset garis lurus, bukan rute
• Berguna untuk "cari titik 5km di utara X" atau membuat offset pencarian
• Tidak memerlukan panggilan API

Contoh Penggunaan: "Di mana titik yang berjarak 10km di timur laut Space Needle?"

Tool Arah

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

Fitur:

• Mengembalikan bearing dalam derajat (0-360°)
• Memberikan arah mata angin (N, NE, E, SE, S, SW, W, NW)
• Berguna untuk navigasi dan pertanyaan tentang arah

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

Tool Titik Tengah

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

Fitur:

• Menghitung titik tengah sebenarnya di permukaan Bumi yang melengkung
• Berguna untuk saran lokasi pertemuan
• Menangani perhitungan jarak jauh dengan benar

Contoh Penggunaan: "Di mana titik tengah antara San Francisco dan New York?"

Tool Sentroid

Hitung pusat geometris (sentroid) dari poligon atau multipoligon.

Fitur:

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

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

Tool Luas

Hitung luas poligon.

Fitur:

• Mendukung beberapa satuan: meter persegi, kilometer persegi, acre, hektare, mil persegi, kaki persegi
• Perhitungan luas yang akurat di permukaan Bumi
• Berfungsi untuk poligon dengan ukuran apa pun

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

Tool Kotak Pembatas

Hitung kotak pembatas minimum (bbox) yang mencakup suatu geometri.

Fitur:

• Berfungsi dengan titik, garis, poligon, dan multipoligon
• Mengembalikan [minLongitude, minLatitude, maxLongitude, maxLatitude]
• Berguna untuk perhitungan viewport dan pengindeksan spasial

Contoh Penggunaan: "Berapa kotak pembatas untuk rute ini?"

Tool Buffer

Buat 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 pembuatan zona pengaruh

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

Tool Penyederhanaan

Kurangi jumlah verteks pada garis atau poligon menggunakan algoritma Douglas-Peucker.

Fitur:

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

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

Tool Panjang

Ukur panjang total garis yang ditentukan oleh serangkaian koordinat.

Fitur:

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

Contoh Penggunaan: "Berapa panjang jalur pendakian ini?"

Tool Convex

Hitung convex hull dari sekumpulan titik — poligon cembung terkecil yang mencakup semuanya.

Fitur:

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

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

Tool Titik Terdekat

Temukan titik terdekat dalam suatu kumpulan terhadap 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?"

Tool Titik Terdekat pada Garis

Jepret titik ke posisi terdekat pada garis atau rute, lalu kembalikan titik tersebut dan jaraknya.

Fitur:

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

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

Tool Union, Intersect, dan Difference

Gabungkan atau bandingkan dua poligon atau lebih — union_tool menggabungkannya menjadi satu geometri, intersect_tool menemukan area yang sama, dan difference_tool mengurangi satu poligon dari poligon lainnya.

Fitur:

• Berguna untuk menggabungkan area layanan, menemukan tumpang tindih cakupan, atau menghitung zona pengecualian (misalnya, "bagian mana yang tercakup oleh zona A tetapi tidak oleh zona B?")
• Berfungsi sepenuhnya secara offline — tidak memerlukan panggilan API
• Masing-masing mengembalikan referensi render_map_tool agar hasilnya dapat langsung divisualisasikan

Contoh Penggunaan: "Gabungkan dua zona pengiriman ini menjadi satu area cakupan" / "Di mana kedua isokron ini bertumpang tindih?" / "Bagian mana dari area layanan ini yang tidak tercakup oleh isokron 15 menit kami?"

Tool API Mapbox

Tool Daftar Kategori (Tidak Digunakan Lagi)

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

Tool ini dipertahankan untuk kompatibilitas mundur dengan klien yang tidak mendukung resource MCP atau resource_reader_tool.

Tool Matriks

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

• Perhitungan perutean satu-ke-banyak, banyak-ke-satu, atau banyak-ke-banyak yang efisien
• Dukungan untuk berbagai profil perjalanan (driving-traffic, driving, walking, cycling)
• Penentuan waktu keberangkatan untuk perhitungan yang mempertimbangkan lalu lintas
• Ringkasan rute dengan metrik jarak dan durasi
• Pengaturan pendekatan (curb/unrestricted) dan rentang arah keberangkatan yang diizinkan

Tool Gambar Statis

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

• Gaya peta khusus (jalan, alam terbuka, satelit, dll.)
• Dimensi gambar dan tingkat zoom yang dapat disesuaikan
• Dukungan untuk beberapa penanda dengan warna dan label khusus
• Opsi overlay, termasuk garis dan poligon
• Penyesuaian otomatis ke koordinat yang ditentukan

Tool Pencarian Kategori

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

• Mencari tempat menarik berdasarkan kategori (restoran, hotel, SPBU, dll.)
• Pemfilteran berdasarkan kedekatan geografis
• Batas jumlah hasil yang dapat disesuaikan
• Metadata lengkap untuk setiap hasil
• Dukungan untuk beberapa bahasa

Tool Geocoding Terbalik

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

• Mengubah koordinat geografis menjadi alamat yang mudah dibaca
• Tingkat detail yang dapat disesuaikan (jalan, lingkungan, kota, dll.)
• Pemfilteran hasil berdasarkan jenis (alamat, poi, lingkungan, dll.)
• Dukungan untuk beberapa bahasa
• Informasi konteks lokasi yang lengkap

Tool Lokasi Darat

Menjawab pertanyaan "apa yang ada di dekat koordinat ini" dalam satu panggilan — nama tempat, tempat menarik di sekitar, dan jangkauan berdasarkan waktu tempuh — dengan data Mapbox terkini beserta sitasi. Gunakan tool ini alih-alih merangkai reverse_geocode_tool dengan pencarian web.

Fitur:

• Mengklasifikasikan pertanyaan (perutean, konteks lingkungan, pencarian POI, atau wilayah/jangkauan) dan hanya mengambil data yang relevan
• Pencarian POI terdekat berdasarkan kategori, jika diminta
• Ringkasan jangkauan berdasarkan waktu tempuh (berbasis isokron)
• Mengembalikan referensi render_map_tool yang berisi lokasi terverifikasi dan POI di sekitarnya yang ditampilkan pada peta

Contoh Penggunaan: "Koordinat ini berada di lingkungan mana, dan apakah ada kedai kopi di dekatnya?"

Tool Detail Tempat

Mengambil informasi terperinci tentang tempat tertentu menggunakan ID Mapbox-nya — foto, jam buka, rating, 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 webnya"

Tool Petunjuk Arah

Mengambil petunjuk rute menggunakan Mapbox Directions API. Fitur meliputi:

• Dukungan untuk berbagai profil perutean: berkendara (dengan lalu lintas langsung atau kondisi umum), berjalan kaki, dan bersepeda
• Rute melalui beberapa titik perantara (2-25 pasangan koordinat)
• Opsi rute alternatif
• Anotasi rute (jarak, durasi, kecepatan, kemacetan)
• Opsi penjadwalan:
  • Waktu keberangkatan mendatang (depart_at) untuk profil driving dan driving-traffic
  • Waktu kedatangan yang diinginkan (arrive_by) hanya untuk profil driving
• Pengoptimalan khusus profil:
  • Berkendara: batasan dimensi kendaraan (tinggi, lebar, berat)
• Opsi pengecualian untuk perutean:
  • Pengecualian umum: rute feri, tol yang hanya menerima uang tunai
  • Pengecualian khusus berkendara: tol, jalan bebas hambatan, jalan tidak beraspal, terowongan, perbatasan negara, perbatasan negara bagian
  • Pengecualian titik khusus (hingga 50 titik geografis yang harus dihindari)
• Format keluaran geometri GeoJSON

Tool Isokron

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

• Dukungan untuk berbagai profil perjalanan (berkendara, berjalan kaki, bersepeda)
• Waktu atau jarak perjalanan yang dapat disesuaikan
• Pembuatan beberapa kontur (misalnya, rentang 15, 30, 45 menit)
• Opsi penentuan waktu keberangkatan atau kedatangan
• Penyesuaian warna untuk visualisasi

Tool Pencarian dan Geocoding

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

Tool Pencocokan Peta

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

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

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

Tool Pengoptimalan

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

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

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

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

Tool Umpan Balik

Mengirimkan umpan balik pengguna tentang aplikasi atau agen kepada pengembangnya melalui Mapbox Feedback API (Pratinjau Publik). Umpan balik dicatat di akun pemilik token akses, jadi saat Anda membuat aplikasi atau agen di server ini dengan token Anda sendiri, umpan balik pengguna Anda akan masuk ke feed yang sama dengan laporan Feedback Agent dari aplikasi Anda, dan Anda dapat meninjaunya di Feedback Explorer. Tool ini tidak melaporkan masalah kepada Mapbox. Seperti Feedback Agent, tool ini ditujukan untuk segala hal tentang produk Anda yang membantu Anda memahami kebutuhan pengguna, misalnya:

• Tempat yang sudah tutup, memiliki detail yang salah, atau berada di lokasi yang keliru
• Tempat atau alamat yang tidak dapat ditemukan
• Jalan yang ditutup, batas kecepatan yang salah, atau informasi lalu lintas yang keliru
• Rute dengan belokan atau pintu masuk ilegal, atau tanpa rute sama sekali
• Sesuatu tentang aplikasinya sendiri, seperti bug atau saran (application_issue)

Alat ini mengirimkan teks masukan, kategori, dan lokasi, lalu mengembalikan ID dan status item tersebut. Lokasi bersifat opsional untuk masukan yang tidak terkait tempat; API mewajibkannya, jadi untuk saat ini alat mengirimkan 0, 0, sesuai rekomendasi tim Feedback API. Tidak ada yang dikirim tanpa persetujuan pengguna: klien yang mendukung elicitation menampilkan permintaan konfirmasi terlebih dahulu, sedangkan di tempat lain deskripsi alat meminta model untuk mengonfirmasi melalui chat.

Feedback API gratis selama Public Preview. Saat General Availability, Feedback Agent mengenakan biaya $0.02 per item masukan. Untuk menghindari pengiriman laporan masalah yang sama dua kali, sebelum mengirim alat memeriksa laporan milik akun tersebut dari 30 hari terakhir. Jika ada laporan dalam kategori yang sama dan berjarak kurang dari 50 m yang masih menunggu peninjauan (masukan tanpa lokasi tidak diperiksa), alat mengembalikan laporan tersebut alih-alih mengirim laporan baru. Feedback API hanya menampilkan laporan milik akun tersebut, jadi laporan dari akun lain tidak dapat terdeteksi. send_anyway: true melewati pemeriksaan ini jika pengguna mengatakan bahwa masalah yang dilaporkannya berbeda.

Persyaratan: token akses memerlukan cakupan user-feedback:write untuk mengirim masukan, dan user-feedback:read untuk pemeriksaan duplikat. Tanpa cakupan tulis, alat mengembalikan pesan kesalahan yang menjelaskan hal tersebut. Tanpa cakupan baca, alat mengirim masukan tanpa pemeriksaan dan menyatakannya dalam hasil. Untuk tidak menyertakan alat ini, jalankan server dengan --disable-tools feedback_tool.

Contoh Penggunaan: "Blue Bottle di Mint St tutup tahun lalu, bisakah Anda mengirimkannya sebagai masukan?"

Alat Report

Mengirim masukan tentang server Mapbox MCP itu sendiri kepada tim Mapbox yang mengembangkannya: bug, alat yang memberikan hasil salah atau membingungkan, kemampuan yang belum tersedia, atau saran. Masukan dicatat atas nama akun Mapbox sendiri, bukan akun Anda, sehingga tidak memerlukan cakupan token tambahan dan tidak dapat dibaca kembali atau ditarik setelah dikirim. Alat ini bukan untuk melaporkan data peta, tempat, atau rute yang salah.

Server menambahkan versi server, nama dan versi klien, serta nama alat yang menjadi pokok masukan di akhir teks. Tidak ada yang dikirim tanpa persetujuan pengguna: klien yang mendukung elicitation menampilkan permintaan konfirmasi terlebih dahulu, sedangkan di tempat lain deskripsi alat meminta model untuk mengonfirmasi melalui chat.

Alat ini menggunakan endpoint yang ditambahkan tim Feedback API untuk perintah mapbox report milik Mapbox CLI. Untuk tidak menyertakan alat ini, jalankan server dengan --disable-tools report_tool.

Contoh Penggunaan: "Peta tidak menggambar satu pun isokron saya. Bisakah Anda memberi tahu tim Mapbox MCP?"

Alat List public tokens

Menampilkan token akses publik (pk.) milik akun, untuk agen yang membuat halaman web atau aplikasi di luar chat yang memuat Mapbox GL JS atau memanggil Mapbox APIs dari browser. Di dalam chat, render_map_tool tidak memerlukan token. Setiap token disertai nama, keterangan apakah token tersebut adalah token default, batasan URL, dan cakupannya.

Berikan site_url (tempat halaman akan dijalankan), lalu alat merekomendasikan token yang dibatasi untuk URL tersebut jika akun memilikinya. Jika tidak, alat merekomendasikan token publik default dan menyatakan bahwa situs yang dipublikasikan sebaiknya menggunakan token dengan batasan URL, disertai tautan untuk membuatnya. Siapa pun yang menyalin token publik tanpa batasan dapat menggunakannya, dan penggunaannya akan ditagihkan ke akun tersebut.

Alat ini tidak pernah mengembalikan token rahasia atau sementara, dan tidak dapat membuat token (untuk itu diperlukan tokens:write; create_token_tool milik DevKit server dapat melakukannya).

Persyaratan: untuk menampilkan daftar, diperlukan cakupan tokens:read, sama seperti yang digunakan peta dalam chat untuk menemukan token publik default. Dengan token akses pk., atau jika permintaan daftar gagal pada MAPBOX_ACCESS_TOKEN milik server dan MAPBOX_PUBLIC_TOKEN disetel, alat akan mengembalikan token tersebut. Pemanggil dengan token bearer sendiri (server yang di-host) tidak pernah mendapatkan MAPBOX_PUBLIC_TOKEN, dan token yang dibatasi untuk URL lain tidak pernah direkomendasikan. Untuk tidak menyertakan alat ini, jalankan server dengan --disable-tools list_public_tokens_tool.

Contoh Penggunaan: "Buatkan situs satu halaman yang menampilkan tiga lokasi toko kami di peta Mapbox."

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 publisher memvalidasi bahwa versi package.json dan server.json cocok dengan versi rilis. Melewatkan pembaruan versi atau sinkronisasi manifest akan menyebabkan kegagalan publikasi.

Pelacakan OpenTelemetry

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

Demo Singkat

# 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 saat startup. File .env.example menyertakan contoh konfigurasi untuk berbagai platform observabilitas.

Platform Observabilitas yang Didukung

Contoh konfigurasi 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 penyiapan lengkap, termasuk:

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

Fitur Pelacakan:

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

Berkontribusi

Kami menyambut kontribusi untuk Mapbox MCP Server! Harap baca CONTRIBUTING.md sebelum mengirim pull request.

Standar dan panduan lengkap:

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

Mulai Cepat untuk Kontributor

1. Fork repositori dan klon fork Anda
2. Instal dependensi: npm install
3. Buat perubahan sesuai standar coding kami
4. Jalankan pengujian dan linting: npm test && npm run lint
5. Tambahkan pengujian untuk setiap fungsionalitas baru
6. Kirim pull request dengan deskripsi yang jelas

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

Penggunaan Data & Privasi

Data yang dikirim ke Mapbox APIs

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

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

Privasi Anda

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

Penggunaan data pihak ketiga

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

Dukungan & Kontak

Untuk Masalah MCP Server

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

Untuk Pertanyaan tentang Mapbox API

• 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 Mapbox API baru
• Perbaikan bug dan pembaruan keamanan
• Kompatibilitas dengan versi protokol MCP terbaru
• Dukungan komunitas melalui GitHub issues

---

Lisensi MIT