Mapbox

Serveur MCP Mapbox

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

Donnez à vos applications d’IA accès à l’intelligence géospatiale

Le serveur MCP Mapbox transforme n’importe quel agent ou application d’IA en système doté d’une compréhension géospatiale en lui donnant un accès fluide à la plateforme complète d’intelligence de localisation de Mapbox. Grâce à ce serveur, votre IA peut comprendre les lieux et raisonner à leur sujet, se déplacer dans le monde physique et accéder à de riches données géospatiales, notamment :

• Géocodage mondial pour convertir les adresses et les noms de lieux en coordonnées, et inversement
• Recherche de points d’intérêt (POI) parmi des millions d’entreprises, de monuments et de lieux dans le monde entier
• Calcul d’itinéraires multimodaux en voiture, à pied et à vélo, avec le 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 de plusieurs étapes (problème du voyageur de commerce)
• Map matching pour aligner les traces GPS sur le réseau routier et obtenir une visualisation claire des itinéraires
• Génération d’isochrones pour visualiser les zones accessibles dans des limites de temps ou de distance données
• Rendu de cartes interactives en direct (render_map_tool) pour afficher des itinéraires, des résultats de recherche et votre propre GeoJSON personnalisé sur une véritable carte Mapbox GL JS, directement dans la conversation
• Images de cartes 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 les distances, les superficies, les relèvements, les zones tampons et l’analyse spatiale, sans appels d’API

Que vous développiez un assistant de voyage IA, un outil d’optimisation logistique, un moteur de recommandation basé sur la localisation ou toute autre application qui doit comprendre « où », le serveur MCP Mapbox fournit l’intelligence spatiale nécessaire. Vous pouvez également l’activer dans des clients populaires comme Claude Desktop et VS Code. Consultez les détails ci-dessous.

Utilisation

Un jeton d’accès Mapbox est nécessaire 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 obtenir des instructions détaillées de configuration selon les différents clients et d’utilisation de l’API, consultez le Guide du serveur MCP hébergé.

Pour obtenir un jeton d’accès Mapbox :

1. Créez 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 en savoir plus sur les jetons d’accès Mapbox, consultez la documentation Mapbox sur les jetons d’accès.

Guides d’intégration

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

• Configuration de Claude Desktop - Instructions pour configurer Claude Desktop afin qu’il fonctionne 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 de Smolagents - Exemple montrant comment connecter des agents IA Smolagents aux outils Mapbox
• Importation directe des outils - Utilisez les outils Mapbox dans vos propres applications sans exécuter le serveur MCP
• Guide render_map_tool - Le composant de visualisation cartographique : schéma complet de la charge utile et instructions pour afficher vos propres données de manière autonome, sans aucun autre outil Mapbox
• Demandes de précision - Comment search_and_geocode_tool et directions_tool demandent à l’utilisateur de préciser les résultats ou de choisir un itinéraire, et comment ils gèrent élégamment les clients qui ne prennent pas cette fonctionnalité en charge

Exemples de requêtes

Après la configuration, essayez ces requêtes avec Claude Desktop ou d’autres clients MCP :

Repérage géographique

Pour les requêtes centrées sur les coordonnées — « qu’y a-t-il près de moi », « dans quel quartier suis-je », « qu’est-ce qui est accessible en N minutes » — utilisez ground_location_tool. Cet outil combine géocodage inversé, recherche par catégorie et isochrone en un seul appel. Il choisit de manière adaptative la stratégie appropriée selon la requête et renvoie des enregistrements typés (noms, adresses, coordonnées, distances, polygones d’accessibilité) avec des citations.

Chacune des quatre requêtes ci-dessous met en œuvre une stratégie différente en un seul appel d’outil :

• Quartier — « Dans quel quartier se trouve le point 47.6097, -122.3408, et qu’y a-t-il autour de moi ? »
• POI — « Cafés accessibles à pied en 10 minutes depuis le point 40.7580, -73.9855 »
• Zone — « Qu’est-ce qui est accessible à pied en 15 minutes depuis le point 37.7749, -122.4194 ? »
• Itinéraire — « Point accessible par la route le plus proche pour déposer quelqu’un au point 34.0522, -118.2437 »

