Mapbox

Mapbox MCP Server

Node.js-Server, der das Model Context Protocol (MCP) für Mapbox-APIs implementiert.

Erschließen Sie geospatiale Intelligenz für Ihre KI-Anwendungen

Der Mapbox MCP Server verwandelt jeden KI-Agenten oder jede Anwendung in ein geospatial bewusstes System, indem er nahtlosen Zugriff auf die umfassende Standort-Intelligenz-Plattform von Mapbox bietet. Mit diesem Server kann Ihre KI Orte verstehen und darüber nachdenken, sich in der physischen Welt zurechtfinden und auf umfangreiche geospatiale Daten zugreifen, darunter:

• Globale Geokodierung zur Umwandlung von Adressen und Ortsnamen in Koordinaten und umgekehrt
• Points of Interest (POI)-Suche in Millionen von Unternehmen, Sehenswürdigkeiten und Orten weltweit
• Multimodale Routenführung für Autofahrten, Fußwege und Radtouren mit Echtzeit-Verkehrsdaten
• Reisezeit-Matrizen zur Analyse von Erreichbarkeit und Optimierung der Logistik
• Routenoptimierung zur Ermittlung der optimalen Besuchsreihenfolge für mehrere Stopps (Problem des Handlungsreisenden)
• Kartenabgleich zum Andocken von GPS-Spuren an das Straßennetz für eine saubere Routenvisualisierung
• Isochronen-Erzeugung zur Visualisierung von Bereichen, die innerhalb bestimmter Zeit- oder Distanzvorgaben erreichbar sind
• Live, interaktive Kartendarstellung (render_map_tool) zur Anzeige von Routen, Suchergebnissen und Ihren eigenen benutzerdefinierten GeoJSON-Daten auf einer echten Mapbox GL JS Karte direkt im Chat
• Statische Kartenbilder zur Erstellung visueller Darstellungen von Orten, Routen und geografischen Daten
• Offline-geospatiale Berechnungen für Distanz, Fläche, Peilung, Puffer und räumliche Analysen ohne API-Aufrufe

Ob Sie einen KI-Reiseassistenten, einen Logistik-Optimierer, einen standortbasierten Empfehlungsdienst oder eine beliebige Anwendung entwickeln, die „wo" verstehen muss – der Mapbox MCP Server bietet die räumliche Intelligenz, um dies zu ermöglichen. Sie können ihn auch auf gängigen Clients wie Claude Desktop und VS Code aktivieren. Details finden Sie unten.

Verwendung

Für die Nutzung dieses MCP-Servers ist ein Mapbox-Zugriffstoken erforderlich.

Gehosteter MCP-Endpunkt

Für den schnellen Zugriff können Sie unseren gehosteten MCP-Endpunkt verwenden:

Endpunkt: https://mcp.mapbox.com/mcp

Detaillierte Einrichtungsanweisungen für verschiedene Clients und die API-Nutzung finden Sie im Hosted MCP Server Guide.

So erhalten Sie ein Mapbox-Zugriffstoken:

1. Registrieren Sie sich für ein kostenloses Mapbox-Konto unter mapbox.com/signup
2. Navigieren Sie zu Ihrer Kontoseite
3. Erstellen Sie ein neues Token oder verwenden Sie das standardmäßige öffentliche Token

Weitere Informationen zu Mapbox-Zugriffstokens finden Sie in der Mapbox-Dokumentation zu Zugriffstokens.

Integrationsanleitungen

Detaillierte Einrichtungsanweisungen für verschiedene Integrationen finden Sie in den folgenden Anleitungen:

• Claude Desktop Setup – Anweisungen zur Konfiguration von Claude Desktop für die Arbeit mit diesem MCP-Server
• Goose Setup – Einrichtung des Goose-KI-Agenten-Frameworks
• VS Code Setup – Einrichtung einer Entwicklungsumgebung in Visual Studio Code
• Cursor AI IDE Setup – Einrichtung einer Entwicklungsumgebung in der Cursor AI IDE
• Smolagents-Integration – Beispiel, das zeigt, wie Smolagents-KI-Agenten mit den Mapbox-Tools verbunden werden
• Direktes Importieren von Tools – Verwenden Sie Mapbox-Tools in Ihren eigenen Anwendungen, ohne den MCP-Server auszuführen
• render_map_tool-Anleitung – Das Kartenvisualisierungs-Primitiv: vollständiges Payload-Schema und wie Sie Ihre eigenen Daten eigenständig rendern, ohne ein anderes Mapbox-Tool
• Elicitations – Wie search_and_geocode_tool und directions_tool den Benutzer bitten, Ergebnisse zu unterscheiden oder eine Route auszuwählen, und wie sie elegant zurückfallen, wenn der Client dies nicht unterstützt

