Mapbox

Serveur MCP Mapbox

Serveur Node.js implémentant le Model Context Protocol (MCP) pour les API Mapbox.

Libérez l'intelligence géospatiale pour vos applications IA

Le serveur MCP Mapbox transforme n'importe quel agent ou application IA en système conscient de la géographie en offrant un accès transparent à la plateforme complète d'intelligence de localisation de Mapbox. Avec ce serveur, votre IA peut comprendre et raisonner sur les lieux, naviguer dans le monde physique et accéder à des données géospatiales riches, notamment :

• Géocodage mondial pour convertir des adresses et noms de lieux en coordonnées et vice versa
• Recherche de points d'intérêt (POI) parmi des millions d'entreprises, de monuments et de lieux dans le monde entier
• Itinéraires multi-modaux pour la conduite, la marche et le vélo avec trafic en temps réel
• Matrices de temps de trajet pour analyser l'accessibilité et optimiser la logistique
• Optimisation d'itinéraires pour trouver l'ordre de visite optimal pour plusieurs arrêts (problème du voyageur de commerce)
• Correspondance cartographique pour aligner les traces GPS sur le réseau routier afin d'obtenir une visualisation propre des itinéraires
• Génération d'isochrones pour visualiser les zones accessibles dans des contraintes de temps ou de distance spécifiques
• Rendu cartographique interactif en direct (render_map_tool) pour afficher les itinéraires, les résultats de recherche et vos propres GeoJSON personnalisés sur une vraie carte Mapbox GL JS directement dans le chat
• Images cartographiques statiques pour créer des représentations visuelles de lieux, d'itinéraires et de données géographiques
• Calculs géospatiaux hors ligne pour la distance, la surface, le relèvement, les zones tampons et l'analyse spatiale sans nécessiter d'appels API

Que vous construisiez un assistant de voyage IA, un optimiseur logistique, un système de recommandation basé sur la localisation ou toute application qui doit comprendre le « où », le serveur MCP Mapbox fournit l'intelligence spatiale pour y parvenir. Vous pouvez également l'activer sur des clients populaires comme Claude Desktop et VS Code. Voir ci-dessous pour plus de détails

Utilisation

Un jeton d'accès Mapbox est requis pour utiliser ce serveur MCP.

Point de terminaison MCP hébergé

Pour un accès rapide, vous pouvez utiliser notre point de terminaison MCP hébergé :

Point de terminaison : https://mcp.mapbox.com/mcp

Pour des instructions de configuration détaillées pour différents clients et l'utilisation de l'API, consultez le Guide du serveur MCP hébergé.

Pour obtenir un jeton d'accès Mapbox :

1. Inscrivez-vous pour un compte Mapbox gratuit sur mapbox.com/signup
2. Accédez à votre page de compte
3. Créez un nouveau jeton ou utilisez le jeton public par défaut

Pour plus d'informations sur les jetons d'accès Mapbox, consultez la documentation Mapbox sur les jetons d'accès.

Guides d'intégration

Pour des instructions de configuration détaillées pour différentes intégrations, consultez les guides suivants :

• Configuration de Claude Desktop - Instructions pour configurer Claude Desktop afin de fonctionner avec ce serveur MCP
• Configuration de Goose - Configuration du framework d'agent IA Goose
• Configuration de VS Code - Configuration d'un environnement de développement dans Visual Studio Code
• Configuration de l'IDE Cursor AI - Configuration d'un environnement de développement dans l'IDE Cursor AI
• Intégration Smolagents - Exemple montrant comment connecter les agents IA Smolagents aux outils de Mapbox
• Importation directe des outils - Utilisez les outils Mapbox dans vos propres applications sans exécuter le serveur MCP
• Guide render_map_tool - La primitive de visualisation cartographique : schéma complet de la charge utile et comment rendre vos propres données de manière autonome, sans aucun autre outil Mapbox
• Élicitations - Comment search_and_geocode_tool et directions_tool demandent à l'utilisateur de lever l'ambiguïté sur les résultats ou de choisir un itinéraire, et comment ils se replient gracieusement lorsque le client ne le prend pas en charge

Exemples de prompts

Essayez ces prompts avec Claude Desktop ou d'autres clients MCP après la configuration :