Découverte de lieux

• « Trouve des cafés accessibles à pied depuis l’Empire State Building »
• « Je veux aller de Seattle à Portland. Y a-t-il un Starbucks en chemin ? »
• « Affiche les stations-service le long de l’itinéraire entre Boston et New York »
• « Quels restaurants se trouvent près de Times Square ? »

Navigation et déplacements

• « Calcule un itinéraire en voiture entre LAX et Hollywood en tenant compte du trafic actuel »
• « Combien de temps faudrait-il pour aller à pied de Central Park à Times Square ? »
• « Calcule le temps de trajet entre mon hôtel (Four Seasons) et l’aéroport JFK en taxi aux heures de pointe »

Visualisation et cartes

• « Avec l’outil de rendu cartographique Mapbox, indique-moi l’itinéraire entre le Golden Gate Bridge et Union Square à San Francisco » — affiche un itinéraire interactif en direct sur une véritable carte Mapbox
• « Crée une image de carte montrant l’itinéraire entre le Golden Gate Bridge et Fisherman’s Wharf, avec des marqueurs aux deux endroits »
• « Affiche une vue satellite de Manhattan avec les principaux monuments indiqués »
• « Génère une carte mettant en évidence tous les Starbucks situés à moins d’un mile du centre-ville de Seattle »
• « Affiche un polygone rempli sur ces coordonnées : [...], avec un marqueur intitulé ‘Entrepôt’ à [...] » — affiche directement votre propre GeoJSON via render_map_tool, sans nécessiter d’autre outil Mapbox

Analyse et planification

• « Affiche les zones accessibles en voiture en moins de 30 minutes depuis le centre-ville de Portland »
• « Calcule une matrice des temps de trajet entre ces 3 hôtels (Marriott, Sheraton et Hilton) et le centre de congrès de Denver »
• « Trouve l’itinéraire optimal passant par ces 3 attractions touristiques (Golden Gate, Musical Stairs et Fisherman’s Wharf) à San Francisco »
• « Optimise un itinéraire de livraison pour ces 8 adresses : [liste d’adresses] »

GPS et correspondance d’itinéraires

• « Nettoie cette trace GPS et affiche l’itinéraire réel sur les routes : [liste de coordonnées avec horodatages] »
• « Aligne cette sortie à vélo enregistrée sur le réseau cyclable : [coordonnées GPS] »
• « Fais correspondre cet itinéraire en voiture au réseau routier et affiche les niveaux de congestion »

Calculs géospatiaux hors ligne

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

Conseils pour obtenir de meilleurs résultats

• Soyez précis sur les lieux (utilisez des adresses complètes ou des noms de monuments)
• Indiquez votre mode de déplacement préféré (voiture, marche, vélo)
• Précisez les contraintes horaires lorsque c’est pertinent (« aux heures de pointe », « à 15 h »)
• Demandez des formats de sortie précis si nécessaire (« sous forme d’image de carte », « au format JSON »)

Exemples détaillés : Consultez examples/search-along-route.md pour découvrir des exemples complets de requêtes de recherche le long d’un itinéraire, couvrant différents cas d’utilisation, ainsi que des 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 donnent un accès en lecture seule à des données que les clients peuvent consulter directement, sans appeler d’outil.

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 l’outil de recherche par catégorie. Les catégories permettent de filtrer les résultats de recherche par type (par exemple, « restaurant », « hôtel », « station-service »).

Exemples :

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

Accès aux ressources :

• Clients prenant en charge nativement les ressources MCP : utilisez la méthode de protocole MCP resources/read
• Clients ne prenant pas en charge les ressources : utilisez resource_reader_tool avec l’URI de la ressource

Aperçus cartographiques enrichis (render_map_tool)

Chaque outil géospatial de ce serveur (itinéraires, isochrones, recherche, etc.) peut afficher son résultat sous forme de carte Mapbox GL JS interactive en direct via render_map_tool, l’unique composant de visualisation du serveur. Il effectue le rendu au moyen du protocole MCP Apps (@modelcontextprotocol/ext-apps), dans un panneau HTML autonome directement intégré à la conversation, avec un bouton Plein écran, dans les clients compatibles :

