Mapbox

Mapbox MCP Server

Mapbox API’leri için Model Context Protocol (MCP) uygulayan Node.js sunucusu.

Yapay Zekâ Uygulamalarınız için Coğrafi Zekânın Kilidini Açın

Mapbox MCP Server, Mapbox’ın kapsamlı konum zekâsı platformuna sorunsuz erişim sağlayarak tüm yapay zekâ aracılarını veya uygulamalarını coğrafi konum farkındalığına sahip bir sisteme dönüştürür. Bu sunucu sayesinde yapay zekânız yerleri anlayıp bunlar hakkında akıl yürütebilir, fiziksel dünyada yolunu bulabilir ve aşağıdakiler de dâhil olmak üzere zengin coğrafi verilere erişebilir:

• Küresel coğrafi kodlama ile adresleri ve yer adlarını koordinatlara, koordinatları da adreslere ve yer adlarına dönüştürme
• İlgi çekici yer (POI) araması ile dünya çapındaki milyonlarca işletme, simge yapı ve yeri arama
• Gerçek zamanlı trafik bilgileriyle çok modlu rota oluşturma (araba, yaya ve bisiklet)
• Erişilebilirliği analiz etmek ve lojistiği optimize etmek için seyahat süresi matrisleri
• Birden fazla durak için en uygun ziyaret sırasını bulmak üzere rota optimizasyonu (gezgin satıcı problemi)
• Temiz rota görselleştirmesi için GPS izlerini yol ağına oturtan harita eşleştirme
• Belirli süre veya mesafe kısıtları içinde ulaşılabilen alanları görselleştirmek için izokron oluşturma
• Rotaları, arama sonuçlarını ve kendi özel GeoJSON verilerinizi doğrudan sohbet içinde gerçek bir Mapbox GL JS haritasında görüntülemek için canlı, etkileşimli harita oluşturma (render_map_tool)
• Konumların, rotaların ve coğrafi verilerin görsel temsillerini oluşturmak için statik harita görselleri
• API çağrısı gerektirmeden mesafe, alan, yön, tampon bölgeler ve mekânsal analiz için çevrimdışı coğrafi hesaplamalar

Yapay zekâ destekli bir seyahat asistanı, lojistik optimizasyon aracı, konum tabanlı öneri sistemi veya “nerede” sorusunu anlaması gereken herhangi bir uygulama geliştiriyor olun, Mapbox MCP Server bunu mümkün kılacak mekânsal zekâyı sağlar. Ayrıca Claude Desktop ve VS Code gibi popüler istemcilerde de etkinleştirebilirsiniz. Ayrıntılar aşağıda.

Kullanım

Bu MCP sunucusunu kullanmak için Mapbox erişim belirteci gerekir.

Barındırılan MCP Uç Noktası

Hızlı erişim için barındırılan MCP uç noktamızı kullanabilirsiniz:

Uç nokta: https://mcp.mapbox.com/mcp

Farklı istemciler için ayrıntılı kurulum talimatları ve API kullanımı için Barındırılan MCP Sunucusu Kılavuzu bölümüne bakın.

Mapbox erişim belirteci almak için:

1. mapbox.com/signup adresinden ücretsiz bir Mapbox hesabı oluşturun
2. Hesap sayfanıza gidin
3. Yeni bir belirteç oluşturun veya varsayılan genel belirteci kullanın

Mapbox erişim belirteçleri hakkında daha fazla bilgi için erişim belirteçleriyle ilgili Mapbox belgelerine bakın.

Entegrasyon Kılavuzları

Farklı entegrasyonlar için ayrıntılı kurulum talimatlarını aşağıdaki kılavuzlarda bulabilirsiniz:

• Claude Desktop Kurulumu - Claude Desktop’ı bu MCP sunucusuyla çalışacak şekilde yapılandırma talimatları
• Goose Kurulumu - Goose yapay zekâ aracı çerçevesini kurma
• VS Code Kurulumu - Visual Studio Code’da geliştirme ortamı kurma
• Cursor AI IDE Kurulumu - Cursor AI IDE’de geliştirme ortamı kurma
• Smolagents Entegrasyonu - Smolagents yapay zekâ ajanlarını Mapbox araçlarına bağlamayı gösteren örnek
• Araçları Doğrudan İçe Aktarma - MCP sunucusunu çalıştırmadan kendi uygulamalarınızda Mapbox araçlarını kullanma
• render_map_tool Kılavuzu - Harita görselleştirme temel bileşeni: tam yük şeması ve başka hiçbir Mapbox aracı olmadan kendi verilerinizi bağımsız olarak nasıl görüntüleyeceğiniz
• Kullanıcıdan Bilgi İsteme - search_and_geocode_tool ve directions_tool araçlarının sonuçları netleştirmek veya bir rota seçmek için kullanıcıya nasıl soru sorduğu ve istemci bu özelliği desteklemediğinde nasıl sorunsuz biçimde alternatif yönteme geçtiği

Örnek İstemler

Kurulumdan sonra bu istemleri Claude Desktop veya diğer MCP istemcileriyle deneyin:

Konum Belirleme

Koordinat odaklı sorgular için — “yakınımda ne var”, “burası hangi mahalle”, “N dakika içinde nereye ulaşabilirim” — ground_location_tool kullanın. Bu araç, tek bir çağrıda ters coğrafi kodlama, kategori araması ve izokronu bir araya getirir; sorguya göre uygun stratejiyi dinamik olarak seçer ve kaynaklarla birlikte türlendirilmiş kayıtlar (adlar, adresler, koordinatlar, mesafeler, erişilebilirlik poligonları) döndürür.

