Mapbox

Mapbox MCP Server

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

Geospatialle Intelligenz für Ihre KI-Anwendungen freischalten

Der Mapbox MCP Server verwandelt jeden KI-Agenten und jede KI-Anwendung in ein geospatial orientiertes System, indem er nahtlosen Zugriff auf die umfassende Location-Intelligence-Plattform von Mapbox bietet. Mit diesem Server kann Ihre KI Orte verstehen und analysieren, sich in der physischen Welt zurechtfinden und auf umfangreiche Geodaten zugreifen, darunter:

• Globale Geokodierung, um Adressen und Ortsnamen in Koordinaten umzuwandeln und umgekehrt
• Suche nach Points of Interest (POI) in Millionen von Unternehmen, Sehenswürdigkeiten und Orten weltweit
• Multimodales Routing für Autofahrten, Fußwege und Fahrradtouren mit Echtzeit-Verkehrsdaten
• Fahrzeitmatrizen zur Analyse der Erreichbarkeit und Optimierung der Logistik
• Routenoptimierung, um die optimale Besuchsreihenfolge für mehrere Zwischenstopps zu finden (Problem des Handlungsreisenden)
• Map Matching, um GPS-Spuren an das Straßennetz anzupassen und Routen sauber darzustellen
• Isochronen-Generierung, um Gebiete zu visualisieren, die innerhalb bestimmter Zeit- oder Entfernungsgrenzen erreichbar sind
• Live-Kartendarstellung mit Interaktion (render_map_tool), um Routen, Suchergebnisse und Ihr eigenes benutzerdefiniertes GeoJSON direkt im Chat auf einer echten Mapbox-GL-JS-Karte anzuzeigen
• Statische Kartenbilder, um Orte, Routen und geografische Daten visuell darzustellen
• Offline-Geodatenberechnungen für Entfernung, Fläche, Peilung, Puffer und räumliche Analysen ohne API-Aufrufe

Ganz gleich, ob Sie einen KI-Reiseassistenten, einen Logistikoptimierer, einen standortbasierten Empfehlungsdienst oder eine andere Anwendung entwickeln, die verstehen muss, „wo“ etwas ist: Der Mapbox MCP Server stellt die räumliche Intelligenz bereit, die dies ermöglicht. Sie können ihn auch in beliebten Clients wie Claude Desktop und VS Code aktivieren. Weitere Informationen finden Sie weiter unten.

Verwendung

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

Gehosteter MCP-Endpunkt

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

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

Ausführliche Einrichtungsanweisungen für verschiedene Clients und Informationen zur API-Nutzung finden Sie im Leitfaden zum gehosteten MCP-Server.

So erhalten Sie ein Mapbox-Zugriffstoken:

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

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

Integrationsleitfäden

Ausführliche Einrichtungsanweisungen für verschiedene Integrationen finden Sie in den folgenden Leitfäden:

• Einrichtung von Claude Desktop – Anweisungen zur Konfiguration von Claude Desktop für die Verwendung mit diesem MCP-Server
• Einrichtung von Goose – Einrichtung des KI-Agenten-Frameworks Goose
• Einrichtung von VS Code – Einrichtung einer Entwicklungsumgebung in Visual Studio Code
• Einrichtung der Cursor AI IDE – Einrichtung einer Entwicklungsumgebung in der Cursor AI IDE
• Integration von Smolagents – Beispiel für die Verbindung von KI-Agenten mit den Tools von Mapbox
• Tools direkt importieren – Mapbox-Tools in Ihren eigenen Anwendungen verwenden, ohne den MCP-Server auszuführen
• Leitfaden zu render_map_tool – Das Kartenvisualisierungs-Primitive: vollständiges Payload-Schema und Anleitung zum eigenständigen Darstellen eigener Daten ohne andere Mapbox-Tools
• Elicitationen – Wie search_and_geocode_tool und directions_tool den Benutzer auffordern, Ergebnisse eindeutig zuzuordnen oder eine Route auszuwählen, und wie sie auf Clients ohne Unterstützung dafür ausweichen

Beispiel-Prompts

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

Standortbestimmung

Verwenden Sie für Abfragen, bei denen Koordinaten im Mittelpunkt stehen – „Was ist in meiner Nähe?“, „In welchem Viertel bin ich?“, „Was ist in N Minuten erreichbar?“ – ground_location_tool. Das Tool kombiniert Reverse-Geokodierung, Kategoriesuche und Isochronen in einem einzigen Aufruf, wählt je nach Abfrage adaptiv die passende Strategie und gibt typisierte Datensätze mit Quellenangaben zurück (Namen, Adressen, Koordinaten, Entfernungen und Erreichbarkeitspolygone).