• 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 du GeoJSON composé manuellement — vos propres polygones, marqueurs et itinéraires — sans dépendre de directions_tool, de isochrone_tool ni d’aucun autre appel d’API Mapbox. Consultez le guide complet de render_map_tool pour découvrir le schéma de la charge utile et un exemple autonome complet.

Si vous avez besoin d’une image statique garantie dans les clients qui ne prennent pas en charge MCP Apps, utilisez plutôt static_map_image_tool : il renvoie un PNG/JPEG encodé en base64 que tous les clients peuvent afficher.

CLIENT_NEEDS_RESOURCE_FALLBACK

Outils de remplacement des ressources (activation facultative pour les clients non conformes)

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

Outils de remplacement :

• resource_reader_tool - Outil générique permettant de lire n’importe quelle ressource à partir de son URI
• category_list_tool - Donne accès à la liste des catégories (mapbox://categories)

Par défaut, ces outils ne sont PAS inclus (le client est supposé prendre en charge les ressources). Si votre client ne prend pas en charge les ressources, activez les outils de remplacement :

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Quand définir cette variable :

• ✅ Définissez-la sur true si vous utilisez smolagents ou d’autres clients qui ne prennent pas en charge les ressources
• ❌ Ne la définissez pas (valeur par défaut) si vous utilisez Claude Desktop, VS Code, MCP Inspector ou tout autre client prenant en charge les ressources
• ❌ Ne la définissez pas si vous avez un doute (la plupart des clients prennent en charge les ressources)

Outils

Outils utilitaires

Outil de lecture des ressources

Donne accès aux ressources MCP pour les clients qui ne prennent pas en charge l’API native des ressources MCP. Utilisez cet outil pour lire des ressources telles que la liste des catégories.

Paramètres :

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

Exemples 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, privilégiez l’API des 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 aux API Mapbox. Ils utilisent Turf.js pour effectuer des calculs géographiques précis et fonctionnent partout, même sans connexion Internet.

Outil de calcul de distance

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

Fonctionnalités :

• Prend en charge plusieurs unités : kilomètres, miles, mètres, pieds et milles marins
• Calcul précis de la distance orthodromique
• Aucun appel d’API nécessaire

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

Outil de recherche de points dans un polygone

Teste un ou plusieurs points par rapport à un polygone ou à un multipolygone et ne renvoie que ceux qui se trouvent à l’intérieur. Traite un point unique ou un lot de points en un seul appel.

Fonctionnalités :

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

Exemple d’utilisation : « Lesquelles de ces adresses de livraison se trouvent dans notre zone de service ? »

Outil 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, et non un itinéraire
• Utile pour « trouver un point situé à 5 km au nord de X » ou créer des décalages de recherche
• Aucun appel d’API requis

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

Outil Bearing

Calcule la direction de la boussole (le 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, SW, W, NW)
• Utile pour la navigation et les requêtes directionnelles

Exemple d’utilisation : « Dans quelle direction dois-je aller pour rejoindre l’aéroport d’ici ? »

Outil Midpoint

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

Fonctionnalités :

• Calcule le véritable point médian à la surface courbe de la Terre
• Utile pour suggérer un lieu de rendez-vous
• 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 Centroid

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 Area

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 à 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 Bounding Box

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

Fonctionnalités :

• Fonctionne avec des points, des lignes, des polygones et des 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 Buffer

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 zones tampons circulaires autour des points
• Utile pour l’analyse de proximité et la création de zones d’influence

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

Outil Simplify

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 régler le niveau de détail
• Préserve la forme générale tout en réduisant la complexité
• Utile pour réduire la taille des fichiers et améliorer les performances de rendu
• Option permettant de préserver la topologie (éviter les auto-intersections)

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

Outil Length

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, un chemin ou une limite tracés sans appel à une API de calcul d’itinéraire

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

Outil Convex

Calcule l’enveloppe convexe d’un ensemble de points — le plus petit polygone convexe qui les contient tous.

Fonctionnalités :

• Utile pour l’analyse de zones englobantes ou l’estimation d’une zone de couverture
• Fonctionne hors ligne, sans appel d’API

Exemple d’utilisation : « Quel est le plus petit polygone contenant tous ces emplacements de magasins ? »

Outil Nearest Point

Trouve le point le plus proche d’un point cible dans une collection.

Fonctionnalités :

• Plus efficace que d’appeler distance_tool pour chaque candidat, puis de trier les résultats
• 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 Nearest Point on Line

Projette un point sur la position la plus proche d’une ligne ou d’un itinéraire, puis renvoie ce point et la distance qui le sépare du point d’origine.

Fonctionnalités :

• Utile pour répondre à des questions comme « Quel point de cet itinéraire est le plus proche de ma position ? » ou pour faire de l’appariement cartographique sans appel d’API

Exemple d’utilisation : « À quel endroit de ce sentier de randonnée suis-je le plus proche en ce moment ? »

Outils Union, Intersect et Difference

Combinent ou comparent 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 :

• Utiles pour combiner des zones de service, trouver les chevauchements 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 ? »)
• Fonctionnent entièrement hors ligne — aucun appel d’API requis
• Chacun renvoie une référence render_map_tool afin que le résultat puisse être visualisé directement