Ancrage de localisation

Pour les requêtes centrées sur les coordonnées — « qu'y a-t-il près de moi », « quel quartier est-ce », « qu'est-ce qui est accessible en N minutes » — utilisez ground_location_tool. Il compose le géocodage inverse, la recherche par catégorie et l'isochrone en un seul appel, en choisissant adaptativement la bonne stratégie en fonction de la requête, et renvoie des enregistrements typés (noms, adresses, coordonnées, distances, polygones d'accessibilité) avec des citations.

Chacun des quatre prompts ci-dessous exerce une stratégie différente en un seul appel d'outil :

• Quartier — « Quel quartier est 47.6097, -122.3408, et qu'y a-t-il autour de moi ? »
• POI — « Cafés à moins de 10 minutes à pied de 40.7580, -73.9855 »
• Région — « Que puis-je atteindre en 15 minutes à pied depuis 37.7749, -122.4194 ? »
• Itinéraire — « Point routable le plus proche pour déposer quelqu'un à 34.0522, -118.2437 »

Découverte de lieux

• « Trouvez des cafés à distance de marche de l'Empire State Building »
• « Je veux aller de Seattle à Portland, y a-t-il un Starbucks en chemin ? »
• « Montrez-moi les stations-service le long de l'itinéraire de Boston à New York »
• « Quels restaurants se trouvent près de Times Square ? »

Navigation et voyage

• « Obtenez l'itinéraire en voiture de LAX à Hollywood avec le trafic actuel »
• « Combien de temps faudrait-il pour marcher de Central Park à Times Square ? »
• « Calculez le temps de trajet de mon hôtel (Four Seasons) à l'aéroport JFK en taxi aux heures de pointe »

Visualisation et cartes

• « À l'aide de l'outil de rendu cartographique Mapbox, montrez-moi l'itinéraire du Golden Gate Bridge à Union Square à San Francisco » — rend un itinéraire interactif en direct sur une vraie carte Mapbox
• « Créez une image cartographique montrant l'itinéraire du Golden Gate Bridge à Fisherman's Wharf avec des marqueurs aux deux endroits »
• « Montrez-moi une vue satellite de Manhattan avec les principaux points de repère marqués »
• « Générez une carte mettant en évidence tous les Starbucks à moins d'un mile du centre-ville de Seattle »
• « Affichez un polygone de remplissage sur ces coordonnées : [...], avec un marqueur étiqueté "Entrepôt" à [...] » — rend votre propre GeoJSON directement via render_map_tool, aucun autre outil Mapbox nécessaire

Analyse et planification