Jeder der folgenden vier Prompts nutzt in einem einzigen Tool-Aufruf eine andere Strategie:

• Viertel – „In welchem Viertel liegt 47.6097, -122.3408, und was gibt es in meiner Nähe?“
• POI – „Cafés, die von 40.7580, -73.9855 aus in 10 Minuten zu Fuß erreichbar sind“
• Region – „Was kann ich von 37.7749, -122.4194 aus in 15 Minuten zu Fuß erreichen?“
• Routing – „Nächstgelegener routbarer Punkt, um jemanden bei 34.0522, -118.2437 abzusetzen“

Orte entdecken

• „Finde Cafés, die vom Empire State Building aus zu Fuß erreichbar sind“
• „Ich möchte von Seattle nach Portland fahren. Gibt es unterwegs einen Starbucks?“
• „Zeige mir Tankstellen entlang der Route von Boston nach New York“
• „Welche Restaurants gibt es in der Nähe des Times Square?“

Navigation und Reisen

• „Gib mir eine Wegbeschreibung vom LAX nach Hollywood mit aktuellen Verkehrsdaten“
• „Wie lange würde es dauern, vom Central Park zum Times Square zu laufen?“
• „Berechne die Fahrzeit während der Hauptverkehrszeit mit dem Taxi von meinem Hotel (Four Seasons) zum JFK Airport“

Visualisierung und Karten

• „Zeige mir mit dem Mapbox-Kartendarstellungstool eine Wegbeschreibung von der Golden Gate Bridge zum Union Square in San Francisco“ – stellt eine Live-Route mit Interaktion auf einer echten Mapbox-Karte dar
• „Erstelle ein Kartenbild mit der Route von der Golden Gate Bridge zum Fisherman's Wharf und Markierungen an beiden Orten“
• „Zeige mir eine Satellitenansicht von Manhattan mit markierten wichtigen Sehenswürdigkeiten“
• „Erstelle eine Karte, auf der alle Starbucks-Standorte im Umkreis von einer Meile um die Innenstadt von Seattle hervorgehoben sind“
• „Zeige ein gefülltes Polygon über diesen Koordinaten: [...], mit einer Markierung mit der Beschriftung 'Warehouse' bei [...]“ – stellt Ihr eigenes GeoJSON direkt über render_map_tool dar, ohne dass ein anderes Mapbox-Tool erforderlich ist

Analyse und Planung