Exemple d’utilisation : « Combine 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 de l’API Mapbox

Outil Category List (obsolète)

⚠️ Obsolète : utilisez resource_reader_tool avec l’URI mapbox://categories à la place, ou accédez directement à la ressource mapbox://categories si votre client prend en charge les ressources MCP.

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

Outil Matrix

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

• Calculs d’itinéraires efficaces d’un point à plusieurs, de plusieurs points à un ou de plusieurs points à plusieurs
• Prise en charge de différents profils de déplacement (driving-traffic, driving, walking, cycling)
• Spécification de l’heure de départ pour les calculs tenant compte du trafic
• Résumé de l’itinéraire avec des mesures de distance et de durée
• Contrôle de l’approche (bordure/tout accès) et de la plage des caps de départ autorisés

Outil Static image

Génère des images cartographiques statiques à l’aide de l’API Mapbox Static Images. Fonctionnalités :

• Styles de carte personnalisés (rues, plein air, satellite, etc.)
• Dimensions d’image et niveaux de zoom réglables
• Prise en charge de plusieurs marqueurs avec des couleurs et des libellés personnalisés
• Options de superposition, notamment des polylignes et des polygones
• Ajustement automatique aux coordonnées spécifiées

Outil Category search

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 selon la proximité géographique
• Limite de résultats personnalisable
• Métadonnées détaillées pour chaque résultat
• Prise en charge de plusieurs langues

Outil Reverse geocoding

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

• Convertit des coordonnées géographiques en adresses lisibles
• Niveaux de détail personnalisables (rue, quartier, ville, etc.)
• Filtrage des résultats par type (adresse, poi, quartier, etc.)
• Prise en charge de plusieurs langues
• Informations détaillées sur le contexte géographique

Outil Ground location

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

Fonctionnalités :

• Classe la requête (itinéraire, contexte du quartier, recherche de POI ou région/accessibilité) et récupère uniquement les données pertinentes
• Recherche de POI à proximité par catégorie, si demandé
• Résumé de l’accessibilité selon le temps de trajet (basé sur des isochrones)
• Renvoie une référence render_map_tool contenant l’emplacement contextualisé et les POI à proximité représentés sur une carte

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

Outil Place details

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

Exemple d’utilisation : « Donne-moi plus d’informations sur le premier café trouvé — horaires, numéro de téléphone et site Web »

Outil Directions

Récupère des itinéraires à l’aide de l’API Mapbox Directions. Fonctionnalités :

• Prise en charge de différents profils d’itinéraire : conduite (avec trafic en temps réel ou habituel), marche et vélo
• Itinéraire passant par 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 driving et driving-traffic
  • Heure d’arrivée souhaitée (arrive_by) pour le profil driving uniquement