Aşağıdaki dört istemin her biri, tek bir araç çağrısında farklı bir stratejiyi kullanır:

• Mahalle — “47.6097, -122.3408 hangi mahallede ve çevremde neler var?”
• POI — “40.7580, -73.9855 koordinatına 10 dakikalık yürüme mesafesindeki kahveciler”
• Bölge — “37.7749, -122.4194 koordinatından 15 dakikada yürüyerek nerelere ulaşabilirim?”
• Rota oluşturma — “34.0522, -118.2437 koordinatında birini indirmek için araçla ulaşılabilen en yakın nokta”

Konum Keşfi

• “Empire State Building’e yürüme mesafesindeki kahvecileri bul”
• “Seattle’dan Portland’a gitmek istiyorum; yol üzerinde Starbucks var mı?”
• “Boston’dan New York’a giden rota üzerindeki benzin istasyonlarını göster”
• “Times Square yakınlarında hangi restoranlar var?”

Navigasyon ve Seyahat

• “LAX’ten Hollywood’a güncel trafik durumunu dikkate alarak araba yol tarifi ver”
• “Central Park’tan Times Square’e yürümek ne kadar sürer?”
• “Yoğun saatlerde otelimden (Four Seasons) JFK Havalimanı’na taksiyle yolculuk süresini hesapla”

Görselleştirme ve Haritalar

• “Mapbox harita oluşturma aracını kullanarak San Francisco’daki Golden Gate Köprüsü’nden Union Square’e yol tarifi göster” — gerçek bir Mapbox haritasında canlı, etkileşimli bir rota görüntüler
• “Golden Gate Köprüsü’nden Fisherman’s Wharf’a giden rotayı ve her iki konumda işaretçileri gösteren bir harita görseli oluştur”
• “Manhattan’ın uydu görüntüsünü önemli simge yapılar işaretlenmiş şekilde göster”
• “Seattle şehir merkezinin bir mil çevresindeki tüm Starbucks konumlarını vurgulayan bir harita oluştur”
• “Bu koordinatların üzerine bir dolgu poligonu yerleştir: [...]; [...] konumuna ‘Warehouse’ etiketli bir işaretçi ekle” — başka bir Mapbox aracına gerek kalmadan kendi GeoJSON verilerinizi doğrudan render_map_tool üzerinden görüntüler

Analiz ve Planlama

• “Portland şehir merkezinden arabayla 30 dakika içinde ulaşılabilen alanları göster”
• “Denver’daki bu 3 otel konumu (Marriott, Sheraton ve Hilton) ile kongre merkezi arasındaki seyahat süresi matrisini hesapla”
• “San Francisco’daki bu 3 turistik yeri (Golden Gate, Musical Stairs ve Fisherman’s Wharf) ziyaret etmek için en uygun rotayı bul”
• “Bu 8 adres için teslimat rotasını optimize et: [adres listesi]”

GPS ve Rota Eşleştirme

• “Bu GPS izini temizle ve yollardaki gerçek rotayı göster: [zaman damgalarıyla koordinat listesi]”
• “Kaydedilmiş bu bisiklet sürüşünü bisiklet ağına oturt: [GPS koordinatları]”
• “Bu sürüş rotasını yol ağıyla eşleştir ve trafik yoğunluğu seviyelerini göster”

Çevrimdışı Coğrafi Hesaplamalar

• “Bu iki koordinat arasındaki mesafe mil cinsinden nedir?”
• “Bu poligonun alanını kilometrekare cinsinden hesapla”
• “37.7749°N, 122.4194°W noktasının bu hizmet alanı poligonunun içinde olup olmadığını kontrol et”
• “San Francisco’dan New York’a yön açısı nedir?”
• “Londra ile Paris arasındaki orta noktayı bul”
• “Bu konumun çevresinde 5 millik bir tampon bölge oluştur”
• “Bu mahalle sınırının ağırlık merkezini hesapla”
• “Bu rota koordinatlarının sınırlayıcı kutusu nedir?”
• “Nokta sayısını azaltmak için bu karmaşık poligonu sadeleştir”

Daha İyi Sonuçlar için İpuçları

• Konumları açıkça belirtin (tam adresleri veya simge yapıların adlarını kullanın)
• Tercih ettiğiniz ulaşım yöntemini belirtin (araba, yürüme, bisiklet)
• Gerektiğinde zaman kısıtlarını ekleyin (“yoğun saatlerde”, “15.00’te”)
• Gerektiğinde belirli çıktı biçimleri isteyin (“harita görseli olarak”, “JSON biçiminde”)

Ayrıntılı örnekler: Farklı kullanım senaryolarını ve MCP Inspector test talimatlarını içeren arama boyunca rota istemi örnekleri için examples/search-along-route.md dosyasına bakın.

Kaynaklar

MCP sunucusu, statik başvuru verilerini MCP kaynakları olarak sunar. Kaynaklar, istemcilerin araç çağrısı yapmadan doğrudan başvurabileceği verilere salt okunur erişim sağlar.

Kullanılabilir Kaynaklar

Mapbox Kategorileri Kaynağı

URI Deseni: mapbox://categories veya mapbox://categories/{language}

Kategori arama aracıyla kullanabileceğiniz tüm kategori kimliklerinin listesine erişin. Arama sonuçlarını türe göre filtrelemek için kategoriler kullanılabilir (ör. “restaurant”, “hotel”, “gas_station”).

Örnekler:

• mapbox://categories - Varsayılan (İngilizce) kategori listesi
• mapbox://categories/ja - Japonca kategori adları
• mapbox://categories/es - İspanyolca kategori adları