• « Montrez-moi les zones accessibles en 30 minutes en voiture du centre-ville de Portland »
• « Calculez une matrice de temps de trajet entre ces 3 emplacements d'hôtels (Marriott, Sheraton et Hilton) et le centre de congrès de Denver »
• « Trouvez l'itinéraire optimal visitant ces 3 attractions touristiques (Golden Gate, Musical Stairs et Fisherman's Wharf) à San Francisco »
• « Optimisez un itinéraire de livraison pour ces 8 adresses : [liste d'adresses] »

GPS et correspondance d'itinéraires

• « Nettoyez cette trace GPS et montrez l'itinéraire réel sur les routes : [liste de coordonnées avec horodatages] »
• « Alignez ce trajet à vélo enregistré sur le réseau cyclable : [coordonnées GPS] »
• « Faites correspondre cet itinéraire en voiture au réseau routier et montrez les niveaux de congestion du trafic »

Calculs géospatiaux hors ligne

• « Quelle est la distance en miles entre ces deux coordonnées ? »
• « Calculez la surface de ce polygone en kilomètres carrés »
• « Le point à 37.7749°N, 122.4194°O est-il à l'intérieur de ce polygone de zone de service ? »
• « Quel est le relèvement de San Francisco à New York ? »
• « Trouvez le point médian entre Londres et Paris »
• « Créez une zone tampon de 5 miles autour de cet emplacement »
• « Calculez le centroïde de cette limite de quartier »
• « Quelle est la boîte englobante pour ces coordonnées d'itinéraire ? »
• « Simplifiez ce polygone complexe pour réduire le nombre de points »

Conseils pour de meilleurs résultats

• Soyez précis sur les lieux (utilisez des adresses complètes ou des noms de points de repère)
• Précisez votre méthode de déplacement préférée (conduite, marche, vélo)
• Incluez des contraintes de temps lorsque c'est pertinent (« aux heures de pointe », « à 15 h »)
• Demandez des formats de sortie spécifiques lorsque nécessaire (« comme image cartographique », « au format JSON »)

Exemples détaillés : Consultez examples/search-along-route.md pour des exemples complets du prompt de recherche le long d'un itinéraire avec différents cas d'utilisation et instructions de test avec MCP Inspector.

Ressources

Le serveur MCP expose des données de référence statiques sous forme de ressources MCP. Les ressources fournissent un accès en lecture seule aux données que les clients peuvent référencer directement sans effectuer d'appels d'outils.

Ressources disponibles

Ressource des catégories Mapbox

Modèle d'URI : mapbox://categories ou mapbox://categories/{language}

Accédez à la liste complète des identifiants de catégories disponibles pour une utilisation avec l'outil de recherche par catégorie. Les catégories peuvent être utilisées pour filtrer les résultats de recherche par type (par exemple, « restaurant », « hôtel », « station-service »).

Exemples :

• mapbox://categories - Liste de catégories par défaut (anglais)
• mapbox://categories/ja - Noms de catégories en japonais
• mapbox://categories/es - Noms de catégories en espagnol

Accès aux ressources :

• Clients avec prise en charge native des ressources MCP : Utilisez la méthode de protocole MCP resources/read
• Clients sans prise en charge des ressources : Utilisez resource_reader_tool avec l'URI de la ressource

Aperçus cartographiques riches (render_map_tool)

Chaque outil géospatial de ce serveur (itinéraires, isochrones, recherche, et plus) peut afficher son résultat sous forme de carte Mapbox GL JS interactive en direct via render_map_tool — la primitive de visualisation unique du serveur. Elle rend via le protocole MCP Apps (@modelcontextprotocol/ext-apps) sous forme de panneau HTML autonome directement dans le chat, avec une bascule plein écran, dans les clients pris en charge :

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

Vous n'avez besoin d'aucun autre outil de ce serveur pour l'utiliser. render_map_tool accepte également directement du GeoJSON composé à la main — vos propres polygones, marqueurs et itinéraires — sans dépendance à directions_tool, isochrone_tool ou tout autre appel API Mapbox. Consultez le guide complet de render_map_tool pour le schéma de la charge utile et un exemple autonome complet.

Si vous avez besoin d'une image statique garantie dans des clients sans prise en charge de MCP Apps, utilisez static_map_image_tool à la place — il renvoie un PNG/JPEG encodé en base64 que tous les clients peuvent afficher.

CLIENT_NEEDS_RESOURCE_FALLBACK

Outils de repli de ressources (adhésion volontaire pour les clients non conformes)

Les ressources sont une fonctionnalité MCP de base prise en charge par la plupart des clients (Claude Desktop, VS Code, MCP Inspector, etc.). Cependant, certains clients (comme smolagents) ne prennent pas du tout en charge les ressources. Pour ces clients, le serveur peut fournir des « outils de repli de ressources » qui fournissent le même contenu que les ressources mais via des appels d'outils.

Outils de repli :

• resource_reader_tool - Repli générique pour lire n'importe quelle ressource par URI
• category_list_tool - Fournit l'accès à la liste des catégories (mapbox://categories)

Par défaut, ces outils ne sont PAS inclus (en supposant que votre client prend en charge les ressources). Si votre client ne prend pas en charge les ressources, activez les outils de repli :

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Quand définir ceci :

• ✅ Définissez sur true si vous utilisez smolagents ou d'autres clients sans prise en charge des ressources
• ❌ Laissez non défini (par défaut) si vous utilisez Claude Desktop, VS Code, MCP Inspector ou tout client capable de gérer les ressources
• ❌ Laissez non défini en cas de doute (la plupart des clients prennent en charge les ressources)

Outils

Outils utilitaires

Outil de lecture de ressources

Fournit l'accès aux ressources MCP pour les clients qui ne prennent pas en charge l'API de ressources MCP native. Utilisez cet outil pour lire des ressources comme la liste des catégories.

Paramètres :

• uri : L'URI de la ressource à lire (par exemple, mapbox://categories, mapbox://categories/ja)

Exemple d'utilisation :

• Lire les catégories par défaut : {"uri": "mapbox://categories"}
• Lire les catégories en japonais : {"uri": "mapbox://categories/ja"}

Remarque : Si votre client MCP prend en charge les ressources natives, préférez utiliser l'API de ressources directement pour de meilleures performances.

Outils géospatiaux hors ligne

Ces outils effectuent des calculs géospatiaux entièrement hors ligne sans nécessiter d'appels API Mapbox. Ils utilisent Turf.js pour des calculs géographiques précis et fonctionnent partout, même sans connexion Internet.

Outil de distance

Calculez la distance entre deux coordonnées géographiques à l'aide de la formule de Haversine.

Caractéristiques :

• Prend en charge plusieurs unités : kilomètres, miles, mètres, pieds, miles nautiques
• Calcul précis de la distance du grand cercle
• Aucun appel API requis

Exemple d'utilisation : « Quelle est la distance entre San Francisco (37.7749°N, 122.4194°O) et New York (40.7128°N, 74.0060°O) ? »

Outil de points dans un polygone

Testez un ou plusieurs points contre un polygone ou un multipolygone, en ne renvoyant que ceux à l'intérieur. Gère un seul point ou un lot en un seul appel.

Caractéristiques :

• Fonctionne avec des polygones complexes, y compris ceux avec des trous
• Prend en charge les multipolygones
• Teste par lots un nombre quelconque de points en un seul appel
• Utile pour le géorepérage, la validation de zones de livraison et la segmentation client

Exemple d'utilisation : « Parmi ces adresses de livraison, lesquelles se trouvent dans notre zone de service ? »

Outil de destination

Calcule un point de destination à partir d'un point de départ, d'un cap et d'une distance en utilisant un décalage géodésique (grand cercle).

Fonctionnalités :

• Décalage en ligne droite, pas un itinéraire routier
• Utile pour « trouver un point à 5 km au nord de X » ou pour construire des décalages de recherche
• Aucun appel API requis

Exemple d'utilisation : « Quel est le point à 10 km au nord-est de la Space Needle ? »

Outil de cap

Calcule la direction de la boussole (cap) d'une coordonnée à une autre.

Fonctionnalités :

• Renvoie le cap en degrés (0-360°)
• Fournit la direction cardinale (N, NE, E, SE, S, SO, O, NO)
• Utile pour la navigation et les requêtes directionnelles

Exemple d'utilisation : « Dans quelle direction dois-je aller pour me rendre d'ici à l'aéroport ? »

Outil de point médian

Trouve le point médian géographique entre deux coordonnées le long du trajet du grand cercle.

Fonctionnalités :

• Calcule le véritable point médian sur la surface incurvée de la Terre
• Utile pour suggérer des points de rencontre
• Gère correctement les calculs sur de longues distances

Exemple d'utilisation : « Quel est le point à mi-chemin entre San Francisco et New York ? »

Outil de centroïde

Calcule le centre géométrique (centroïde) d'un polygone ou d'un multipolygone.

Fonctionnalités :

• Fonctionne avec des formes complexes
• Renvoie la moyenne arithmétique de tous les points
• Utile pour placer des étiquettes ou des marqueurs

Exemple d'utilisation : « Où dois-je placer un marqueur pour cette limite de quartier ? »

Outil de superficie

Calcule la superficie d'un polygone.

Fonctionnalités :

• Prend en charge plusieurs unités : mètres carrés, kilomètres carrés, acres, hectares, miles carrés, pieds carrés
• Calcul précis de la superficie sur la surface de la Terre
• Fonctionne avec des polygones de toutes tailles

Exemple d'utilisation : « Quelle est la superficie de ce parc en acres ? »

Outil de boîte englobante

Calcule la boîte englobante minimale (bbox) qui contient une géométrie.

Fonctionnalités :

• Fonctionne avec les points, les lignes, les polygones et les multipolygones
• Renvoie [minLongitude, minLatitude, maxLongitude, maxLatitude]
• Utile pour les calculs de fenêtre d'affichage et l'indexation spatiale

Exemple d'utilisation : « Quelle est la boîte englobante de cet itinéraire ? »

Outil de tampon

Crée une zone tampon (polygone) autour d'un point, d'une ligne ou d'un polygone.

Fonctionnalités :

• Prend en charge plusieurs unités de distance
• Crée des tampons circulaires autour des points
• Utile pour l'analyse de proximité et la création de zones d'influence

Exemple d'utilisation : « Montrez-moi une zone tampon de 5 km autour de cet emplacement »

Outil de simplification

Réduit le nombre de sommets d'une ligne ou d'un polygone à l'aide de l'algorithme de Douglas-Peucker.

Fonctionnalités :

• Tolérance configurable pour le niveau de détail
• Préserve la forme globale tout en réduisant la complexité
• Utile pour réduire la taille des fichiers et améliorer les performances de rendu
• Option pour maintenir la topologie (empêcher les auto-intersections)

Exemple d'utilisation : « Simplifiez cette limite complexe pour réduire le nombre de points »

Outil de longueur

Mesure la longueur totale d'une ligne définie par une série de coordonnées.

Fonctionnalités :

• Prend en charge les kilomètres, les miles, les mètres et les pieds
• Utile pour mesurer un itinéraire tracé, un chemin ou une limite sans appel API de routage

Exemple d'utilisation : « Quelle est la longueur de ce sentier de randonnée ? »

Outil convexe

Calcule l'enveloppe convexe d'un ensemble de points — le plus petit polygone convexe les contenant tous.

Fonctionnalités :

• Utile pour l'analyse de zone englobante ou l'estimation de la zone de couverture
• Fonctionne hors ligne sans appels API

Exemple d'utilisation : « Quel est le plus petit polygone qui contient tous ces emplacements de magasins ? »

Outil de point le plus proche

Trouve le point le plus proche dans une collection d'un point cible donné.

Fonctionnalités :

• Plus efficace que d'appeler distance_tool pour chaque candidat et de trier
• Utile pour trouver le magasin, l'arrêt ou le point de repère le plus proche d'un emplacement

Exemple d'utilisation : « Lequel de ces magasins est le plus proche de ma position actuelle ? »

Outil de point le plus proche sur une ligne

Accroche un point à la position la plus proche sur une ligne ou un itinéraire, renvoyant ce point et la distance qui le sépare.

Fonctionnalités :

• Utile pour « quel point de cet itinéraire est le plus proche de ma position ? » ou pour l'appariement cartographique sans appel API

Exemple d'utilisation : « Où suis-je le plus proche sur ce sentier de randonnée en ce moment ? »

Outils d'union, d'intersection et de différence

Combine ou compare deux polygones ou plus — union_tool les fusionne en une seule géométrie, intersect_tool trouve la zone qu'ils partagent, et difference_tool soustrait l'un de l'autre.

Fonctionnalités :

• Utile pour combiner des zones de service, trouver un chevauchement de couverture ou calculer des zones d'exclusion (par exemple « qu'est-ce qui est couvert par la zone A mais pas par la zone B ? »)
• Fonctionne entièrement hors ligne — aucun appel API requis
• Chacun renvoie une référence render_map_tool afin que le résultat puisse être visualisé directement