• „Zeige mir Gebiete, die von der Innenstadt Portlands aus in 30 Minuten mit dem Auto erreichbar sind“
• „Berechne eine Fahrzeitmatrix zwischen diesen drei Hotelstandorten (Marriott, Sheraton und Hilton) und dem Kongresszentrum in Denver“
• „Finde die optimale Route, die diese drei Touristenattraktionen (Golden Gate, Musical Stairs und Fisherman's Wharf) in San Francisco besucht“
• „Optimiere eine Liefertour für diese acht Adressen: [list of addresses]“

GPS- und Routenabgleich

• „Bereinige diese GPS-Spur und zeige die tatsächliche Route auf den Straßen: [list of coordinates with timestamps]“
• „Passe diese aufgezeichnete Fahrradtour an das Radwegenetz an: [GPS coordinates]“
• „Gleiche diese Autofahrt mit dem Straßennetz ab und zeige die Verkehrsstauwerte“

Offline-Geodatenberechnungen

• „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 Servicegebiets-Polygons?“
• „Wie lautet die Peilung von San Francisco nach New York?“
• „Finde den Mittelpunkt zwischen London und Paris“
• „Erstelle eine Pufferzone von 5 Meilen um diesen Standort“
• „Berechne den Schwerpunkt dieser Viertelgrenze“
• „Wie lautet die Bounding Box für diese Routenkoordinaten?“
• „Vereinfache dieses komplexe Polygon, um die Anzahl der Punkte zu reduzieren“

Tipps für bessere Ergebnisse

• Geben Sie Orte möglichst genau an (verwenden Sie vollständige Adressen oder Namen von Sehenswürdigkeiten).
• Geben Sie Ihre bevorzugte Fortbewegungsart an (Auto, zu Fuß, Fahrrad).
• Nennen Sie bei Bedarf zeitliche Einschränkungen („während der Hauptverkehrszeit“, „um 15 Uhr“).
• Fragen Sie bei Bedarf nach bestimmten Ausgabeformaten („als Kartenbild“, „im JSON-Format“).

Ausführliche Beispiele: Unter examples/search-along-route.md finden Sie umfassende Beispiele für den Prompt zur Suche entlang einer Route mit verschiedenen Anwendungsfällen sowie Anweisungen zum Testen mit MCP Inspector.

Ressourcen

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

Verfügbare Ressourcen

Mapbox-Kategorienressource

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

Greifen Sie auf die vollständige Liste der verfügbaren Kategorie-IDs zu, die Sie mit dem Kategoriesuchtool verwenden können. Kategorien dienen dazu, Suchergebnisse nach Typ zu filtern (z. B. „restaurant“, „hotel“, „gas_station“).

Beispiele:

• mapbox://categories – Standard-Kategorienliste (Englisch)
• mapbox://categories/ja – Japanische Kategorienamen
• mapbox://categories/es – Spanische Kategorienamen

Auf Ressourcen zugreifen:

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

Umfangreiche Kartenvorschauen (render_map_tool)

Jedes Geodaten-Tool dieses Servers (Wegbeschreibung, Isochrone, Suche und mehr) kann sein Ergebnis als Live-Mapbox-GL-JS-Karte mit Interaktion über render_map_tool anzeigen – das einzige Visualisierungs-Primitive des Servers. Es wird über das MCP Apps-Protokoll (@modelcontextprotocol/ext-apps) als eigenständiges HTML-Panel direkt im Chat dargestellt, mit einer Vollbildschaltfläche, in den folgenden 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 manuell zusammengestelltes GeoJSON – Ihre eigenen Polygone, Markierungen und Routen – ohne Abhängigkeit von directions_tool, isochrone_tool oder einem anderen Mapbox-API-Aufruf. Das vollständige Handbuch zu render_map_tool enthält das Payload-Schema und ein vollständiges eigenständiges Beispiel.

Wenn Sie in Clients ohne MCP Apps-Unterstützung garantiert ein statisches Bild 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

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

Ressourcen sind eine zentrale MCP-Funktion, die 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 „Fallback-Tools für Ressourcen“ bereitstellen, die denselben Inhalt wie Ressourcen über Tool-Aufrufe liefern.

Fallback-Tools:

• resource_reader_tool – Allgemeiner Fallback zum Lesen beliebiger Ressourcen anhand ihres URI
• category_list_tool – Ermöglicht den Zugriff auf die Kategorienliste (mapbox://categories)

Standardmäßig sind diese Tools NICHT enthalten (es wird davon ausgegangen, 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 diese Einstellung verwendet werden sollte:

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

Tools

Hilfsprogramme

Ressourcenleser-Tool

Ermöglicht Clients, die die native MCP-Ressourcen-API nicht unterstützen, den Zugriff auf MCP-Ressourcen. Verwenden Sie dieses Tool, um Ressourcen wie die Kategorienliste zu lesen.

Parameter:

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

Beispiele für die Verwendung:

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

Hinweis: Wenn Ihr MCP-Client native Ressourcen unterstützt, verwenden Sie für eine bessere Leistung vorzugsweise direkt die Ressourcen-API.

Offline-Geodaten-Tools

Diese Tools führen Geodatenberechnungen vollständig offline aus, ohne Mapbox-API-Aufrufe zu benötigen. Sie verwenden Turf.js für präzise geografische Berechnungen und funktionieren überall, auch ohne Internetverbindung.

Entfernungs-Tool

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

Funktionen:

• Unterstützt mehrere Einheiten: Kilometer, Meilen, Meter, Fuß und Seemeilen
• Präzise Berechnung der Großkreisentfernung
• Keine API-Aufrufe erforderlich

Beispiel für die Verwendung: „Wie groß ist die Entfernung zwischen San Francisco (37.7749°N, 122.4194°W) und New York (40.7128°N, 74.0060°W)?“

Tool „Punkte innerhalb eines Polygons“

Prüft einen oder mehrere Punkte anhand eines Polygons oder Multipolygons und gibt nur die Punkte zurück, die innerhalb liegen. Unterstützt sowohl einen einzelnen Punkt als auch mehrere Punkte in einem Aufruf.

Funktionen:

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

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

Zielpunkt-Tool

Berechnet einen Zielpunkt anhand eines Startpunkts, einer Peilung und einer Entfernung mithilfe eines geodätischen (Großkreis-)Offsets.

Funktionen:

• Geradliniger Offset, keine berechnete Route
• Nützlich für „Finde einen Punkt 5 km nördlich von X“ oder zum Erstellen von Such-Offsets
• Keine API-Aufrufe erforderlich

Beispielverwendung: „Wo liegt der Punkt 10 km nordöstlich der Space Needle?“

Peilungs-Tool

Berechnet die Himmelsrichtung (Peilung) von einer Koordinate zu einer anderen.

Funktionen:

• Gibt die Peilung in Grad zurück (0–360°)
• Gibt die Himmelsrichtung an (N, NE, E, SE, 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

Ermittelt den geografischen Mittelpunkt zwischen zwei Koordinaten entlang des Großkreisverlaufs.

Funktionen:

• Berechnet den tatsächlichen Mittelpunkt auf der gekrümmten Erdoberfläche
• Nützlich für Vorschläge zu Treffpunkten
• Verarbeitet Berechnungen über große Entfernungen korrekt

Beispielverwendung: „Was liegt auf halber Strecke 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 sollte 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ß
• Präzise Flächenberechnung auf der Erdoberfläche
• Funktioniert mit Polygonen jeder 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 [minLongitude, minLatitude, maxLongitude, maxLatitude] zurück
• Nützlich für Ansichtsfensterberechnungen und räumliche Indizierung

Beispielverwendung: „Wie lautet 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äheanalysen und zum Erstellen von Einflusszonen

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

Vereinfachungs-Tool

Reduziert die Anzahl der Stützpunkte einer Linie oder eines Polygons mithilfe des Douglas-Peucker-Algorithmus.

Funktionen:

• Konfigurierbare Toleranz für den Detailgrad
• Bewahrt die Gesamtform und reduziert gleichzeitig die Komplexität
• Nützlich zum Verkleinern von Dateien und Verbessern der Rendering-Leistung
• Option zum Beibehalten der Topologie (Verhindern von 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 eingezeichneten Route, eines Pfads oder einer Grenze ohne API-Aufruf für eine Routenberechnung

Beispielverwendung: „Wie lang ist dieser Wanderweg?“

Konvexhüllen-Tool

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

Funktionen:

• Nützlich für Analysen von Begrenzungsflächen oder zur Schätzung von Abdeckungsflächen
• Funktioniert offline ohne API-Aufrufe

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

Nächster-Punkt-Tool

Ermittelt den nächstgelegenen Punkt in einer Sammlung zu einem gegebenen Zielpunkt.

Funktionen:

• Effizienter, als distance_tool für jeden Kandidaten aufzurufen und die Ergebnisse zu sortieren
• Nützlich, um das nächstgelegene Geschäft, die nächste Haltestelle oder das nächste Wahrzeichen zu einem Standort zu finden

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

Nächster-Punkt-auf-Linie-Tool

Projiziert einen Punkt auf die nächstgelegene Position auf einer Linie oder Route und gibt diesen Punkt sowie die Entfernung dorthin zurück.

Funktionen:

• Nützlich für Fragen wie „Welcher Punkt auf dieser Route liegt meinem Standort am nächsten?“ oder für Map-Matching ohne API-Aufruf

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

Vereinigungs-, Schnittmengen- und Differenz-Tools

Kombinieren oder vergleichen zwei oder mehr Polygone – union_tool führt sie zu einer Geometrie zusammen, intersect_tool ermittelt die gemeinsame Fläche und difference_tool zieht eines vom anderen ab.

Funktionen:

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

Beispielverwendung: „Führe diese beiden Lieferzonen zu einem Abdeckungsgebiet zusammen“ / „Wo überschneiden sich diese beiden Isochronen?“ / „Welcher Teil dieses Servicegebiets wird nicht von unserer 15-Minuten-Isochrone abgedeckt?“

Mapbox-API-Tools

Kategorielisten-Tool (veraltet)

⚠️ Veraltet: Verwende stattdessen resource_reader_tool mit dem URI mapbox://categories oder greife direkt auf die Ressource mapbox://categories zu, wenn dein Client MCP-Ressourcen unterstützt.

Dieses Tool wird aus Gründen der Abwärtskompatibilität mit Clients beibehalten, die MCP-Ressourcen oder resource_reader_tool nicht unterstützen.

Matrix-Tool

Berechnet Reisezeiten und Entfernungen zwischen mehreren Punkten mithilfe der Mapbox Matrix API. Zu den Funktionen gehören:

• Effiziente Routenberechnungen von einem zu vielen, von vielen zu einem oder von vielen zu vielen Punkten
• Unterstützung verschiedener Reiseprofile (driving-traffic, driving, walking, cycling)
• Angabe der Abfahrtszeit für verkehrsabhängige Berechnungen
• Zusammenfassung der Route mit Entfernungs- und Dauerangaben
• Steuerung der Anfahrt (Bordstein/unbeschränkt) und des zulässigen Bereichs für Abfahrtspeilungen

Tool für statische Bilder

Erstellt statische Kartenbilder mithilfe der Mapbox static image API. Zu den Funktionen gehören:

• Benutzerdefinierte Kartenstile (streets, outdoors, satellite usw.)
• Anpassbare 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 category search API durch. Zu den Funktionen gehören:

• Suche nach Points of Interest anhand von Kategorien (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. Zu den Funktionen gehören:

• Umwandlung geografischer 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 Informationen zum Standortkontext

Tool für Standortinformationen

Beantwortet Fragen wie „Was befindet sich in der Nähe dieser Koordinate?“ mit einem einzigen Aufruf – einschließlich Ortsname, nahegelegener Points of Interest und Erreichbarkeit innerhalb einer bestimmten Reisezeit. Die Informationen stammen aus aktuellen Mapbox-Daten und enthalten Quellenangaben. Verwende dieses Tool, statt reverse_geocode_tool mit einer Websuche zu verketten.

Funktionen:

• Klassifiziert die Anfrage (Routenplanung, Nachbarschaftskontext, POI-Suche oder Region/Erreichbarkeit) und ruft nur die relevanten Daten ab
• Suche nach nahegelegenen POIs anhand von Kategorien, sofern angefordert
• Zusammenfassung der Erreichbarkeit innerhalb einer bestimmten Reisezeit (auf Isochronenbasis)
• Gibt eine render_map_tool-Referenz zurück, in der der verifizierte Standort und nahegelegene POIs eingezeichnet sind

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

Tool für Ortsdetails

Ruft detaillierte Informationen zu einem bestimmten Ort anhand seiner Mapbox-ID ab – Fotos, Öffnungszeiten, Bewertungen, Telefonnummern und Website-URLs. Verwende es nach search_and_geocode_tool, category_search_tool oder reverse_geocode_tool, um weitere Details zu einem bestimmten Ergebnis abzurufen.

Beispielverwendung: „Erzähl mir mehr über das erste Café in den Ergebnissen – Öffnungszeiten, Telefonnummer und Website“

Routenplanungs-Tool

Ruft Routenanweisungen mithilfe der Mapbox Directions API ab. Zu den Funktionen gehören:

• Unterstützung verschiedener Routenprofile: Autofahren (mit aktuellem oder typischem Verkehr), Gehen und Radfahren
• Routenplanung über mehrere Wegpunkte (2–25 Koordinatenpaare)
• Option für alternative Routen
• Routenannotationen (Entfernung, Dauer, Geschwindigkeit, Verkehrsaufkommen)
• Zeitplanungsoptionen:
  • Zukünftige Abfahrtszeit (depart_at) für die Profile driving und driving-traffic
  • Gewünschte Ankunftszeit (arrive_by) nur für das Profil driving
• Profilspezifische Optimierungen:
  • Autofahren: Einschränkungen für Fahrzeugabmessungen (Höhe, Breite, Gewicht)
• Ausschlussoptionen für die Routenplanung:
  • Allgemeine Ausschlüsse: Fährverbindungen, Mautstraßen mit ausschließlicher Barzahlung
  • Spezifische Ausschlüsse für Autofahrten: Mautstraßen, Autobahnen, unbefestigte Straßen, Tunnel, Landesgrenzen, Staatsgrenzen
  • Benutzerdefinierte Punktausschlüsse (bis zu 50 geografische Punkte, die vermieden werden sollen)
• GeoJSON-Ausgabeformat für Geometrien

Isochronen-Tool

Berechnet mithilfe der Mapbox Isochrone API Gebiete, die von einem Standort aus innerhalb einer angegebenen Zeit erreichbar sind. Zu den Funktionen gehören:

• Unterstützung verschiedener Reiseprofile (Autofahren, Gehen, Radfahren)
• Anpassbare Reisezeiten oder Entfernungen
• Erstellung mehrerer Konturen (z. B. Bereiche für 15, 30 und 45 Minuten)
• Optionale Angabe der Abfahrts- oder Ankunftszeit
• Farbanpassung zur Visualisierung

Such- und Geocoding-Tool

Verwendet den Endpunkt der Mapbox Search Box Text Search API, um die Suche nach und das Geocoding von POIs, Adressen, Orten und allen anderen von dieser API unterstützten Typen zu ermöglichen. Dieses Tool vereint die Funktionen, die zuvor von ForwardGeocodeTool und PoiSearchTool (in früheren Versionen dieses MCP-Servers) bereitgestellt wurden, in einem einzigen Tool.

Map-Matching-Tool

Projiziert GPS-Spuren mithilfe der Mapbox Map Matching API auf das Straßennetz. Zu den Funktionen gehören:

• Umwandlung verrauschter GPS-Spuren in saubere Routen auf dem Straßennetz
• Unterstützung verschiedener Reiseprofile (driving, driving-traffic, walking, cycling)
• Verarbeitung von bis zu 100 Koordinatenpaaren pro Anfrage
• Optionale Zeitstempel für höhere Genauigkeit anhand der Geschwindigkeit
• Konfigurierbare Fangradien für unterschiedliche GPS-Qualitätsstufen
• Routenannotationen (Geschwindigkeitsbegrenzungen, Entfernung, Dauer, Verkehrsaufkommen)
• Mehrere Geometrieausgabeformate (GeoJSON, polyline)

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

Optimierungs-Tool

Ermittelt mithilfe der Mapbox Optimization API die optimale Route durch mehrere Standorte. Zu den Funktionen gehören:

• Löst das Problem des Handlungsreisenden (TSP) für 2–12 Standorte
• Unterstützung verschiedener Reiseprofile (driving, driving-traffic, walking, cycling)
• Flexible Konfiguration von Start- und Endpunkt
• Optimierung für Rundreisen oder einfache Fahrten
• Abbiegehinweise (optional)
• Routenannotationen (Entfernung, Dauer, Geschwindigkeit)
• Mehrere Geometrieausgabeformate (GeoJSON, polyline)

Beispielverwendung: „Finde die optimale Route für diese 5 Stopps: [Liste von Adressen oder Koordinaten]“

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

Feedback-Tool

Sendet das Feedback eines Nutzers zur App oder zum Agenten über die Mapbox Feedback API (Public Preview) an den Entwickler. Das Feedback wird unter dem Konto erfasst, dem das Zugriffstoken gehört. Wenn du also mit deinem eigenen Token eine App oder einen Agenten auf diesem Server erstellst, erscheint das Feedback deiner Nutzer im selben Feed wie die Berichte des Feedback Agent deiner Apps und kann im Feedback Explorer geprüft werden. Probleme werden damit nicht an Mapbox gemeldet. Wie der Feedback Agent dient das Tool dazu, Rückmeldungen zu deinem Produkt zu sammeln, die dir helfen, die Bedürfnisse der Nutzer zu verstehen, zum Beispiel:

• Ein Ort, der geschlossen wurde, falsche Angaben hat oder am falschen Standort liegt
• Ein Ort oder eine Adresse, der bzw. die nicht gefunden werden kann
• Eine gesperrte Straße, ein falsches Tempolimit oder eine falsche Verkehrslage
• Eine Route mit einer unzulässigen Abbiegung oder Zufahrt oder gar keine Route
• Etwas zur App selbst, etwa ein Fehler oder ein Vorschlag (application_issue)

Das Tool sendet den Feedbacktext, eine Kategorie und den Standort und gibt die ID und den Status des Eintrags zurück. Der Standort ist optional, wenn sich das Feedback nicht auf einen Ort bezieht. Die API verlangt jedoch einen Standort, daher sendet das Tool vorerst 0, 0, wie vom Feedback-API-Team empfohlen. Ohne Zustimmung des Nutzers wird nichts gesendet: Clients, die Elicitation unterstützen, zeigen zuerst eine Bestätigungsaufforderung an. In allen anderen Fällen fordert die Toolbeschreibung das Modell auf, im Chat eine Bestätigung einzuholen.

Die Feedback API ist während der Public Preview kostenlos. Ab der General Availability berechnet Feedback Agent $0.02 pro Feedbackeintrag. Um zu vermeiden, dass dasselbe Problem zweimal gemeldet wird, prüft das Tool vor dem Senden die eigenen Meldungen des Kontos aus den letzten 30 Tagen. Wenn eine Meldung derselben Kategorie innerhalb von 50 m noch geprüft wird (Feedback ohne Standort wird nicht geprüft), gibt das Tool diese Meldung zurück, statt eine neue zu senden. Die Feedback API listet nur die eigenen Meldungen des Kontos auf und kann daher keine Meldungen anderer Konten erkennen. send_anyway: true überspringt die Prüfung, wenn der Nutzer angibt, dass es sich um ein anderes Problem handelt.

Anforderungen: Zum Senden benötigt das Zugriffstoken den Scope user-feedback:write, für die Duplikatprüfung den Scope user-feedback:read. Ohne Schreib-Scope gibt das Tool eine entsprechende Fehlermeldung zurück. Ohne Lese-Scope sendet es das Feedback ohne Prüfung und weist im Ergebnis darauf hin. Um das Tool wegzulassen, starte den Server mit --disable-tools feedback_tool.

Beispielverwendung: „Blue Bottle in der Mint St hat letztes Jahr geschlossen. Kannst du das als Feedback senden?“

Report-Tool

Sendet Feedback zum Mapbox MCP-Server selbst an das Mapbox-Team, das ihn entwickelt: zu einem Fehler, einem Tool mit falschem oder verwirrendem Ergebnis, einer fehlenden Funktion oder einem Vorschlag. Das Feedback wird über das eigene Konto von Mapbox eingereicht, nicht über deins. Daher ist kein zusätzlicher Token-Scope erforderlich. Anschließend kann es weder abgerufen noch zurückgezogen werden. Dieses Tool ist nicht dafür gedacht, falsche Karten-, Orts- oder Routendaten zu melden.

Der Server fügt am Ende des Textes seine Version, den Namen und die Version des Clients sowie das Tool hinzu, auf das sich das Feedback bezieht. Ohne Zustimmung des Nutzers wird nichts gesendet: Clients, die Elicitation unterstützen, zeigen zuerst eine Bestätigungsaufforderung an. In allen anderen Fällen fordert die Toolbeschreibung das Modell auf, im Chat eine Bestätigung einzuholen.

Das Tool verwendet den Endpunkt, den das Feedback-API-Team für den Befehl mapbox report der Mapbox CLI hinzugefügt hat. Um das Tool wegzulassen, starte den Server mit --disable-tools report_tool.

Beispielverwendung: „Die Karte hat keine meiner Isochronen gezeichnet. Kannst du das Mapbox MCP-Team informieren?“

Tool zum Auflisten öffentlicher Tokens

Listet die öffentlichen Zugriffstokens des Kontos (pk.) auf. Das ist für einen Agent gedacht, der außerhalb des Chats eine Webseite oder App erstellt, die Mapbox GL JS lädt oder Mapbox-APIs im Browser aufruft. Im Chat benötigt render_map_tool kein Token. Zu jedem Token werden sein Name, der Hinweis, ob es das Standardtoken ist, seine URL-Einschränkungen und seine Scopes angezeigt.

Übergib site_url (die URL, unter der die Seite ausgeführt wird). Wenn das Konto ein Token mit dieser URL-Einschränkung hat, empfiehlt das Tool dieses Token. Andernfalls empfiehlt es das öffentliche Standardtoken und weist darauf hin, dass eine veröffentlichte Website stattdessen ein URL-beschränktes Token verwenden sollte. Dazu wird ein Link zum Erstellen eines solchen Tokens bereitgestellt. Jeder, der ein uneingeschränktes öffentliches Token kopiert, kann es verwenden; die Nutzung wird dem Konto in Rechnung gestellt.

Das Tool gibt niemals geheime oder temporäre Tokens zurück und kann keine Tokens erstellen (dafür ist tokens:write erforderlich; create_token_tool des DevKit-Servers übernimmt das).

Anforderungen: Zum Auflisten ist der Scope tokens:read erforderlich. Derselbe Scope wird auch von der In-Chat-Karte verwendet, um das öffentliche Standardtoken zu finden. Bei einem Zugriffstoken mit pk. oder wenn das Auflisten mit dem servereigenen MAPBOX_ACCESS_TOKEN fehlschlägt und MAPBOX_PUBLIC_TOKEN gesetzt ist, gibt das Tool stattdessen dieses Token zurück. Ein Aufrufer mit eigenem Bearer-Token (der gehostete Server) erhält niemals MAPBOX_PUBLIC_TOKEN, und ein Token, das auf andere URLs beschränkt ist, wird niemals empfohlen. Um das Tool wegzulassen, starte den Server mit --disable-tools list_public_tokens_tool.

Beispielverwendung: „Erstelle eine einseitige Website, die unsere drei Filialstandorte auf einer Mapbox-Karte zeigt.“

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)

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 prüft, ob die Versionen von package.json und server.json mit der Release-Version übereinstimmen. Wird die Version nicht erhöht oder das Manifest nicht synchronisiert, schlägt die Veröffentlichung fehl.

OpenTelemetry-Tracing

Dieser MCP-Server umfasst umfassendes OpenTelemetry-Tracing für die Beobachtbarkeit in Produktionsumgebungen:

Kurzdemo

# 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 deiner Datei .env. Die Datei .env.example 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

Unter docs/tracing.md findest du eine vollständige Anleitung zur Einrichtung, einschließlich:

• 🔧 Plattformspezifischer Konfigurationsanleitungen
• 📊 Einrichtung von Authentifizierung und Endpunkten
• 🎯 Benutzerdefinierter Trace-Attribute und Kontext
• 🚀 Leistungsoptimierung (minimaler Overhead)
• 🔍 Fehlerbehebung und Debugging

Tracing-Funktionen:

• ✅ Tracing beim Laden der Konfiguration (Laden der .env-Datei)
• ✅ Automatisches Tracing der Toolausführung
• ✅ Instrumentierung von HTTP-Anfragen mit CloudFront-Korrelations-IDs
• ✅ Konfigurierbare Exporter (Konsole, OTLP)
• ✅ Sicherheitsbewusst (Datenschutz, JWT-Validierung)
• ✅ Produktionsbereit (<1% CPU-Overhead)

Mitwirken

Beiträge zum Mapbox MCP Server sind willkommen! Lies bitte CONTRIBUTING.md, bevor du einen Pull Request einreichst.

Vollständige Standards und Richtlinien:

• CONTRIBUTING.md – Einstieg, PR-Prozess, Kurzübersicht
• Engineering Standards (docs/engineering_standards.md) – Vollständige Standards für Codequalität, Tests, Dokumentation und Zusammenarbeit
• Claude Code Guide (CLAUDE.md) – Standards und Muster für Mitwirkende, die Claude Code verwenden
• AI Agent Instructions (AGENTS.md) – Anleitung für andere KI-Coding-Assistenten (Cursor, Continue, Aider usw.)
• GitHub Copilot Guidelines – Best Practices für den verantwortungsvollen Einsatz von GitHub Copilot

Schnellstart für Mitwirkende

1. Forke das Repository und klone deinen Fork.
2. Installiere die Abhängigkeiten: npm install
3. Nimm deine Änderungen gemäß unseren Coding-Standards vor.
4. Führe Tests und Linting aus: npm test && npm run lint
5. Ergänze Tests für alle neuen Funktionen.
6. Reiche einen Pull Request mit einer klaren Beschreibung ein.

Alle Beiträge müssen unsere CI-Prüfungen und den Code-Review-Prozess bestehen. Detaillierte Anforderungen findest du unter docs/engineering_standards.md.

Datennutzung und Datenschutz

Welche Daten an Mapbox-APIs gesendet werden

Wenn du die Tools des MCP-Servers verwendest, werden die folgenden Daten direkt aus deiner Umgebung an Mapbox-APIs gesendet:

• Geocoding-Tools: Adress- und Standorttext, Koordinaten, Länder- und Regionsfilter
• Suchtools: Suchanfragen, Standortkoordinaten für die Nähe, Kategoriefilter
• Directions-Tool: Start- und Endkoordinaten, Wegpunkte, Routingeinstellungen, Fahrzeugbeschränkungen
• Matrix-Tool: Mehrere Koordinatenpaare, Reiseprofil, Abfahrtszeiten
• Static-Map-Tool: Koordinaten, Zoomstufe, Stileinstellungen, Markierungsinformationen
• Isochrone-Tool: Ausgangskoordinaten, Zeit- und Entfernungsparameter, Reiseprofil

Deine Privatsphäre

• Lokale Ausführung: Alle API-Aufrufe erfolgen direkt aus deiner Umgebung an Mapbox-APIs.
• Token-Sicherheit: Dein Mapbox-API-Token bleibt auf deinem lokalen Rechner und wird niemals an diesen MCP-Server übertragen oder von ihm gespeichert.
• Keine Datenspeicherung: Dieser MCP-Server speichert, protokolliert oder erfasst keine deiner Daten oder API-Anfragen.
• Direkte Kommunikation: Zwischen dir und den Mapbox-APIs gibt es keinen zwischengeschalteten Server.

Datennutzung durch Dritte

• Die Datenschutzrichtlinie von Mapbox gilt für Daten, die an die APIs gesendet werden: https://www.mapbox.com/legal/privacy/
• API-Nutzung: Für alle über diese Tools ausgeführten Anfragen gelten die üblichen Nutzungsbedingungen der Mapbox-APIs.
• Datenaufbewahrung: Informationen zu den Aufbewahrungsrichtlinien findest du in der Dokumentation von Mapbox.

Support und Kontakt

Bei Problemen mit dem MCP-Server

• E-Mail: mcp-feedback@mapbox.com
• GitHub Issues: Fehler und Funktionswünsche melden

Bei Fragen zu Mapbox-APIs

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

Wartungszusage

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 License