• Optimisations propres à chaque profil :
  • Conduite : contraintes liées aux dimensions du véhicule (hauteur, largeur, poids)
• Options d’exclusion pour le calcul d’itinéraire :
  • Exclusions courantes : traversées en ferry, péages en espèces uniquement
  • Exclusions propres à la conduite : péages, autoroutes, routes non revêtues, tunnels, frontières nationales, frontières entre États
  • Exclusions de points personnalisées (jusqu’à 50 points géographiques à éviter)
• Format de sortie de la géométrie GeoJSON

Outil Isochrone

Calcule les zones accessibles depuis un emplacement dans un délai donné à l’aide de l’API Mapbox Isochrone. Fonctionnalités :

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

Outil Search and geocode

Utilise le point de terminaison Text Search API de Mapbox Search Box pour rechercher et géocoder des POI, des adresses, des lieux et tout autre type pris en charge par cette API. Cet outil regroupe les fonctionnalités auparavant fournies par ForwardGeocodeTool et PoiSearchTool (dans les versions précédentes de ce serveur MCP) en un seul outil.

Outil Map matching

Projette des traces GPS sur le réseau routier à l’aide de l’API Mapbox Map Matching. Fonctionnalités :

• Convertit des traces GPS bruitées en itinéraires propres sur le réseau routier
• Prise en charge de différents profils de déplacement (driving, driving-traffic, walking, cycling)
• Jusqu’à 100 paires de coordonnées par requête
• Horodatages facultatifs pour améliorer la précision en fonction de la vitesse
• Rayons d’accrochage configurables selon la qualité du GPS
• Annotations d’itinéraire (limites de vitesse, distance, durée, congestion du trafic)
• Plusieurs formats de sortie géométrique (GeoJSON, polyline)

Exemple d’utilisation : « Nettoie cette trace GPS et projette-la sur les routes : [coordonnées avec horodatages] »

Outil Optimization

Trouve l’itinéraire optimal passant par plusieurs emplacements à l’aide de l’API Mapbox Optimization. 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 (driving, driving-traffic, walking, cycling)
• Configuration flexible des points de départ et d’arrivée
• Optimisation des trajets en boucle ou à sens unique
• Instructions de navigation virage par virage (facultatif)
• Annotations d’itinéraire (distance, durée, vitesse)
• Plusieurs formats de sortie géométrique (GeoJSON, polyline)

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

Remarque : une API V2 dotée de fonctionnalités avancées (fenêtres horaires, contraintes de capacité, véhicules multiples) est disponible, mais nécessite un accès bêta. L’implémentation V2 est incluse dans la base de code, mais n’est pas enregistrée par défaut.

Outil Feedback

Envoie les commentaires d’un utilisateur sur l’application ou l’agent à son développeur, via l’API Mapbox Feedback (Public Preview). Les commentaires sont associés au compte propriétaire du jeton d’accès. Ainsi, lorsque vous créez une application ou un agent sur ce serveur avec votre propre jeton, les commentaires de vos utilisateurs apparaissent dans le même flux que les rapports de Feedback Agent de vos applications, et vous pouvez les consulter dans Feedback Explorer. Cet outil ne signale pas de problèmes à Mapbox. Comme Feedback Agent, il sert à recueillir tout commentaire sur votre produit susceptible de vous aider à comprendre les besoins des utilisateurs, par exemple :

• Un lieu qui a fermé, dont les informations sont incorrectes ou qui se trouve au mauvais endroit
• Un lieu ou une adresse introuvable
• Une route fermée, une limitation de vitesse incorrecte ou des informations erronées sur la circulation
• Un itinéraire comportant un virage ou une entrée interdits, ou aucun itinéraire
• Un problème concernant l'application elle-même, comme un bogue ou une suggestion (application_issue)