Exemple d'utilisation : « Combinez ces deux zones de livraison en une seule zone de couverture » / « Où ces deux isochrones se chevauchent-ils ? » / « Quelle partie de cette zone de service n'est pas couverte par notre isochrone de 15 minutes ? »

Outils API Mapbox

Outil de liste de catégories (obsolète)

⚠️ Obsolète : Utilisez plutôt le resource_reader_tool avec l'URI mapbox://categories, ou accédez directement à la ressource mapbox://categories si votre client prend en charge les ressources MCP.

Cet outil est maintenu pour la rétrocompatibilité avec les clients qui ne prennent pas en charge les ressources MCP ou l'outil resource_reader_tool.

Outil de matrice

Calcule les temps de trajet et les distances entre plusieurs points à l'aide de l'API Matrix Mapbox. Fonctionnalités :

• Calculs de routage efficaces un-à-plusieurs, plusieurs-à-un ou plusieurs-à-plusieurs
• Prise en charge de différents profils de déplacement (conduite avec trafic, conduite, marche, vélo)
• Spécification de l'heure de départ pour les calculs tenant compte du trafic
• Résumé de l'itinéraire avec des métriques de distance et de durée
• Contrôle de l'approche (bordure/sans restriction) et de la plage des caps de départ autorisés

Outil d'image statique