Beispiel-Prompts

Probieren Sie diese Prompts nach der Einrichtung mit Claude Desktop oder anderen MCP-Clients aus:

Standortverankerung

Für koordinatenbasierte Abfragen – „Was ist in meiner Nähe", „In welchem Viertel ist das", „Was ist in N Minuten erreichbar" – verwenden Sie ground_location_tool. Es kombiniert Reverse-Geokodierung, Kategoriesuche und Isochrone in einem einzigen Aufruf, wählt adaptiv die richtige Strategie basierend auf der Abfrage und gibt typisierte Datensätze (Namen, Adressen, Koordinaten, Distanzen, Erreichbarkeits-Polygone) mit Zitaten zurück.

Jeder der vier folgenden Prompts übt eine andere Strategie in einem Tool-Aufruf aus:

• Nachbarschaft – „In welchem Viertel liegt 47.6097, -122.3408, und was ist in meiner Nähe?"
• POI – „Cafés in 10 Gehminuten von 40.7580, -73.9855"
• Region – „Was kann ich in 15 Gehminuten von 37.7749, -122.4194 erreichen?"
• Routenführung – „Nächster befahrbarer Punkt, um jemanden bei 34.0522, -118.2437 abzusetzen"

Standortsuche

• „Finde Cafés in Gehweite vom Empire State Building"
• „Ich möchte von Seattle nach Portland, gibt es unterwegs einen Starbucks?"
• „Zeig mir Tankstellen entlang der Route von Boston nach New York"
• „Welche Restaurants gibt es in der Nähe des Times Square?"

Navigation & Reisen

• „Gib mir Fahrtrouten von LAX nach Hollywood mit aktuellem Verkehr"
• „Wie lange würde ich vom Central Park zum Times Square laufen?"
• „Berechne die Reisezeit von meinem Hotel (Four Seasons) zum JFK-Flughafen mit dem Taxi während der Stoßzeit"

Visualisierung & Karten

• „Zeig mir mit dem Mapbox-Karten-Render-Tool die Route von der Golden Gate Bridge zum Union Square in San Francisco" – rendert eine Live-, interaktive Route auf einer echten Mapbox-Karte
• „Erstelle ein Kartenbild, das die Route von der Golden Gate Bridge zum Fisherman's Wharf mit Markierungen an beiden Orten zeigt"
• „Zeig mir eine Satellitenansicht von Manhattan mit markierten wichtigen Sehenswürdigkeiten"
• „Generiere eine Karte, die alle Starbucks-Standorte innerhalb einer Meile um die Innenstadt von Seattle hervorhebt"
• „Zeige ein Füll-Polygon über diesen Koordinaten: [...], mit einer Markierung mit der Beschriftung 'Lager' bei [...]" – rendert Ihre eigenen GeoJSON-Daten direkt über render_map_tool, kein anderes Mapbox-Tool erforderlich

Analyse & Planung