L'outil envoie le texte du signalement, une catégorie et l'emplacement, puis renvoie l'identifiant et le statut de l'élément. L'emplacement est facultatif pour les signalements qui ne concernent pas un lieu ; l'API l'exige, donc l'outil envoie 0, 0, comme le recommande actuellement l'équipe de l'API Feedback. Rien n'est envoyé sans l'accord de l'utilisateur : les clients qui prennent en charge l'élicitation affichent d'abord une demande de confirmation, et la description de l'outil demande au modèle de confirmer dans la conversation dans tous les autres cas.

L'API Feedback est gratuite pendant la Public Preview. À la disponibilité générale, Feedback Agent facture 0,02 $ par signalement. Pour éviter de signaler deux fois le même problème, avant l'envoi, l'outil vérifie les signalements du compte datant des 30 derniers jours. Si un signalement de la même catégorie, situé à moins de 50 m, est toujours en attente d'examen (les signalements sans emplacement ne sont pas vérifiés), l'outil renvoie ce signalement au lieu d'en envoyer un nouveau. L'API Feedback ne répertorie que les signalements du compte, elle ne peut donc pas détecter ceux d'autres comptes. send_anyway: true ignore cette vérification lorsque l'utilisateur indique que son signalement concerne un autre problème.

Prérequis : le jeton d'accès doit disposer de la portée user-feedback:write pour envoyer un signalement et de la portée user-feedback:read pour vérifier les doublons. Sans la portée d'écriture, l'outil renvoie une erreur l'indiquant. Sans la portée de lecture, il envoie le signalement sans vérification et le précise dans le résultat. Pour exclure l'outil, démarrez le serveur avec --disable-tools feedback_tool.

Exemple d'utilisation : « Blue Bottle, sur Mint St, a fermé l'année dernière. Peux-tu envoyer ce signalement ? »

Outil de signalement

Envoie à l'équipe Mapbox qui le développe des commentaires sur le serveur MCP Mapbox lui-même : un bogue, un outil qui a fourni un résultat erroné ou déroutant, une fonctionnalité manquante ou une suggestion. Le signalement est effectué au nom du compte de Mapbox, et non du vôtre ; aucune portée de jeton supplémentaire n'est donc nécessaire. Il ne peut pas être consulté ni retiré par la suite. Cet outil ne sert pas à signaler des données cartographiques, des lieux ou des itinéraires erronés.

Le serveur ajoute à la fin du texte sa version, le nom et la version du client, ainsi que l'outil concerné par le commentaire. Rien n'est envoyé sans l'accord de l'utilisateur : les clients qui prennent en charge l'élicitation affichent d'abord une demande de confirmation, et la description de l'outil demande au modèle de confirmer dans la conversation dans tous les autres cas.

L'outil utilise le point de terminaison ajouté par l'équipe de l'API Feedback pour la commande mapbox report de Mapbox CLI. Pour exclure l'outil, démarrez le serveur avec --disable-tools report_tool.

Exemple d'utilisation : « La carte n'a dessiné aucune de mes isochrones. Peux-tu en informer l'équipe MCP Mapbox ? »

Outil de liste des jetons publics

Répertorie les jetons d'accès publics (pk.) du compte, pour un agent qui crée une page Web ou une application en dehors de la conversation et qui charge Mapbox GL JS ou appelle les API Mapbox depuis le navigateur. Dans la conversation, render_map_tool n'a pas besoin de jeton. Chaque jeton est accompagné de son nom, de l'indication précisant s'il s'agit du jeton par défaut, de ses restrictions d'URL et de ses portées.

Transmettez site_url (l'adresse où la page sera exécutée) ; si le compte en possède un, l'outil recommande un jeton restreint à cette URL. Sinon, il recommande le jeton public par défaut et précise qu'un site publié devrait utiliser un jeton restreint à une URL, avec un lien pour en créer un. Toute personne qui copie un jeton public sans restriction peut l'utiliser, et l'utilisation est facturée au compte.

L'outil ne renvoie jamais de jetons secrets ou temporaires et ne peut pas créer de jetons (cela nécessite tokens:write ; le create_token_tool du serveur DevKit s'en charge).