Génère des images cartographiques statiques à l'aide de l'API d'image statique Mapbox. Fonctionnalités :

• Styles de carte personnalisés (rues, extérieur, satellite, etc.)
• Dimensions d'image et niveaux de zoom réglables
• Prise en charge de plusieurs marqueurs avec des couleurs et des étiquettes personnalisées
• Options de superposition, y compris les polylignes et les polygones
• Ajustement automatique aux coordonnées spécifiées

Outil de recherche par catégorie

Effectue une recherche par catégorie à l'aide de l'API de recherche par catégorie Mapbox Search Box. Fonctionnalités :

• Recherche de points d'intérêt par catégorie (restaurants, hôtels, stations-service, etc.)
• Filtrage par proximité géographique
• Limites de résultats personnalisables
• Métadonnées riches pour chaque résultat
• Prise en charge de plusieurs langues

Outil de géocodage inversé

Effectue un géocodage inversé à l'aide de l'API de géocodage V6 Mapbox. Fonctionnalités :

• Convertit les coordonnées géographiques en adresses lisibles par l'homme
• Niveaux de détail personnalisables (rue, quartier, ville, etc.)
• Filtrage des résultats par type (adresse, point d'intérêt, quartier, etc.)
• Prise en charge de plusieurs langues
• Informations riches sur le contexte de l'emplacement

Outil d'emplacement au sol

Répond aux questions « qu'y a-t-il près de cette coordonnée » en un seul appel — nom du lieu, points d'intérêt à proximité et accessibilité en temps de trajet — à partir des données Mapbox en direct avec citations. Utilisez-le plutôt que d'enchaîner reverse_geocode_tool avec une recherche Web.

Fonctionnalités :

• Classe la requête (routage, contexte de quartier, recherche de points d'intérêt ou région/accessibilité) et ne récupère que les données pertinentes
• Recherche de points d'intérêt à proximité par catégorie, si demandé
• Résumé de l'accessibilité en temps de trajet (basé sur les isochrones)
• Renvoie une référence render_map_tool avec l'emplacement ancré et les points d'intérêt à proximité tracés

Exemple d'utilisation : « Dans quel quartier se trouve cette coordonnée, et y a-t-il des cafés à proximité ? »

Outil de détails de lieu

Récupère des informations détaillées sur un lieu spécifique à l'aide de son identifiant Mapbox — photos, heures d'ouverture, évaluations, numéros de téléphone et URL de sites Web. Utilisez après search_and_geocode_tool, category_search_tool ou reverse_geocode_tool pour obtenir plus de détails sur un résultat spécifique.

Exemple d'utilisation : « Parlez-moi davantage de ce premier résultat de café — heures d'ouverture, numéro de téléphone et site Web »

Outil d'itinéraires

Récupère les directions de routage à l'aide de l'API Directions Mapbox. Fonctionnalités :

• Prise en charge de différents profils de routage : conduite (avec trafic en direct ou typique), marche et vélo
• Itinéraire à partir de plusieurs points de passage (2 à 25 paires de coordonnées)
• Option d'itinéraires alternatifs
• Annotations d'itinéraire (distance, durée, vitesse, congestion)
• Options de planification :
  • Heure de départ future (depart_at) pour les profils de conduite et de conduite avec trafic
  • Heure d'arrivée souhaitée (arrive_by) pour le profil de conduite uniquement
• Optimisations spécifiques au profil :
  • Conduite : contraintes de dimensions du véhicule (hauteur, largeur, poids)
• Options d'exclusion pour le routage :
  • Exclusions courantes : traversiers, péages en espèces uniquement
  • Exclusions spécifiques à la conduite : péages, autoroutes, routes non pavées, tunnels, frontières de pays, frontières d'État
  • Exclusions de points personnalisées (jusqu'à 50 points géographiques à éviter)
• Format de sortie de géométrie GeoJSON

Outil d'isochrone

Calcule les zones accessibles dans des durées spécifiées à partir d'un emplacement à l'aide de l'API Isochrone Mapbox. Fonctionnalités :

• Prise en charge de différents profils de déplacement (conduite, marche, vélo)
• Temps de trajet ou distances personnalisables
• Génération de plusieurs contours (par exemple, plages de 15, 30, 45 minutes)
• Spécification facultative de l'heure de départ ou d'arrivée
• Personnalisation des couleurs pour la visualisation

Outil de recherche et de géocodage

Utilise le point de terminaison de l'API de recherche textuelle Mapbox Search Box pour alimenter la recherche et le géocodage de points d'intérêt, d'adresses, de lieux et de tout autre type pris en charge par cette API. Cet outil regroupe les fonctionnalités précédemment fournies par ForwardGeocodeTool et PoiSearchTool (des versions antérieures de ce serveur MCP) en un seul outil.

Outil d'appariement cartographique

Accroche les traces GPS au réseau routier à l'aide de l'API Map Matching Mapbox. Fonctionnalités :

• Convertit les traces GPS bruitées en itinéraires propres sur le réseau routier
• Prise en charge de différents profils de déplacement (conduite, conduite avec trafic, marche, vélo)
• Gère jusqu'à 100 paires de coordonnées par requête
• Horodatages facultatifs pour une précision améliorée basée sur la vitesse
• Rayons d'accrochage configurables pour différents niveaux de qualité GPS
• Annotations d'itinéraire (limites de vitesse, distance, durée, congestion du trafic)
• Plusieurs formats de sortie de géométrie (GeoJSON, polyligne)

Exemple d'utilisation : « Nettoyez cette trace GPS et accrochez-la aux routes : [coordonnées avec horodatages] »

Outil d'optimisation

Trouve l'itinéraire optimal à travers plusieurs emplacements à l'aide de l'API Optimization Mapbox. Fonctionnalités :

• Résout le problème du voyageur de commerce (TSP) pour 2 à 12 emplacements
• Prise en charge de différents profils de déplacement (conduite, conduite avec trafic, marche, vélo)
• Configuration flexible des points de départ et d'arrivée
• Optimisation d'itinéraire aller-retour ou aller simple
• Instructions de navigation étape par étape (facultatif)
• Annotations d'itinéraire (distance, durée, vitesse)
• Plusieurs formats de sortie de géométrie (GeoJSON, polyligne)

Exemple d'utilisation : « Trouvez l'itinéraire optimal pour visiter ces 5 arrêts : [liste d'adresses ou de coordonnées] »

Remarque : Une API V2 avec des fonctionnalités avancées (fenêtres de temps, contraintes de capacité, plusieurs véhicules) est disponible mais nécessite un accès bêta. L'implémentation V2 est incluse dans le codebase mais n'est pas enregistrée par défaut.

Développement

Inspection du serveur

Avec Node.js

# Run the built image
npm run inspect:build

Avec 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

Créer un nouvel outil

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

Publication d'une nouvelle version

# 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

Important : Le flux de travail de l'éditeur valide que les versions package.json et server.json correspondent à la version de publication. Sauter l'incrémentation de version ou la synchronisation du manifeste entraînera des échecs de publication.

Traçage OpenTelemetry

Ce serveur MCP inclut un traçage OpenTelemetry complet pour l'observabilité en production :

Démo rapide

# 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

Remarque : Le serveur charge automatiquement la configuration depuis votre fichier .env au démarrage. Le fichier .env.example inclut des exemples de configuration pour plusieurs plateformes d'observabilité.

Plateformes d'observabilité prises en charge

Exemples de configuration inclus dans .env.example pour :

Fournisseurs cloud :

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

Plateformes SaaS :

• 📊 Datadog
• 📊 New Relic
• 📊 Honeycomb
• 📊 Tout backend compatible OTLP

Configuration de production

Consultez docs/tracing.md pour les instructions complètes de configuration, notamment :

• 🔧 Guides de configuration spécifiques à chaque plateforme
• 📊 Configuration de l'authentification et des points de terminaison
• 🎯 Attributs de trace personnalisés et contexte
• 🚀 Optimisation des performances (surcharge minimale)
• 🔍 Dépannage et débogage

Fonctionnalités de traçage :

• ✅ Traçage du chargement de la configuration (chargement du fichier .env)
• ✅ Traçage automatique de l'exécution des outils
• ✅ Instrumentation des requêtes HTTP avec identifiants de corrélation CloudFront
• ✅ Exportateurs configurables (console, OTLP)
• ✅ Conception soucieuse de la sécurité (protection des données, validation JWT)
• ✅ Prêt pour la production (moins de 1 % de surcharge CPU)

Contribution

Nous accueillons favorablement les contributions au serveur MCP Mapbox ! Veuillez lire CONTRIBUTING.md avant de soumettre une demande d'extraction (pull request).

Normes et directives complètes :

• CONTRIBUTING.md - Pour commencer, processus de demande d'extraction, référence rapide
• Normes d'ingénierie (docs/engineering_standards.md) - Normes complètes de qualité du code, de tests, de documentation et de collaboration
• Guide Claude Code (CLAUDE.md) - Normes et modèles pour les contributeurs utilisant Claude Code
• Instructions pour les agents IA (AGENTS.md) - Guide pour d'autres assistants de codage IA (Cursor, Continue, Aider, etc.)
• Directives GitHub Copilot - Bonnes pratiques pour utiliser GitHub Copilot de manière responsable

Démarrage rapide pour les contributeurs

1. Forkez le dépôt et clonez votre fork
2. Installez les dépendances : npm install
3. Apportez vos modifications en suivant nos normes de codage
4. Exécutez les tests et le linting : npm test && npm run lint
5. Ajoutez des tests pour toute nouvelle fonctionnalité
6. Soumettez une demande d'extraction avec une description claire

Toutes les contributions doivent passer nos vérifications CI et notre processus de revue de code. Consultez docs/engineering_standards.md pour les exigences détaillées.

Utilisation des données et confidentialité

Quelles données sont envoyées aux API Mapbox

Lorsque vous utilisez les outils du serveur MCP, les données suivantes sont envoyées directement de votre environnement aux API Mapbox :

• Outils de géocodage : Texte d'adresse/localisation, coordonnées, filtres pays/région
• Outils de recherche : Requêtes de recherche, coordonnées de localisation pour la proximité, filtres de catégorie
• Outil d'itinéraire : Coordonnées de départ/arrivée, points de passage, préférences de routage, contraintes de véhicule
• Outil de matrice : Plusieurs paires de coordonnées, profil de déplacement, heures de départ
• Outil de carte statique : Coordonnées, niveau de zoom, préférences de style, informations sur les marqueurs
• Outil d'isochrone : Coordonnées d'origine, paramètres de temps/distance, profil de déplacement

Votre confidentialité

• Exécution locale : Tous les appels API sont effectués directement depuis votre environnement vers les API Mapbox
• Sécurité des jetons : Votre jeton API Mapbox reste sur votre machine locale et n'est jamais transmis ni stocké par ce serveur MCP
• Aucun stockage de données : Ce serveur MCP ne stocke, ne journalise ni ne collecte aucune de vos données ou requêtes API
• Communication directe : Il n'y a aucun serveur intermédiaire entre vous et les API Mapbox

Utilisation des données par des tiers

• La politique de confidentialité de Mapbox régit les données envoyées à leurs API : https://www.mapbox.com/legal/privacy/
• Utilisation de l'API : Les conditions standard de l'API Mapbox s'appliquent à toutes les requêtes effectuées via ces outils
• Conservation des données : Reportez-vous à la documentation de Mapbox pour leurs politiques de conservation des données

Support et contact

Pour les problèmes du serveur MCP

• E-mail : mcp-feedback@mapbox.com
• Problèmes GitHub : Signaler des bogues et demander des fonctionnalités

Pour les questions sur l'API Mapbox

• Support Mapbox : https://support.mapbox.com/
• Documentation : https://docs.mapbox.com/
• Statut de l'API : https://status.mapbox.com/

Engagement de maintenance

Ce serveur MCP est officiellement maintenu par Mapbox, Inc. Nous fournissons :

• Des mises à jour régulières pour les nouvelles fonctionnalités de l'API Mapbox
• Des corrections de bogues et des mises à jour de sécurité
• La compatibilité avec les dernières versions du protocole MCP
• Un support communautaire via les problèmes GitHub

---

Licence MIT