Kaynaklara Erişim:

• Yerel MCP kaynak desteği olan istemciler: resources/read MCP protokol yöntemini kullanın
• Kaynak desteği olmayan istemciler: Kaynak URI’siyle birlikte resource_reader_tool kullanın

Zengin Harita Önizlemeleri (render_map_tool)

Bu sunucudaki her coğrafi araç (yol tarifi, izokron, arama ve daha fazlası), sonucunu sunucunun tek görselleştirme temel bileşeni olan render_map_tool aracılığıyla canlı, etkileşimli bir Mapbox GL JS haritasında görüntüleyebilir. Harita, desteklenen istemcilerde Tam Ekran düğmesi bulunan, doğrudan sohbet içinde açılan ve kendi içinde çalışan bir HTML paneli olarak MCP Apps protokolü (@modelcontextprotocol/ext-apps) üzerinden oluşturulur:

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

Bu özelliği kullanmak için sunucunun diğer araçlarından hiçbirine ihtiyacınız yok. render_map_tool, kendi poligonlarınızı, işaretçilerinizi ve rotalarınızı içeren, elle oluşturulmuş GeoJSON verilerini de doğrudan kabul eder; directions_tool, isochrone_tool veya başka herhangi bir Mapbox API çağrısına bağlı değildir. Yük şeması ve bağımsız, eksiksiz bir örnek için render_map_tool kılavuzunun tamamına bakın.

MCP Apps desteği olmayan istemcilerde garantili bir statik görsele ihtiyacınız varsa bunun yerine static_map_image_tool kullanın — bu araç, her istemcinin görüntüleyebileceği base64 kodlu bir PNG/JPEG döndürür.

CLIENT_NEEDS_RESOURCE_FALLBACK

Kaynak Yedek Araçları (Uyumlu Olmayan İstemciler için İsteğe Bağlı)

Kaynaklar, çoğu istemcinin (Claude Desktop, VS Code, MCP Inspector vb.) desteklediği temel bir MCP özelliğidir. Ancak bazı istemciler (smolagents gibi) kaynakları hiç desteklemez. Bu istemciler için sunucu, kaynaklarla aynı içeriği araç çağrıları üzerinden sunan “kaynak yedek araçları” sağlayabilir.

Yedek Araçlar:

• resource_reader_tool - URI ile herhangi bir kaynağı okumak için genel yedek araç
• category_list_tool - Kategori listesine erişim sağlar (mapbox://categories)

Bu araçlar varsayılan olarak dâhil DEĞİLDİR (istemcinizin kaynakları desteklediği varsayılır). İstemciniz kaynakları desteklemiyorsa yedek araçları etkinleştirin:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Bu ayarı ne zaman yapmalısınız:

• ✅ smolagents veya kaynak desteği olmayan başka istemciler kullanıyorsanız true olarak ayarlayın
• ❌ Claude Desktop, VS Code, MCP Inspector veya kaynakları destekleyen başka bir istemci kullanıyorsanız ayarı yapmayın (varsayılan)
• ❌ Emin değilseniz ayarı yapmayın (çoğu istemci kaynakları destekler)

Araçlar

Yardımcı Araçlar

Kaynak Okuyucu Aracı

Yerel MCP kaynak API’sini desteklemeyen istemciler için MCP kaynaklarına erişim sağlar. Kategori listesi gibi kaynakları okumak için bu aracı kullanın.

Parametreler:

• uri: Okunacak kaynak URI’si (ör. mapbox://categories, mapbox://categories/ja)

Örnek Kullanım:

• Varsayılan kategorileri oku: {"uri": "mapbox://categories"}
• Japonca kategorileri oku: {"uri": "mapbox://categories/ja"}

Not: MCP istemciniz yerel kaynakları destekliyorsa daha iyi performans için doğrudan kaynak API’sini kullanmayı tercih edin.

Çevrimdışı Coğrafi Araçlar

Bu araçlar, Mapbox API çağrısı gerektirmeden coğrafi hesaplamaları tamamen çevrimdışı gerçekleştirir. Doğru coğrafi hesaplamalar için Turf.js kullanırlar ve internet bağlantısı olmasa bile her yerde çalışırlar.

Mesafe Aracı

Haversine formülünü kullanarak iki coğrafi koordinat arasındaki mesafeyi hesaplar.

Özellikler:

• Birden fazla birimi destekler: kilometre, mil, metre, fit, deniz mili
• Büyük daire mesafesini doğru biçimde hesaplar
• API çağrısı gerektirmez

Örnek Kullanım: “San Francisco (37.7749°N, 122.4194°W) ile New York (40.7128°N, 74.0060°W) arasındaki mesafe nedir?”

Poligon İçindeki Noktalar Aracı

Bir veya daha fazla noktanın poligonun veya multipoligonun içinde olup olmadığını sınar ve yalnızca içeridekileri döndürür. Tek bir noktayı veya birden fazla noktayı tek çağrıda işler.

Özellikler:

• Delikler içeren karmaşık poligonlarla çalışır
• Çoklu poligonları destekler
• Tek bir çağrıda istenen sayıda noktayı toplu olarak test eder
• Coğrafi sınır belirleme, teslimat bölgesi doğrulama ve müşteri segmentasyonu için kullanışlıdır

Örnek Kullanım: "Bu teslimat adreslerinden hangileri hizmet alanımızın içinde?"

Hedef Aracı

Jeodezik (büyük daire) ofsetini kullanarak başlangıç noktası, kerteriz ve mesafe verildiğinde bir hedef noktası hesaplar.

Özellikler:

• Rota değil, düz çizgili ofset
• "X noktasının 5 km kuzeyinde bir nokta bulma" veya arama ofsetleri oluşturma için kullanışlıdır
• API çağrısı gerektirmez

Örnek Kullanım: "Space Needle'ın 10 km kuzeydoğusundaki nokta neresi?"

Kerteriz Aracı

Bir koordinattan diğerine pusula yönünü (kerterizi) hesaplar.

Özellikler:

• Kerterizi derece cinsinden döndürür (0-360°)
• Ana yönü belirtir (K, KD, D, GD, G, GB, B, KB)
• Navigasyon ve yön sorguları için kullanışlıdır

Örnek Kullanım: "Buradan havaalanına gitmek için hangi yöne ilerlemeliyim?"

Orta Nokta Aracı

Büyük daire rotası boyunca iki koordinat arasındaki coğrafi orta noktayı bulur.

Özellikler:

• Dünya'nın eğri yüzeyindeki gerçek orta noktayı hesaplar
• Buluşma noktası önerileri için kullanışlıdır
• Uzun mesafeli hesaplamaları doğru şekilde gerçekleştirir

Örnek Kullanım: "San Francisco ile New York'un tam ortası neresi?"

Ağırlık Merkezi Aracı

Bir poligonun veya çoklu poligonun geometrik merkezini (ağırlık merkezini) hesaplar.

Özellikler:

• Karmaşık şekillerle çalışır
• Tüm noktaların aritmetik ortalamasını döndürür
• Etiket veya işaretçi yerleştirmek için kullanışlıdır

Örnek Kullanım: "Bu mahalle sınırı için işaretçiyi nereye yerleştirmeliyim?"

Alan Aracı

Bir poligonun alanını hesaplar.

Özellikler:

• Birden fazla birimi destekler: metrekare, kilometrekare, akre, hektar, mil kare, fit kare
• Dünya yüzeyinde doğru alan hesaplaması
• Her boyuttaki poligonlarla çalışır

Örnek Kullanım: "Bu parkın akre cinsinden alanı nedir?"

Sınırlayıcı Kutu Aracı

Bir geometriyi kapsayan minimum sınırlayıcı kutuyu (bbox) hesaplar.

Özellikler:

• Noktalar, çizgiler, poligonlar ve çoklu poligonlarla çalışır
• [minLongitude, minLatitude, maxLongitude, maxLatitude] değerlerini döndürür
• Görünüm alanı hesaplamaları ve mekânsal indeksleme için kullanışlıdır

Örnek Kullanım: "Bu rotanın sınırlayıcı kutusu nedir?"

Tampon Aracı

Bir nokta, çizgi veya poligonun çevresinde tampon bölge (poligon) oluşturur.

Özellikler:

• Birden fazla mesafe birimini destekler
• Noktaların çevresinde dairesel tamponlar oluşturur
• Yakınlık analizi ve etki alanları oluşturmak için kullanışlıdır

Örnek Kullanım: "Bu konumun çevresinde 5 km'lik bir tampon bölge göster"

Basitleştirme Aracı

Douglas-Peucker algoritmasını kullanarak bir çizgi veya poligondaki köşe noktalarının sayısını azaltır.

Özellikler:

• Ayrıntı düzeyi için yapılandırılabilir tolerans
• Karmaşıklığı azaltırken genel şekli korur
• Dosya boyutlarını küçültmek ve görüntüleme performansını artırmak için kullanışlıdır
• Topolojiyi koruma seçeneği (kendi kendine kesişmeleri önleme)

Örnek Kullanım: "Nokta sayısını azaltmak için bu karmaşık sınırı basitleştir"

Uzunluk Aracı

Bir dizi koordinatla tanımlanan çizginin toplam uzunluğunu ölçer.

Özellikler:

• Kilometre, mil, metre ve fit birimlerini destekler
• Yönlendirme API'si çağrısı yapmadan çizilmiş bir rotayı, yolu veya sınırı ölçmek için kullanışlıdır

Örnek Kullanım: "Bu yürüyüş parkuru ne kadar uzun?"

Dışbükey Gövde Aracı

Bir nokta kümesinin dışbükey gövdesini, yani tüm noktaları içeren en küçük dışbükey poligonu hesaplar.

Özellikler:

• Sınırlayıcı alan analizi veya kapsama alanı tahmini için kullanışlıdır
• API çağrısı yapmadan çevrimdışı çalışır

Örnek Kullanım: "Bu mağaza konumlarının tümünü içeren en küçük poligon nedir?"

En Yakın Nokta Aracı

Bir hedef noktaya en yakın noktayı bir koleksiyon içinden bulur.

Özellikler:

• Her aday için distance_tool çağırıp sonuçları sıralamaktan daha verimlidir
• Bir konuma en yakın mağazayı, durağı veya önemli noktayı bulmak için kullanışlıdır

Örnek Kullanım: "Bu mağazalardan hangisi şu anki konumuma en yakın?"

Çizgi Üzerindeki En Yakın Nokta Aracı

Bir noktayı çizgi veya rota üzerindeki en yakın konuma oturtur ve bu noktayı, ayrıca ona olan mesafeyi döndürür.

Özellikler:

• "Bu rotanın hangi noktası konumuma en yakın?" sorguları veya API çağrısı yapmadan harita eşleştirme için kullanışlıdır

Örnek Kullanım: "Şu anda bu yürüyüş parkurunun hangi noktasına en yakınım?"

Birleştirme, Kesişim ve Fark Araçları

İki veya daha fazla poligonu birleştirir ya da karşılaştırır: union_tool bunları tek bir geometride birleştirir, intersect_tool ortak alanlarını bulur ve difference_tool birini diğerinden çıkarır.

Özellikler:

• Hizmet alanlarını birleştirmek, kapsama alanlarının kesişimini bulmak veya hariç tutma bölgeleri hesaplamak için kullanışlıdır (ör. "A bölgesinin kapsadığı ama B bölgesinin kapsamadığı alan neresi?")
• Tamamen çevrimdışı çalışır; API çağrısı gerektirmez
• Her biri, sonucun doğrudan görselleştirilebilmesi için bir render_map_tool referansı döndürür

Örnek Kullanım: "Bu iki teslimat bölgesini tek bir kapsama alanında birleştir" / "Bu iki eşzamanlı erişim alanı nerede kesişiyor?" / "Bu hizmet alanının hangi kısmı 15 dakikalık eşzamanlı erişim alanımızın dışında kalıyor?"

Mapbox API Araçları

Kategori Listesi Aracı (Kullanımdan Kaldırıldı)

⚠️ Kullanımdan kaldırıldı: Bunun yerine URI'si mapbox://categories olan resource_reader_tool aracını kullanın veya istemciniz MCP kaynaklarını destekliyorsa mapbox://categories kaynağına doğrudan erişin.

Bu araç, MCP kaynaklarını veya resource_reader_tool aracını desteklemeyen istemcilerle geriye dönük uyumluluk için korunmaktadır.

Matris Aracı

Mapbox Matrix API kullanarak birden fazla nokta arasındaki seyahat sürelerini ve mesafeleri hesaplar. Özellikler:

• Bire-çok, çok-bire veya çoktan-çoğa verimli rota hesaplamaları
• Farklı seyahat profillerini destekler (driving-traffic, driving, walking, cycling)
• Trafiği dikkate alan hesaplamalar için hareket saati belirtme
• Mesafe ve süre ölçümleriyle rota özeti
• Yaklaşım biçimini (curb/unrestricted) ve izin verilen hareket kerterizlerinin aralığını denetleme

Statik Görsel Aracı

Mapbox static image API kullanarak statik harita görselleri oluşturur. Özellikler:

• Özel harita stilleri (streets, outdoors, satellite vb.)
• Ayarlanabilir görsel boyutları ve yakınlaştırma düzeyleri
• Özel renk ve etiketlerle birden fazla işaretçi desteği
• Çizgiler ve poligonlar dahil kaplama seçenekleri
• Belirtilen koordinatlara otomatik sığdırma

Kategori Arama Aracı

Mapbox Search Box category search API kullanarak kategori araması yapar. Özellikler:

• İlgi çekici yerleri kategoriye göre arama (restoranlar, oteller, benzin istasyonları vb.)
• Coğrafi yakınlığa göre filtreleme
• Özelleştirilebilir sonuç sınırları
• Her sonuç için zengin meta veriler
• Birden fazla dil desteği

Ters Geocoding Aracı

Mapbox geocoding V6 API kullanarak ters geocoding yapar. Özellikler:

• Coğrafi koordinatları insanların okuyabileceği adreslere dönüştürme
• Özelleştirilebilir ayrıntı düzeyleri (sokak, mahalle, şehir vb.)
• Sonuçları türe göre filtreleme (adres, poi, mahalle vb.)
• Birden fazla dil desteği
• Zengin konum bağlamı bilgileri

Konum Bağlamı Aracı

Canlı Mapbox verilerini ve kaynak gösterimlerini kullanarak tek bir çağrıda "bu koordinatın yakınında neler var?" sorularını yanıtlar: yer adı, yakındaki ilgi çekici yerler ve seyahat süresiyle erişilebilirlik. Bunu, reverse_geocode_tool aracını web aramasıyla zincirlemek yerine kullanın.

Özellikler:

• Sorguyu sınıflandırır (rota oluşturma, mahalle bağlamı, ilgi çekici yer araması veya bölge/erişilebilirlik) ve yalnızca ilgili verileri getirir
• İstendiğinde kategoriye göre yakındaki ilgi çekici yerleri arar
• Seyahat süresiyle erişilebilirlik özeti (eşzamanlı erişim alanı tabanlı)
• Konumu ve haritada işaretlenmiş yakındaki ilgi çekici yerleri içeren bir render_map_tool referansı döndürür

Örnek Kullanım: "Bu koordinat hangi mahallede ve yakınlarda kahve dükkânı var mı?"

Yer Ayrıntıları Aracı

Mapbox kimliğini kullanarak belirli bir yer hakkında ayrıntılı bilgi getirir: fotoğraflar, çalışma saatleri, puanlar, telefon numaraları ve web sitesi URL'leri. Belirli bir sonuç hakkında daha fazla bilgi almak için search_and_geocode_tool, category_search_tool veya reverse_geocode_tool sonrasında kullanın.

Örnek Kullanım: "İlk kahve dükkânı sonucu hakkında daha fazla bilgi ver — çalışma saatleri, telefon numarası ve web sitesi"

Yol Tarifi Aracı

Mapbox Directions API kullanarak rota yönergelerini getirir. Özellikler:

• Farklı rota profillerini destekler: sürüş (canlı trafik veya tipik trafikle), yürüme ve bisiklet
• Birden fazla ara noktadan rota oluşturma (2-25 koordinat çifti)
• Alternatif rota seçeneği
• Rota açıklamaları (mesafe, süre, hız, trafik yoğunluğu)
• Zamanlama seçenekleri:
  • Sürüş ve driving-traffic profilleri için gelecekteki hareket saati (depart_at)
  • Yalnızca sürüş profili için istenen varış saati (arrive_by)
• Profile özgü optimizasyonlar:
  • Sürüş: araç boyutu kısıtlamaları (yükseklik, genişlik, ağırlık)
• Rota oluşturma için hariç tutma seçenekleri:
  • Yaygın hariç tutmalar: feribot rotaları, yalnızca nakit kabul eden ücretli yollar
  • Sürüşe özgü hariç tutmalar: ücretli yollar, otoyollar, asfaltlanmamış yollar, tüneller, ülke sınırları, eyalet sınırları
  • Özel nokta hariç tutmaları (kaçınılacak en fazla 50 coğrafi nokta)
• GeoJSON geometri çıktı biçimi

Eşzamanlı Erişim Alanı Aracı

Mapbox Isochrone API kullanarak bir konumdan belirli bir süre içinde erişilebilen alanları hesaplar. Özellikler:

• Farklı seyahat profillerini destekler (sürüş, yürüme, bisiklet)
• Özelleştirilebilir seyahat süreleri veya mesafeleri
• Birden fazla eşzamanlı erişim alanı oluşturma (ör. 15, 30, 45 dakikalık aralıklar)
• İsteğe bağlı hareket veya varış saati belirtme
• Görselleştirme için renk özelleştirme

Arama ve Geocoding Aracı

POI'leri, adresleri, yerleri ve bu API'nin desteklediği diğer türleri aramak ve geocoding işlemlerini yapmak için Mapbox Search Box Text Search API uç noktasını kullanır. Bu araç, daha önce bu MCP sunucusunun önceki sürümlerindeki ForwardGeocodeTool ve PoiSearchTool tarafından sağlanan işlevleri tek bir araçta birleştirir.

Harita Eşleştirme Aracı

Mapbox Map Matching API kullanarak GPS izlerini yol ağına oturtur. Özellikler:

• Gürültülü GPS izlerini yol ağı üzerindeki temiz rotalara dönüştürme
• Farklı seyahat profillerini destekler (driving, driving-traffic, walking, cycling)
• İstek başına en fazla 100 koordinat çiftini işleme
• Hıza dayalı doğruluğu artırmak için isteğe bağlı zaman damgaları
• Farklı GPS kalite düzeyleri için yapılandırılabilir oturtma yarıçapları
• Rota açıklamaları (hız sınırları, mesafe, süre, trafik yoğunluğu)
• Birden fazla geometri çıktı biçimi (GeoJSON, polyline)

Örnek Kullanım: "Bu GPS izini temizleyip yollara oturt: [zaman damgalarıyla koordinatlar]"

Optimizasyon Aracı

Mapbox Optimization API kullanarak birden fazla konumdan geçen en uygun rotayı bulur. Özellikler:

• 2-12 konum için gezgin satıcı problemini (TSP) çözer
• Farklı seyahat profillerini destekler (driving, driving-traffic, walking, cycling)
• Esnek başlangıç ve bitiş noktası yapılandırması
• Gidiş-dönüş veya tek yönlü rota optimizasyonu
• Dönüş dönüş navigasyon yönergeleri (isteğe bağlı)
• Rota açıklamaları (mesafe, süre, hız)
• Birden fazla geometri çıktı biçimi (GeoJSON, polyline)

Örnek Kullanım: "Şu 5 durağı ziyaret etmek için en uygun rotayı bul: [adres veya koordinat listesi]"

Not: Gelişmiş özelliklere (zaman aralıkları, kapasite kısıtlamaları, birden fazla araç) sahip bir V2 API mevcuttur ancak beta erişimi gerektirir. V2 uygulaması kod tabanına dahildir ancak varsayılan olarak kaydedilmez.

Geri Bildirim Aracı

Kullanıcının uygulama veya aracı hakkındaki geri bildirimini Mapbox Feedback API (Public Preview) aracılığıyla geliştiricisine gönderir. Geri bildirim, erişim belirtecinin sahibi olan hesap altında kaydedilir. Bu nedenle, kendi belirtecinizle bu sunucuda bir uygulama veya araç oluşturduğunuzda kullanıcılarınızın geri bildirimleri, uygulamalarınızın Feedback Agent raporlarıyla aynı akışa düşer ve bunları Feedback Explorer'da inceleyebilirsiniz. Mapbox'a sorun bildirmez. Feedback Agent gibi, kullanıcıların ihtiyaçlarını anlamanıza yardımcı olacak ürününüzle ilgili her türlü geri bildirim içindir; örneğin:

• Kapanmış, bilgileri yanlış olan veya yanlış konumda bulunan bir yer
• Bulunamayan bir yer veya adres
• Kapalı bir yol, yanlış bir hız sınırı veya yanlış gösterilen trafik
• Yasa dışı bir dönüşü ya da girişi olan veya hiç rota bulunmayan bir rota
• Uygulamanın kendisiyle ilgili bir sorun; örneğin bir hata veya öneri (application_issue)

Geri bildirim metnini, kategoriyi ve konumu gönderir; öğenin kimliğini ve durumunu döndürür. Yerle ilgili olmayan geri bildirimlerde konum isteğe bağlıdır; ancak API konum gerektirdiğinden araç, Feedback API ekibinin şimdilik önerdiği şekilde 0, 0 gönderir. Kullanıcı onay vermeden hiçbir şey gönderilmez: elicitation özelliğini destekleyen istemciler önce bir onay istemi gösterir; diğer tüm durumlarda araç açıklaması modelden sohbet içinde onay almasını ister.

Feedback API, Public Preview süresince ücretsizdir. General Availability aşamasında Feedback Agent, her geri bildirim öğesi için $0.02 ücret alır. Aynı sorunun iki kez bildirilmesini önlemek için araç, göndermeden önce hesabın son 30 gündeki kendi bildirimlerini kontrol eder. Aynı kategoride ve 50 m içindeki bir bildirim hâlâ incelenmeyi bekliyorsa (konum içermeyen geri bildirimler kontrol edilmez), yeni bir bildirim göndermek yerine mevcut bildirimi döndürür. Feedback API yalnızca hesabın kendi bildirimlerini listeler; bu nedenle diğer hesapların bildirimlerini yakalayamaz. Kullanıcı bunun farklı bir sorun olduğunu söylediğinde send_anyway: true kontrolü atlar.

Gereksinimler: Gönderim için erişim belirtecinin user-feedback:write kapsamına, yinelenen bildirim kontrolü içinse user-feedback:read kapsamına ihtiyacı vardır. Yazma kapsamı yoksa araç bunu belirten bir hata döndürür. Okuma kapsamı yoksa kontrol etmeden gönderir ve sonucunda bunu belirtir. Aracı devre dışı bırakmak için sunucuyu --disable-tools feedback_tool ile başlatın.

Kullanım Örneği: "Mint St'deki Blue Bottle geçen yıl kapandı, bunu geri bildirim olarak gönderebilir misin?"

Report aracı

Mapbox MCP sunucusunun kendisiyle ilgili bir hatayı, yanlış veya kafa karıştırıcı sonuç veren bir aracı, eksik bir özelliği ya da öneriyi, sunucuyu geliştiren Mapbox ekibine gönderir. Bildirim sizin hesabınızdan değil, Mapbox'ın kendi hesabından yapılır; bu nedenle ek bir belirteç kapsamı gerekmez. Bildirim daha sonra okunamaz veya geri çekilemez. Yanlış harita, yer veya rota verilerini bildirmek için kullanılmaz.

Sunucu, metnin sonuna kendi sürümünü, istemcinin adını ve sürümünü ve geri bildirimin ilgili olduğu aracı ekler. Kullanıcı onay vermeden hiçbir şey gönderilmez: elicitation özelliğini destekleyen istemciler önce bir onay istemi gösterir; diğer tüm durumlarda araç açıklaması modelden sohbet içinde onay almasını ister.

Feedback API ekibinin Mapbox CLI için eklediği mapbox report komutunun kullandığı uç noktayı kullanır. Aracı devre dışı bırakmak için sunucuyu --disable-tools report_tool ile başlatın.

Kullanım Örneği: "Harita izokronlarımın hiçbirini çizmedi. Mapbox MCP ekibine haber verebilir misin?"

List public tokens aracı

Sohbet dışında Mapbox GL JS yükleyen veya tarayıcıdan Mapbox API'lerini çağıran bir web sayfası ya da uygulama geliştiren bir aracı için hesabın herkese açık (pk.) erişim belirteçlerini listeler. Sohbet içindeki render_map_tool için belirteç gerekmez. Her belirteçle birlikte adı, varsayılan olup olmadığı, URL kısıtlamaları ve kapsamları verilir.

site_url değerini (sayfanın çalışacağı yer) iletin; hesapta bu URL ile kısıtlanmış bir belirteç varsa araç onu önerir. Aksi takdirde varsayılan herkese açık belirteci önerir ve yayımlanmış bir sitenin bunun yerine URL kısıtlamalı bir belirteç kullanması gerektiğini belirtip böyle bir belirteç oluşturma bağlantısı verir. Kısıtlanmamış herkese açık bir belirteci kopyalayan herkes onu kullanabilir ve kullanım ücretleri hesaba yansır.

Gizli veya geçici belirteçleri hiçbir zaman döndürmez ve belirteç oluşturamaz (bunun için tokens:write gerekir; DevKit server içindeki create_token_tool bunu yapar).

Gereksinimler: Listeleme için, sohbet içi haritanın varsayılan herkese açık belirteci bulmak üzere kullandığı kapsamla aynı olan tokens:read kapsamı gerekir. pk. erişim belirteci kullanıldığında veya sunucunun kendi MAPBOX_ACCESS_TOKEN değeriyle listeleme başarısız olduğunda ve MAPBOX_PUBLIC_TOKEN ayarlandığında, bunun yerine o belirteci döndürür. Kendi bearer belirtecini kullanan bir çağıran (barındırılan sunucu) hiçbir zaman MAPBOX_PUBLIC_TOKEN almaz ve başka URL'lerle kısıtlanmış bir belirteç hiçbir zaman önerilmez. Aracı devre dışı bırakmak için sunucuyu --disable-tools list_public_tokens_tool ile başlatın.

Kullanım Örneği: "Mapbox haritasında üç mağazamızın konumlarını gösteren tek sayfalık bir site oluştur."

Geliştirme

Sunucuyu inceleme

Node.js kullanarak

# Run the built image
npm run inspect:build

Docker kullanarak

# 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

Yeni araç oluşturma

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

Yeni bir sürüm yayımlama

# 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

Önemli: Yayıncı iş akışı, package.json ve server.json sürümlerinin yayın sürümüyle eşleştiğini doğrular. Sürüm numarasını artırmayı veya manifest eşitlemesini atlamak, yayınlama hatalarına neden olur.

OpenTelemetry izleme

Bu MCP sunucusu, üretim ortamında gözlemlenebilirlik için kapsamlı OpenTelemetry izleme içerir:

Hızlı demo

# 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

Not: Sunucu, başlangıçta yapılandırmayı .env dosyanızdan otomatik olarak yükler. .env.example dosyasında birden fazla gözlemlenebilirlik platformu için yapılandırma örnekleri bulunur.

Desteklenen gözlemlenebilirlik platformları

Aşağıdakiler için yapılandırma örnekleri .env.example içinde bulunur:

Bulut sağlayıcıları:

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

SaaS platformları:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 OTLP uyumlu tüm arka uçlar

Üretim yapılandırması

Kurulumla ilgili tüm talimatlar için docs/tracing.md dosyasına bakın. Bu talimatlar şunları içerir:

• 🔧 Platforma özel yapılandırma kılavuzları
• 📊 Kimlik doğrulama ve uç nokta kurulumu
• 🎯 Özel izleme öznitelikleri ve bağlamı
• 🚀 Performans optimizasyonu (minimum ek yük)
• 🔍 Sorun giderme ve hata ayıklama

İzleme özellikleri:

• ✅ Yapılandırma yükleme izlemesi (.env dosyası yükleme)
• ✅ Araç yürütmesinin otomatik izlenmesi
• ✅ CloudFront korelasyon kimlikleriyle HTTP isteklerinin enstrümantasyonu
• ✅ Yapılandırılabilir dışa aktarıcılar (console, OTLP)
• ✅ Güvenlik odaklı (veri koruması, JWT doğrulaması)
• ✅ Üretime hazır (CPU ek yükü <%1)

Katkıda bulunma

Mapbox MCP Server'a katkılarınızı bekliyoruz! Pull request göndermeden önce lütfen CONTRIBUTING.md dosyasını okuyun.

Standartların ve yönergelerin tamamı:

• CONTRIBUTING.md - Başlangıç, PR süreci, hızlı başvuru
• Engineering Standards (docs/engineering_standards.md) - Kod kalitesi, test, belgelendirme ve iş birliği standartlarının tamamı
• Claude Code Guide (CLAUDE.md) - Claude Code kullanan katkıda bulunanlar için standartlar ve kalıplar
• AI Agent Instructions (AGENTS.md) - Diğer yapay zekâ kodlama asistanları (Cursor, Continue, Aider vb.) için kılavuz
• GitHub Copilot Guidelines - GitHub Copilot'ı sorumlu biçimde kullanmaya yönelik en iyi uygulamalar

Katkıda bulunanlar için hızlı başlangıç

1. Depoyu çatallayın ve kendi çatalladığınız depoyu klonlayın
2. Bağımlılıkları yükleyin: npm install
3. Kodlama standartlarımıza uyarak değişikliklerinizi yapın
4. Testleri ve lint denetimlerini çalıştırın: npm test && npm run lint
5. Yeni işlevler için test ekleyin
6. Açık ve anlaşılır bir açıklamayla pull request gönderin

Tüm katkılar CI denetimlerimizden ve kod inceleme sürecimizden geçmelidir. Ayrıntılı gereksinimler için docs/engineering_standards.md dosyasına bakın.

Veri kullanımı ve gizlilik

Mapbox API'lerine gönderilen veriler

MCP sunucusu araçlarını kullandığınızda aşağıdaki veriler ortamınızdan doğrudan Mapbox API'lerine gönderilir:

• Geocoding araçları: Adres/konum metni, koordinatlar, ülke/bölge filtreleri
• Search araçları: Arama sorguları, yakınlık için konum koordinatları, kategori filtreleri
• Directions aracı: Başlangıç/bitiş koordinatları, ara noktalar, rota tercihleri, araç kısıtlamaları
• Matrix aracı: Birden fazla koordinat çifti, seyahat profili, hareket saatleri
• Static map aracı: Koordinatlar, yakınlaştırma düzeyi, stil tercihleri, işaretçi bilgileri
• Isochrone aracı: Başlangıç koordinatları, süre/mesafe parametreleri, seyahat profili

Gizliliğiniz

• Yerel yürütme: Tüm API çağrıları ortamınızdan doğrudan Mapbox API'lerine yapılır
• Belirteç güvenliği: Mapbox API belirteciniz yerel makinenizde kalır ve bu MCP sunucusuna hiçbir zaman iletilmez veya sunucu tarafından saklanmaz
• Veri depolama yok: Bu MCP sunucusu verilerinizi veya API isteklerinizi saklamaz, günlüğe kaydetmez ya da toplamaz
• Doğrudan iletişim: Sizinle Mapbox API'leri arasında aracı bir sunucu yoktur

Üçüncü taraf veri kullanımı

• Mapbox'ın gizlilik politikası, API'lerine gönderilen verileri düzenler: https://www.mapbox.com/legal/privacy/
• API kullanımı: Bu araçlar üzerinden yapılan tüm isteklerde standart Mapbox API koşulları geçerlidir
• Veri saklama: Mapbox'ın veri saklama politikaları için belgelerine bakın

Destek ve iletişim

MCP sunucusu sorunları için

• E-posta: mcp-feedback@mapbox.com
• GitHub Issues: Hataları ve özellik isteklerini bildirin

Mapbox API soruları için

• Mapbox Support: https://support.mapbox.com/
• Belgeler: https://docs.mapbox.com/
• API durumu: https://status.mapbox.com/

Bakım taahhüdü

Bu MCP sunucusunun resmi bakımını Mapbox, Inc. üstlenir. Şunları sağlıyoruz:

• Yeni Mapbox API özellikleri için düzenli güncellemeler
• Hata düzeltmeleri ve güvenlik güncellemeleri
• En yeni MCP protokolü sürümleriyle uyumluluk
• GitHub sorunları üzerinden topluluk desteği

---

MIT License