Prérequis : la liste nécessite la portée tokens:read, la même que celle utilisée par la carte intégrée à la conversation pour trouver le jeton public par défaut. Avec un jeton d'accès pk., ou si la liste ne peut pas être récupérée sur le serveur à l'aide de son propre MAPBOX_ACCESS_TOKEN et que MAPBOX_PUBLIC_TOKEN est défini, l'outil renvoie ce jeton à la place. Un appelant utilisant son propre jeton bearer (le serveur hébergé) ne reçoit jamais MAPBOX_PUBLIC_TOKEN, et un jeton restreint à d'autres URL n'est jamais recommandé. Pour exclure l'outil, démarrez le serveur avec --disable-tools list_public_tokens_tool.

Exemple d'utilisation : « Crée une page d'une seule page qui affiche les trois emplacements de nos magasins sur une carte Mapbox. »

Développement

Inspecter le 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)

Publier 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 workflow de publication vérifie que les versions de package.json et server.json correspondent à la version publiée. Omettre la mise à jour de version ou la synchronisation du manifeste entraînera l'échec de la publication.

Traçage OpenTelemetry

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

Démonstration 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 : au démarrage, le serveur charge automatiquement la configuration depuis votre fichier .env. Le fichier .env.example contient 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 avec OTLP

Configuration de production

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

• 🔧 Guides de configuration propres à chaque plateforme
• 📊 Configuration de l'authentification et des points de terminaison
• 🎯 Attributs de trace et contexte personnalisés
• 🚀 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 les identifiants de corrélation CloudFront
• ✅ Exportateurs configurables (console, OTLP)
• ✅ Sécurité renforcée (protection des données, validation JWT)
• ✅ Prêt pour la production (moins de 1 % de surcharge CPU)

Contributions

Nous accueillons les contributions au serveur MCP Mapbox ! Veuillez lire CONTRIBUTING.md avant de soumettre une pull request.

Normes et directives complètes :

• CONTRIBUTING.md - Premiers pas, processus de PR, aide-mémoire
• 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 destinés aux contributeurs utilisant Claude Code
• Instructions pour les agents IA (AGENTS.md) - Guide destiné aux autres assistants de programmation 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. Créez un fork du dépôt et clonez-le
2. Installez les dépendances : npm install
3. Effectuez vos modifications en respectant nos normes de codage
4. Exécutez les tests et l'analyse statique : npm test && npm run lint
5. Ajoutez des tests pour toute nouvelle fonctionnalité
6. Soumettez une pull request accompagnée d'une description claire

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

Utilisation des données et confidentialité

Données envoyées aux API Mapbox

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

• Outils de géocodage : texte d'adresse ou d'emplacement, coordonnées, filtres de pays ou de région
• Outils de recherche : requêtes de recherche, coordonnées d'emplacement pour la proximité, filtres de catégorie
• Outil d'itinéraire : coordonnées de départ et d'arrivée, points de passage, préférences d'itinéraire, contraintes liées au 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 durée ou de distance, profil de déplacement

Votre confidentialité

• Exécution locale : tous les appels d'API sont effectués directement depuis votre environnement vers les API Mapbox
• Sécurité des jetons : votre jeton d'API Mapbox reste sur votre machine locale et n'est jamais transmis à ce serveur MCP ni stocké par celui-ci
• Aucun stockage de données : ce serveur MCP ne stocke, ne consigne ni ne collecte aucune de vos données ou requêtes d'API
• Communication directe : aucun serveur intermédiaire ne se trouve 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 à ses API : https://www.mapbox.com/legal/privacy/
• Utilisation des API : les conditions standard des API Mapbox s'appliquent à toutes les requêtes effectuées avec ces outils
• Conservation des données : consultez la documentation de Mapbox pour connaître ses politiques de conservation des données

Assistance et contact

Problèmes liés au serveur MCP

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

Questions sur les API Mapbox

• Assistance Mapbox : https://support.mapbox.com/
• Documentation : https://docs.mapbox.com/
• État des 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 des API Mapbox
• Des corrections de bogues et des mises à jour de sécurité
• La compatibilité avec les dernières versions du protocole MCP
• Une assistance communautaire via les problèmes GitHub

---

Licence MIT