• „Zeig mir Bereiche, die innerhalb von 30 Minuten mit dem Auto von der Innenstadt von Portland erreichbar sind"
• „Berechne eine Reisezeit-Matrix zwischen diesen 3 Hotelstandorten (Marriott, Sheraton und Hilton) und dem Kongresszentrum in Denver"
• „Finde die optimale Route, die diese 3 Touristenattraktionen (Golden Gate, Musical Stairs und Fisherman's Wharf) in San Francisco besucht"
• „Optimiere eine Lieferroute für diese 8 Adressen: [Liste der Adressen]"

GPS & Routenabgleich

• „Bereinige diese GPS-Spur und zeige die tatsächliche Route auf Straßen: [Liste der Koordinaten mit Zeitstempeln]"
• „Docke diese aufgezeichnete Fahrradtour an das Radwegenetz an: [GPS-Koordinaten]"
• „Gleiche diese Fahrroute mit dem Straßennetz ab und zeige die Verkehrsstauungsgrade"

Offline-geospatiale Berechnungen

• „Wie groß ist die Entfernung in Meilen zwischen diesen beiden Koordinaten?"
• „Berechne die Fläche dieses Polygons in Quadratkilometern"
• „Liegt der Punkt bei 37.7749°N, 122.4194°W innerhalb dieses Servicebereich-Polygons?"
• „Wie ist die Peilung von San Francisco nach New York?"
• „Finde den Mittelpunkt zwischen London und Paris"
• „Erstelle eine Pufferzone von 5 Meilen um diesen Ort"
• „Berechne den Schwerpunkt dieser Nachbarschaftsgrenze"
• „Was ist der Begrenzungsrahmen für diese Routenkoordinaten?"
• „Vereinfache dieses komplexe Polygon, um die Anzahl der Punkte zu reduzieren"

Tipps für bessere Ergebnisse

• Seien Sie spezifisch bei Orten (verwenden Sie vollständige Adressen oder Sehenswürdigkeitsnamen)
• Geben Sie Ihre bevorzugte Reisemethode an (Autofahren, Gehen, Radfahren)
• Fügen Sie bei Bedarf Zeitbeschränkungen hinzu („während der Stoßzeit", „um 15 Uhr")
• Fragen Sie bei Bedarf nach bestimmten Ausgabeformaten („als Kartenbild", „im JSON-Format")

Detaillierte Beispiele: Siehe examples/search-along-route.md für umfassende Beispiele des search-along-route-Prompts mit verschiedenen Anwendungsfällen und Testanweisungen für den MCP Inspector.

Ressourcen

Der MCP-Server stellt statische Referenzdaten als MCP-Ressourcen bereit. Ressourcen bieten schreibgeschützten Zugriff auf Daten, auf die Clients direkt verweisen können, ohne Tool-Aufrufe durchzuführen.

Verfügbare Ressourcen

Mapbox-Kategorien-Ressource

URI-Muster: mapbox://categories oder mapbox://categories/{language}

Greifen Sie auf die vollständige Liste der verfügbaren Kategorie-IDs für die Verwendung mit dem Kategoriesuch-Tool zu. Kategorien können verwendet werden, um Suchergebnisse nach Typ zu filtern (z. B. „restaurant", „hotel", „gas_station").

Beispiele:

• mapbox://categories – Standardmäßige (englische) Kategorienliste
• mapbox://categories/ja – Japanische Kategoriennamen
• mapbox://categories/es – Spanische Kategoriennamen

Zugriff auf Ressourcen:

• Clients mit nativer MCP-Ressourcenunterstützung: Verwenden Sie die resources/read MCP-Protokollmethode
• Clients ohne Ressourcenunterstützung: Verwenden Sie resource_reader_tool mit der Ressourcen-URI

Umfangreiche Kartenvorschauen (render_map_tool)

Jedes geospatiale Tool auf diesem Server (Routenführung, Isochrone, Suche und mehr) kann sein Ergebnis als Live-, interaktive Mapbox GL JS Karte über render_map_tool anzeigen – das einzige Visualisierungs-Primitiv des Servers. Es rendert über das MCP Apps-Protokoll (@modelcontextprotocol/ext-apps) als eigenständiges HTML-Panel direkt im Chat, mit einem Vollbild-Umschalter, in unterstützten Clients:

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

Sie benötigen keines der anderen Tools dieses Servers, um es zu verwenden. render_map_tool akzeptiert auch direkt handkomponierte GeoJSON-Daten – Ihre eigenen Polygone, Markierungen und Routen – ohne Abhängigkeit von directions_tool, isochrone_tool oder einem anderen Mapbox-API-Aufruf. Siehe die vollständige render_map_tool-Anleitung für das Payload-Schema und ein vollständiges eigenständiges Beispiel.

Wenn Sie ein garantiert statisches Bild in Clients ohne MCP Apps-Unterstützung benötigen, verwenden Sie stattdessen static_map_image_tool – es gibt ein base64-kodiertes PNG/JPEG zurück, das jeder Client anzeigen kann.

CLIENT_NEEDS_RESOURCE_FALLBACK

Ressourcen-Fallback-Tools (Opt-In für nicht konforme Clients)

Ressourcen sind ein Kernmerkmal von MCP, das von den meisten Clients unterstützt wird (Claude Desktop, VS Code, MCP Inspector usw.). Einige Clients (wie smolagents) unterstützen Ressourcen jedoch überhaupt nicht. Für diese Clients kann der Server „Ressourcen-Fallback-Tools" bereitstellen, die denselben Inhalt wie Ressourcen, aber über Tool-Aufrufe liefern.

Fallback-Tools:

• resource_reader_tool – Generischer Fallback zum Lesen beliebiger Ressourcen per URI
• category_list_tool – Bietet Zugriff auf die Kategorienliste (mapbox://categories)

Standardmäßig sind diese Tools NICHT enthalten (es wird angenommen, dass Ihr Client Ressourcen unterstützt). Wenn Ihr Client keine Ressourcen unterstützt, aktivieren Sie die Fallback-Tools:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Wann Sie dies festlegen sollten:

• ✅ Auf true setzen, wenn Sie smolagents oder andere Clients ohne Ressourcenunterstützung verwenden
• ❌ Nicht gesetzt lassen (Standard), wenn Sie Claude Desktop, VS Code, MCP Inspector oder einen anderen ressourcenfähigen Client verwenden
• ❌ Nicht gesetzt lassen, wenn Sie unsicher sind (die meisten Clients unterstützen Ressourcen)

Tools

Dienstprogramm-Tools

Ressourcenleser-Tool

Bietet Zugriff auf MCP-Ressourcen für Clients, die die native MCP-Ressourcen-API nicht unterstützen. Verwenden Sie dieses Tool, um Ressourcen wie die Kategorienliste zu lesen.

Parameter:

• uri: Die zu lesende Ressourcen-URI (z. B. mapbox://categories, mapbox://categories/ja)

Beispielverwendung:

• Standardkategorien lesen: {"uri": "mapbox://categories"}
• Japanische Kategorien lesen: {"uri": "mapbox://categories/ja"}

Hinweis: Wenn Ihr MCP-Client native Ressourcen unterstützt, bevorzugen Sie die direkte Verwendung der Ressourcen-API für bessere Leistung.

Offline-geospatiale Tools

Diese Tools führen geospatiale Berechnungen vollständig offline durch, ohne Mapbox-API-Aufrufe zu erfordern. Sie verwenden Turf.js für genaue geografische Berechnungen und funktionieren überall, sogar ohne Internetverbindung.

Distanz-Tool

Berechnet die Distanz zwischen zwei geografischen Koordinaten mithilfe der Haversine-Formel.

Funktionen:

• Unterstützt mehrere Einheiten: Kilometer, Meilen, Meter, Fuß, Seemeilen
• Genaue Großkreis-Distanzberechnung
• Keine API-Aufrufe erforderlich

Beispielverwendung: „Wie groß ist die Distanz zwischen San Francisco (37.7749°N, 122.4194°W) und New York (40.7128°N, 74.0060°W)?"

Punkte-im-Polygon-Tool

Testet einen oder mehrere Punkte gegen ein Polygon oder Multipolygon und gibt nur diejenigen zurück, die sich darin befinden. Verarbeitet einen einzelnen Punkt oder eine Stapelverarbeitung in einem Aufruf.

Funktionen:

• Funktioniert mit komplexen Polygonen, einschließlich Löchern
• Unterstützt Multipolygone
• Testet beliebig viele Punkte in einem einzigen Aufruf
• Nützlich für Geofencing, Validierung von Lieferzonen und Kundensegmentierung

Beispielverwendung: „Welche dieser Lieferadressen liegen in unserem Servicebereich?“

Zielpunkt-Tool

Berechnet einen Zielpunkt aus einem Startpunkt, Kurs und Entfernung mithilfe des geodätischen (Großkreis-)Versatzes.

Funktionen:

• Geradliniger Versatz, keine geroutete Strecke
• Nützlich für „Finde einen Punkt 5 km nördlich von X“ oder zum Erstellen von Suchversätzen
• Keine API-Aufrufe erforderlich

Beispielverwendung: „Was ist der Punkt 10 km nordöstlich der Space Needle?“

Kurs-Tool

Berechnet die Kompassrichtung (Kurs) von einer Koordinate zu einer anderen.

Funktionen:

• Gibt den Kurs in Grad zurück (0–360°)
• Liefert die Himmelsrichtung (N, NO, O, SO, S, SW, W, NW)
• Nützlich für Navigation und Richtungsabfragen

Beispielverwendung: „In welche Richtung muss ich gehen, um von hier zum Flughafen zu gelangen?“

Mittelpunkt-Tool

Findet den geografischen Mittelpunkt zwischen zwei Koordinaten entlang des Großkreiswegs.

Funktionen:

• Berechnet den echten Mittelpunkt auf der gekrümmten Erdoberfläche
• Nützlich für Treffpunktvorschläge
• Behandelt Langstreckenberechnungen korrekt

Beispielverwendung: „Was liegt auf halbem Weg zwischen San Francisco und New York?“

Schwerpunkt-Tool

Berechnet den geometrischen Mittelpunkt (Schwerpunkt) eines Polygons oder Multipolygons.

Funktionen:

• Funktioniert mit komplexen Formen
• Gibt das arithmetische Mittel aller Punkte zurück
• Nützlich zum Platzieren von Beschriftungen oder Markierungen

Beispielverwendung: „Wo soll ich eine Markierung für diese Nachbarschaftsgrenze platzieren?“

Flächen-Tool

Berechnet die Fläche eines Polygons.

Funktionen:

• Unterstützt mehrere Einheiten: Quadratmeter, Quadratkilometer, Acres, Hektar, Quadratmeilen, Quadratfuß
• Genaue Flächenberechnung auf der Erdoberfläche
• Funktioniert mit Polygonen beliebiger Größe

Beispielverwendung: „Wie groß ist die Fläche dieses Parks in Acres?“

Begrenzungsrahmen-Tool

Berechnet den minimalen Begrenzungsrahmen (bbox), der eine Geometrie enthält.

Funktionen:

• Funktioniert mit Punkten, Linien, Polygonen und Multipolygonen
• Gibt [minLängengrad, minBreitengrad, maxLängengrad, maxBreitengrad] zurück
• Nützlich für Viewport-Berechnungen und räumliche Indizierung

Beispielverwendung: „Was ist der Begrenzungsrahmen für diese Route?“

Puffer-Tool

Erstellt eine Pufferzone (Polygon) um einen Punkt, eine Linie oder ein Polygon.

Funktionen:

• Unterstützt mehrere Entfernungseinheiten
• Erstellt kreisförmige Puffer um Punkte
• Nützlich für Näherungsanalysen und das Erstellen von Einflusszonen

Beispielverwendung: „Zeig mir eine 5-km-Pufferzone um diesen Standort“

Vereinfachungs-Tool

Reduziert die Anzahl der Scheitelpunkte in einer Linie oder einem Polygon mithilfe des Douglas-Peucker-Algorithmus.

Funktionen:

• Konfigurierbare Toleranz für den Detailgrad
• Erhält die Gesamtform bei reduzierter Komplexität
• Nützlich zur Reduzierung der Dateigröße und Verbesserung der Rendering-Leistung
• Option zur Beibehaltung der Topologie (verhindert Selbstüberschneidungen)

Beispielverwendung: „Vereinfache diese komplexe Grenze, um die Anzahl der Punkte zu reduzieren“

Längen-Tool

Misst die Gesamtlänge einer Linie, die durch eine Reihe von Koordinaten definiert ist.

Funktionen:

• Unterstützt Kilometer, Meilen, Meter und Fuß
• Nützlich zum Messen einer gezeichneten Route, eines Pfads oder einer Grenze ohne Routing-API-Aufruf

Beispielverwendung: „Wie lang ist dieser Wanderweg?“

Konvex-Tool

Berechnet die konvexe Hülle einer Punktmenge – das kleinste konvexe Polygon, das alle Punkte enthält.

Funktionen:

• Nützlich für Begrenzungsflächenanalysen oder zur Schätzung des Abdeckungsbereichs
• Funktioniert offline ohne API-Aufrufe

Beispielverwendung: „Was ist das kleinste Polygon, das alle diese Filialstandorte enthält?“

Nächster-Punkt-Tool

Findet den nächsten Punkt in einer Sammlung zu einem bestimmten Zielpunkt.

Funktionen:

• Effizienter als distance_tool für jeden Kandidaten aufzurufen und zu sortieren
• Nützlich zum Finden des nächsten Geschäfts, Haltestelle oder Wahrzeichens zu einem Standort

Beispielverwendung: „Welches dieser Geschäfte ist meinem aktuellen Standort am nächsten?“

Nächster-Punkt-auf-Linie-Tool

Rastet einen Punkt auf die nächste Position auf einer Linie oder Route ein und gibt diesen Punkt sowie die Entfernung dazu zurück.

Funktionen:

• Nützlich für „Welcher Punkt auf dieser Route ist meinem Standort am nächsten?“ oder Kartenabgleich ohne API-Aufruf

Beispielverwendung: „Wo auf diesem Wanderweg bin ich gerade am nächsten?“

Vereinigen-, Überschneiden- und Differenz-Tools

Kombinieren oder vergleichen zwei oder mehr Polygone – union_tool führt sie zu einer Geometrie zusammen, intersect_tool findet den gemeinsamen Bereich und difference_tool subtrahiert eines von einem anderen.

Funktionen:

• Nützlich zum Kombinieren von Servicebereichen, Finden von Abdeckungsüberschneidungen oder Berechnen von Ausschlusszonen (z. B. „Was ist von Zone A abgedeckt, aber nicht von Zone B?“)
• Funktioniert vollständig offline – keine API-Aufrufe erforderlich
• Jedes gibt eine render_map_tool-Referenz zurück, sodass das Ergebnis direkt visualisiert werden kann

Beispielverwendung: „Kombiniere diese beiden Lieferzonen zu einem Abdeckungsbereich“ / „Wo überschneiden sich diese beiden Isochronen?“ / „Welcher Teil dieses Servicebereichs wird nicht von unserer 15-Minuten-Isochrone abgedeckt?“

Mapbox-API-Tools

Kategorienlisten-Tool (veraltet)

⚠️ Veraltet: Verwenden Sie stattdessen resource_reader_tool mit URI mapbox://categories, oder greifen Sie direkt auf die mapbox://categories-Ressource zu, wenn Ihr Client MCP-Ressourcen unterstützt.

Dieses Tool wird für die Abwärtskompatibilität mit Clients beibehalten, die keine MCP-Ressourcen oder das resource_reader_tool unterstützen.

Matrix-Tool

Berechnet Reisezeiten und Entfernungen zwischen mehreren Punkten mithilfe der Mapbox Matrix API. Funktionen umfassen:

• Effiziente Ein-zu-Viele-, Viele-zu-Ein- oder Viele-zu-Viele-Routingberechnungen
• Unterstützung verschiedener Reiseprofile (driving-traffic, driving, walking, cycling)
• Angabe der Abfahrtszeit für verkehrsabhängige Berechnungen
• Routenzusammenfassung mit Entfernungs- und Dauer-Kennzahlen
• Steuerung des Ansatzes (curb/unrestricted) und Bereich zulässiger Abfahrtskurse

Statisches-Bild-Tool

Generiert statische Kartenbilder mithilfe der Mapbox Static Image API. Funktionen umfassen:

• Benutzerdefinierte Kartenstile (Straßen, Outdoor, Satellit usw.)
• Einstellbare Bildabmessungen und Zoomstufen
• Unterstützung mehrerer Markierungen mit benutzerdefinierten Farben und Beschriftungen
• Overlay-Optionen einschließlich Polylinien und Polygonen
• Automatische Anpassung an angegebene Koordinaten

Kategoriesuch-Tool

Führt eine Kategoriesuche mithilfe der Mapbox Search Box Kategoriesuch-API durch. Funktionen umfassen:

• Suche nach Points of Interest nach Kategorie (Restaurants, Hotels, Tankstellen usw.)
• Filterung nach geografischer Nähe
• Anpassbare Ergebnislimits
• Umfangreiche Metadaten für jedes Ergebnis
• Unterstützung mehrerer Sprachen

Reverse-Geocoding-Tool

Führt Reverse-Geocoding mithilfe der Mapbox Geocoding V6 API durch. Funktionen umfassen:

• Konvertiert geografische Koordinaten in menschenlesbare Adressen
• Anpassbare Detailstufen (Straße, Nachbarschaft, Stadt usw.)
• Filterung der Ergebnisse nach Typ (Adresse, POI, Nachbarschaft usw.)
• Unterstützung mehrerer Sprachen
• Umfangreiche Standortkontextinformationen

Bodenstandort-Tool

Beantwortet Fragen wie „Was befindet sich in der Nähe dieser Koordinate?“ in einem einzigen Aufruf – Ortsname, nahegelegene Points of Interest und Erreichbarkeit in Reisezeit – basierend auf Live-Mapbox-Daten mit Quellenangaben. Verwenden Sie dies anstelle der Verkettung von reverse_geocode_tool mit einer Websuche.

Funktionen:

• Klassifiziert die Abfrage (Routing, Nachbarschaftskontext, POI-Suche oder Region/Erreichbarkeit) und ruft nur die relevanten Daten ab
• Nahegelegene POI-Suche nach Kategorie, wenn angefordert
• Zusammenfassung der Erreichbarkeit in Reisezeit (isochronenbasiert)
• Gibt eine render_map_tool-Referenz mit dem verorteten Standort und nahegelegenen POIs zurück

Beispielverwendung: „In welcher Nachbarschaft befindet sich diese Koordinate, und gibt es in der Nähe Cafés?“

Ortsdetails-Tool

Ruft detaillierte Informationen zu einem bestimmten Ort mithilfe seiner Mapbox-ID ab – Fotos, Öffnungszeiten, Bewertungen, Telefonnummern und Website-URLs. Verwenden Sie dies nach search_and_geocode_tool, category_search_tool oder reverse_geocode_tool, um weitere Details zu einem bestimmten Ergebnis zu erhalten.

Beispielverwendung: „Erzähl mir mehr über dieses erste Café-Ergebnis – Öffnungszeiten, Telefonnummer und Website“

Routen-Tool

Ruft Routing-Anweisungen mithilfe der Mapbox Directions API ab. Funktionen umfassen:

• Unterstützung verschiedener Routing-Profile: Autofahren (mit Live-Verkehr oder typisch), Gehen und Radfahren
• Route über mehrere Wegpunkte (2–25 Koordinatenpaare)
• Option für alternative Routen
• Routenannotationen (Entfernung, Dauer, Geschwindigkeit, Stau)
• Planungsoptionen:
  • Zukünftige Abfahrtszeit (depart_at) für driving- und driving-traffic-Profile
  • Gewünschte Ankunftszeit (arrive_by) nur für das driving-Profil
• Profilspezifische Optimierungen:
  • Autofahren: Fahrzeugabmessungsbeschränkungen (Höhe, Breite, Gewicht)
• Ausschlussoptionen für das Routing:
  • Häufige Ausschlüsse: Fährrouten, nur Bargeld akzeptierende Mautstellen
  • Fahrtspezifische Ausschlüsse: Maut, Autobahnen, unbefestigte Straßen, Tunnel, Landesgrenzen, Staatsgrenzen
  • Benutzerdefinierte Punktausschlüsse (bis zu 50 geografische Punkte, die vermieden werden sollen)
• GeoJSON-Geometrieausgabeformat

Isochronen-Tool

Berechnet Bereiche, die innerhalb einer bestimmten Zeit von einem Standort aus erreichbar sind, mithilfe der Mapbox Isochrone API. Funktionen umfassen:

• Unterstützung verschiedener Reiseprofile (Autofahren, Gehen, Radfahren)
• Anpassbare Reisezeiten oder Entfernungen
• Mehrfachkonturgenerierung (z. B. 15-, 30-, 45-Minuten-Bereiche)
• Optionale Angabe von Abfahrts- oder Ankunftszeit
• Farbanpassung für die Visualisierung

Such- und Geocoding-Tool

Verwendet den Mapbox Search Box Text Search API-Endpunkt, um die Suche und das Geocoding von POIs, Adressen, Orten und allen anderen von dieser API unterstützten Typen zu ermöglichen. Dieses Tool bündelt die Funktionalität, die zuvor vom ForwardGeocodeTool und PoiSearchTool (aus früheren Versionen dieses MCP-Servers) bereitgestellt wurde, in einem einzigen Tool.

Kartenabgleich-Tool

Rastet GPS-Spuren auf das Straßennetz ein, mithilfe der Mapbox Map Matching API. Funktionen umfassen:

• Konvertiert verrauschte GPS-Spuren in saubere Routen auf dem Straßennetz
• Unterstützung verschiedener Reiseprofile (Autofahren, driving-traffic, Gehen, Radfahren)
• Verarbeitet bis zu 100 Koordinatenpaare pro Anfrage
• Optionale Zeitstempel für verbesserte Genauigkeit basierend auf Geschwindigkeit
• Konfigurierbare Einrastradien für verschiedene GPS-Qualitätsstufen
• Routenannotationen (Geschwindigkeitsbegrenzungen, Entfernung, Dauer, Verkehrsstau)
• Mehrere Geometrieausgabeformate (GeoJSON, Polylinie)

Beispielverwendung: „Bereinige diese GPS-Spur und raste sie auf Straßen ein: [Koordinaten mit Zeitstempeln]“

Optimierungs-Tool

Findet die optimale Route durch mehrere Standorte mithilfe der Mapbox Optimization API. Funktionen umfassen:

• Löst das Problem des Handlungsreisenden (TSP) für 2–12 Standorte
• Unterstützung verschiedener Reiseprofile (Autofahren, driving-traffic, Gehen, Radfahren)
• Flexible Konfiguration von Start- und Endpunkt
• Rundreise- oder Einweg-Optimierung
• Abbiegehinweise (optional)
• Routenannotationen (Entfernung, Dauer, Geschwindigkeit)
• Mehrere Geometrieausgabeformate (GeoJSON, Polylinie)

Beispielverwendung: „Finde die optimale Route, um diese 5 Stopps zu besuchen: [Liste der Adressen oder Koordinaten]“

Hinweis: Eine V2-API mit erweiterten Funktionen (Zeitfenster, Kapazitätsbeschränkungen, mehrere Fahrzeuge) ist verfügbar, erfordert jedoch Beta-Zugang. Die V2-Implementierung ist im Codebase enthalten, aber standardmäßig nicht registriert.

Entwicklung

Server untersuchen

Mit Node.js

# Run the built image
npm run inspect:build

Mit 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

Neues Tool erstellen

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

Eine neue Version veröffentlichen

# 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

Wichtig: Der Publisher-Workflow validiert, dass die package.json- und server.json-Versionen mit der Release-Version übereinstimmen. Das Überspringen des Versionssprungs oder der Manifest-Synchronisierung führt zu Veröffentlichungsfehlern.

OpenTelemetry-Tracing

Dieser MCP-Server enthält umfassendes OpenTelemetry-Tracing für Produktionsbeobachtbarkeit:

Schnelldemo

# 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

Hinweis: Der Server lädt beim Start automatisch die Konfiguration aus Ihrer .env-Datei. Die .env.example-Datei enthält Konfigurationsbeispiele für mehrere Observability-Plattformen.

Unterstützte Observability-Plattformen

Konfigurationsbeispiele in .env.example für:

Cloud-Anbieter:

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

SaaS-Plattformen:

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Jedes OTLP-kompatible Backend

Produktionskonfiguration

Siehe docs/tracing.md für vollständige Einrichtungsanweisungen, einschließlich:

• 🔧 Plattformspezifische Konfigurationsanleitungen
• 📊 Authentifizierungs- und Endpunkt-Einrichtung
• 🎯 Benutzerdefinierte Trace-Attribute und Kontext
• 🚀 Leistungsoptimierung (minimaler Overhead)
• 🔍 Fehlerbehebung und Debugging

Tracing-Funktionen:

• ✅ Konfigurationsladungs-Tracing (.env-Datei laden)
• ✅ Automatisches Tool-Ausführungs-Tracing
• ✅ HTTP-Anfrage-Instrumentierung mit CloudFront-Korrelations-IDs
• ✅ Konfigurierbare Exporter (Konsole, OTLP)
• ✅ Sicherheitsbewusst (Datenschutz, JWT-Validierung)
• ✅ Produktionsreif (<1% CPU-Overhead)

Mitwirken

Wir begrüßen Beiträge zum Mapbox MCP Server! Bitte lesen Sie CONTRIBUTING.md, bevor Sie einen Pull-Request einreichen.

Vollständige Standards und Richtlinien:

• CONTRIBUTING.md – Erste Schritte, PR-Prozess, Kurzreferenz
• Engineering Standards (docs/engineering_standards.md) – Vollständige Codequalitäts-, Test-, Dokumentations- und Kollaborationsstandards
• Claude Code Guide (CLAUDE.md) – Standards und Muster für Mitwirkende, die Claude Code verwenden
• AI-Agent-Anweisungen (AGENTS.md) – Leitfaden für andere KI-Codierungsassistenten (Cursor, Continue, Aider usw.)
• GitHub Copilot-Richtlinien – Best Practices für die verantwortungsvolle Nutzung von GitHub Copilot

Schnellstart für Mitwirkende

1. Forken Sie das Repository und klonen Sie Ihren Fork
2. Installieren Sie Abhängigkeiten: npm install
3. Nehmen Sie Ihre Änderungen gemäß unseren Codierungsstandards vor
4. Führen Sie Tests und Linting aus: npm test && npm run lint
5. Fügen Sie Tests für neue Funktionen hinzu
6. Reichen Sie einen Pull-Request mit einer klaren Beschreibung ein

Alle Beiträge müssen unsere CI-Prüfungen und den Code-Review-Prozess bestehen. Siehe docs/engineering_standards.md für detaillierte Anforderungen.

Datennutzung & Datenschutz

Welche Daten an Mapbox-APIs gesendet werden

Wenn Sie die MCP-Server-Tools verwenden, werden die folgenden Daten direkt von Ihrer Umgebung an Mapbox-APIs gesendet:

• Geocoding-Tools: Adress-/Ortsangaben, Koordinaten, Länder-/Regionsfilter
• Such-Tools: Suchanfragen, Standortkoordinaten für Nähe, Kategoriefilter
• Routen-Tool: Start-/Zielkoordinaten, Wegpunkte, Routing-Präferenzen, Fahrzeugbeschränkungen
• Matrix-Tool: Mehrere Koordinatenpaare, Reiseprofil, Abfahrtszeiten
• Statisches Karten-Tool: Koordinaten, Zoomstufe, Stilpräferenzen, Markerinformationen
• Isochronen-Tool: Ursprungskoordinaten, Zeit-/Distanzparameter, Reiseprofil

Ihre Privatsphäre

• Lokale Ausführung: Alle API-Aufrufe werden direkt von Ihrer Umgebung an Mapbox-APIs gesendet
• Token-Sicherheit: Ihr Mapbox-API-Token bleibt auf Ihrem lokalen Rechner und wird niemals an diesen MCP-Server übertragen oder von ihm gespeichert
• Keine Datenspeicherung: Dieser MCP-Server speichert, protokolliert oder sammelt keine Ihrer Daten oder API-Anfragen
• Direkte Kommunikation: Es gibt keinen zwischengeschalteten Server zwischen Ihnen und den Mapbox-APIs

Datennutzung durch Dritte

• Die Datenschutzrichtlinie von Mapbox regelt die an ihre APIs gesendeten Daten: https://www.mapbox.com/legal/privacy/
• API-Nutzung: Die standardmäßigen Mapbox-API-Bedingungen gelten für alle Anfragen über diese Tools
• Datenaufbewahrung: Siehe Mapbox-Dokumentation für deren Datenaufbewahrungsrichtlinien

Support & Kontakt

Bei MCP-Server-Problemen

• E-Mail: mcp-feedback@mapbox.com
• GitHub Issues: Fehler melden und Feature-Anfragen stellen

Bei Fragen zu Mapbox-APIs

• Mapbox-Support: https://support.mapbox.com/
• Dokumentation: https://docs.mapbox.com/
• API-Status: https://status.mapbox.com/

Wartungsverpflichtung

Dieser MCP-Server wird offiziell von Mapbox, Inc. gewartet. Wir bieten:

• Regelmäßige Updates für neue Mapbox-API-Funktionen
• Fehlerbehebungen und Sicherheitsupdates
• Kompatibilität mit den neuesten MCP-Protokollversionen
• Community-Support über GitHub Issues

---

MIT-Lizenz