Mapbox

oficial

Desbloquea inteligencia geoespacial a través de las APIs de Mapbox como geocodificación, búsqueda de POI, direcciones, isocronas y más.

GitHub
370

¿Qué puedes hacer con Mapbox MCP?

  • Geocodificar y buscar lugares — Convierte direcciones en coordenadas o encuentra puntos de interés, como cafeterías y gasolineras, con search_and_geocode_tool.
  • Obtener indicaciones — Obtén rutas en coche, a pie o en bicicleta con información del tráfico, alternativas y exclusiones mediante directions_tool.
  • Encontrar áreas accesibles — Genera polígonos de isócronas que muestran qué lugares se pueden alcanzar en un tiempo o una distancia determinados con isochrone_tool.
  • Ubicar una coordenada — Pregunta en qué barrio se encuentra una coordenada, qué puntos de interés hay cerca y qué lugares son accesibles, todo en una sola llamada con ground_location_tool.
  • Mostrar mapas en el chat — Muestra rutas, resultados de búsqueda o GeoJSON personalizado en un mapa interactivo en tiempo real con render_map_tool.
  • Consultar categorías — Consulta la lista de ID de categorías en inglés, japonés o español mediante mapbox://categories.

Documentación

Servidor MCP de Mapbox

npm version

Servidor Node.js que implementa Model Context Protocol (MCP) para las API de Mapbox.

Desbloquea la inteligencia geoespacial para tus aplicaciones de IA

El servidor MCP de Mapbox transforma cualquier agente o aplicación de IA en un sistema con conciencia geoespacial, al proporcionar acceso fluido a la completa plataforma de inteligencia de ubicación de Mapbox. Con este servidor, tu IA puede comprender y razonar sobre lugares, navegar por el mundo físico y acceder a datos geoespaciales enriquecidos, entre ellos:

  • Geocodificación global para convertir direcciones y nombres de lugares en coordenadas y viceversa
  • Búsqueda de puntos de interés (POI) entre millones de negocios, lugares emblemáticos y sitios de todo el mundo
  • Rutas multimodales para conducir, caminar y andar en bicicleta con tráfico en tiempo real
  • Matrices de tiempos de viaje para analizar la accesibilidad y optimizar la logística
  • Optimización de rutas para encontrar el orden óptimo de visita de varias paradas (problema del viajante)
  • Ajuste a la red vial para ajustar trazas GPS a la red de carreteras y obtener una visualización clara de las rutas
  • Generación de isócronas para visualizar las áreas a las que se puede llegar dentro de límites específicos de tiempo o distancia
  • Representación de mapas interactivos en vivo (render_map_tool) para mostrar rutas, resultados de búsqueda y tu propio GeoJSON personalizado en un mapa real de Mapbox GL JS directamente en el chat
  • Imágenes de mapas estáticos para crear representaciones visuales de ubicaciones, rutas y datos geográficos
  • Cálculos geoespaciales sin conexión de distancia, área, rumbo, zonas de influencia y análisis espacial, sin necesidad de llamadas a la API

Tanto si estás creando un asistente de viajes con IA, un optimizador logístico, un recomendador basado en la ubicación o cualquier aplicación que necesite comprender «dónde», el servidor MCP de Mapbox proporciona la inteligencia espacial necesaria para hacerlo posible. También puedes habilitarlo en clientes populares como Claude Desktop y VS Code. Consulta los detalles a continuación.

Mapbox MCP Server Demo

Uso

Se requiere un token de acceso de Mapbox para usar este servidor MCP.

Endpoint MCP alojado

Para acceder rápidamente, puedes usar nuestro endpoint MCP alojado:

Endpoint: https://mcp.mapbox.com/mcp

Para obtener instrucciones detalladas de configuración para distintos clientes y del uso de la API, consulta la guía del servidor MCP alojado.

Para obtener un token de acceso de Mapbox:

  1. Regístrate para obtener una cuenta gratuita de Mapbox en mapbox.com/signup
  2. Ve a tu página de cuenta
  3. Crea un token nuevo o usa el token público predeterminado

Para obtener más información sobre los tokens de acceso de Mapbox, consulta la documentación de Mapbox sobre los tokens de acceso.

Guías de integración

Para obtener instrucciones detalladas de configuración para distintas integraciones, consulta las siguientes guías:

Ejemplos de prompts

Prueba estos prompts con Claude Desktop u otros clientes MCP después de la configuración:

Contextualización de ubicaciones

Para consultas que parten de coordenadas —«qué hay cerca de mí», «qué barrio es este», «a qué lugares puedo llegar en N minutos»— usa ground_location_tool. Combina geocodificación inversa, búsqueda por categoría e isócrona en una sola llamada, eligiendo de forma adaptativa la estrategia adecuada según la consulta, y devuelve registros tipados (nombres, direcciones, coordenadas, distancias y polígonos de accesibilidad) con citas.

Cada uno de los cuatro prompts siguientes pone a prueba una estrategia distinta en una sola llamada a la herramienta:

  • Barrio — «¿Qué barrio está en 47.6097, -122.3408 y qué hay cerca de mí?»
  • POI — «Cafeterías a 10 minutos a pie de 40.7580, -73.9855»
  • Región — «¿A qué lugares puedo llegar en 15 minutos a pie desde 37.7749, -122.4194?»
  • Rutas — «Punto transitable más cercano para dejar a alguien en 34.0522, -118.2437»

Descubrimiento de lugares

  • «Encuentra cafeterías a poca distancia a pie del Empire State Building»
  • «Quiero ir de Seattle a Portland, ¿hay algún Starbucks en el camino?»
  • «Muéstrame gasolineras a lo largo de la ruta de Boston a Nueva York»
  • «¿Qué restaurantes hay cerca de Times Square?»

Navegación y viajes

  • «Obtén indicaciones en coche desde LAX hasta Hollywood con el tráfico actual»
  • «¿Cuánto tardaría en ir a pie de Central Park a Times Square?»
  • «Calcula el tiempo de viaje en taxi desde mi hotel (Four Seasons) hasta el aeropuerto JFK durante la hora punta»

Visualización y mapas

  • «Usando la herramienta de representación de mapas de Mapbox, muéstrame las indicaciones desde el Golden Gate Bridge hasta Union Square en San Francisco» — representa una ruta interactiva en vivo en un mapa real de Mapbox
  • «Crea una imagen de mapa que muestre la ruta desde Golden Gate Bridge hasta Fisherman's Wharf, con marcadores en ambas ubicaciones»
  • «Muéstrame una vista satelital de Manhattan con los principales lugares emblemáticos señalados»
  • «Genera un mapa que destaque todas las ubicaciones de Starbucks a menos de una milla del centro de Seattle»
  • «Muestra un polígono de relleno sobre estas coordenadas: [...], con un marcador etiquetado como 'Warehouse' en [...]» — representa tu propio GeoJSON directamente mediante render_map_tool, sin necesidad de ninguna otra herramienta de Mapbox

Análisis y planificación

  • «Muéstrame las áreas a las que se puede llegar en coche en 30 minutos desde el centro de Portland»
  • «Calcula una matriz de tiempos de viaje entre estas 3 ubicaciones de hoteles (Marriott, Sheraton y Hilton) y el centro de convenciones de Denver»
  • «Encuentra la ruta óptima para visitar estas 3 atracciones turísticas (Golden Gate, Musical Stairs y Fisherman's Wharf) en San Francisco»
  • «Optimiza una ruta de reparto para estas 8 direcciones: [lista de direcciones]»

GPS y ajuste de rutas

  • «Limpia esta traza GPS y muestra la ruta real por las carreteras: [lista de coordenadas con marcas de tiempo]»
  • «Ajusta este recorrido en bicicleta grabado a la red de ciclismo: [coordenadas GPS]»
  • «Ajusta esta ruta en coche a la red de carreteras y muestra los niveles de congestión del tráfico»

Cálculos geoespaciales sin conexión

  • «¿Cuál es la distancia en millas entre estas dos coordenadas?»
  • «Calcula el área de este polígono en kilómetros cuadrados»
  • «¿Está el punto en 37.7749°N, 122.4194°W dentro de este polígono de área de servicio?»
  • «¿Cuál es el rumbo de San Francisco a Nueva York?»
  • «Encuentra el punto medio entre Londres y París»
  • «Crea una zona de influencia de 5 millas alrededor de esta ubicación»
  • «Calcula el centroide de este límite de barrio»
  • «¿Cuál es el cuadro delimitador de estas coordenadas de ruta?»
  • «Simplifica este polígono complejo para reducir el número de puntos»

Consejos para obtener mejores resultados

  • Especifica las ubicaciones con precisión (usa direcciones completas o nombres de lugares emblemáticos)
  • Indica el medio de transporte que prefieres (coche, a pie o bicicleta)
  • Incluye restricciones horarias cuando corresponda («durante la hora punta», «a las 3 PM»)
  • Solicita formatos de salida específicos cuando los necesites («como imagen de mapa», «en formato JSON»)

Ejemplos detallados: Consulta examples/search-along-route.md para ver ejemplos completos del prompt de búsqueda a lo largo de una ruta, con distintos casos de uso e instrucciones para probarlo con MCP Inspector.

Recursos

El servidor MCP expone datos de referencia estáticos como recursos MCP. Los recursos proporcionan acceso de solo lectura a datos que los clientes pueden consultar directamente, sin realizar llamadas a herramientas.

Recursos disponibles

Recurso de categorías de Mapbox

Patrón de URI: mapbox://categories o mapbox://categories/{language}

Accede a la lista completa de ID de categorías disponibles para usar con la herramienta de búsqueda por categoría. Las categorías se pueden usar para filtrar los resultados de búsqueda por tipo (p. ej., «restaurant», «hotel», «gas_station»).

Ejemplos:

  • mapbox://categories - Lista de categorías predeterminada (en inglés)
  • mapbox://categories/ja - Nombres de categorías en japonés
  • mapbox://categories/es - Nombres de categorías en español

Acceso a los recursos:

  • Clientes con compatibilidad nativa con recursos MCP: Usa el método del protocolo MCP resources/read
  • Clientes sin compatibilidad con recursos: Usa resource_reader_tool con el URI del recurso

Vistas previas de mapas enriquecidas (render_map_tool)

Todas las herramientas geoespaciales de este servidor (indicaciones, isócronas, búsquedas y más) pueden mostrar sus resultados como un mapa interactivo en vivo de Mapbox GL JS mediante render_map_tool, la única primitiva de visualización del servidor. Se representa mediante el protocolo MCP Apps (@modelcontextprotocol/ext-apps) como un panel HTML independiente directamente en el chat, con un botón para cambiar a pantalla completa, en los clientes compatibles:

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

No necesitas ninguna otra herramienta de este servidor para usarlo. render_map_tool también acepta GeoJSON creado manualmente —tus propios polígonos, marcadores y rutas— sin depender de directions_tool, isochrone_tool ni de ninguna otra llamada a la API de Mapbox. Consulta la guía completa de render_map_tool para ver el esquema del contenido y un ejemplo independiente completo.

Si necesitas una imagen estática garantizada en clientes que no admiten MCP Apps, usa static_map_image_tool; devuelve un PNG/JPEG codificado en base64 que cualquier cliente puede mostrar.

CLIENT_NEEDS_RESOURCE_FALLBACK

Herramientas alternativas para recursos (opción para clientes no conformes)

Los recursos son una función esencial de MCP compatible con la mayoría de los clientes (Claude Desktop, VS Code, MCP Inspector, etc.). Sin embargo, algunos clientes (como smolagents) no admiten recursos. Para estos clientes, el servidor puede proporcionar «herramientas alternativas para recursos» que ofrecen el mismo contenido que los recursos, pero mediante llamadas a herramientas.

Herramientas alternativas:

  • resource_reader_tool - Alternativa genérica para leer cualquier recurso por URI
  • category_list_tool - Proporciona acceso a la lista de categorías (mapbox://categories)

De forma predeterminada, estas herramientas NO se incluyen (se presupone que el cliente admite recursos). Si tu cliente no admite recursos, habilita las herramientas alternativas:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Cuándo establecerlo:

  • ✅ Establécelo en true si usas smolagents u otros clientes sin compatibilidad con recursos
  • ❌ Déjalo sin establecer (valor predeterminado) si usas Claude Desktop, VS Code, MCP Inspector o cualquier cliente compatible con recursos
  • ❌ Déjalo sin establecer si no estás seguro (la mayoría de los clientes admiten recursos)

Herramientas

Herramientas de utilidad

Herramienta de lectura de recursos

Proporciona acceso a recursos MCP para clientes que no admiten la API nativa de recursos MCP. Usa esta herramienta para leer recursos como la lista de categorías.

Parámetros:

  • uri: URI del recurso que se va a leer (p. ej., mapbox://categories, mapbox://categories/ja)

Ejemplos de uso:

  • Leer las categorías predeterminadas: {"uri": "mapbox://categories"}
  • Leer las categorías en japonés: {"uri": "mapbox://categories/ja"}

Nota: Si tu cliente MCP admite recursos nativos, es preferible usar directamente la API de recursos para obtener un mejor rendimiento.

Herramientas geoespaciales sin conexión

Estas herramientas realizan cálculos geoespaciales completamente sin conexión, sin necesidad de llamadas a las API de Mapbox. Usan Turf.js para realizar cálculos geográficos precisos y funcionan en cualquier lugar, incluso sin conexión a Internet.

Herramienta de distancia

Calcula la distancia entre dos coordenadas geográficas mediante la fórmula de Haversine.

Funciones:

  • Admite varias unidades: kilómetros, millas, metros, pies y millas náuticas
  • Cálculo preciso de la distancia de círculo máximo
  • No requiere llamadas a la API

Ejemplo de uso: «¿Cuál es la distancia entre San Francisco (37.7749°N, 122.4194°W) y Nueva York (40.7128°N, 74.0060°W)?»

Herramienta de puntos dentro de un polígono

Comprueba uno o varios puntos con respecto a un polígono o multipolígono y devuelve solo los que están dentro. Admite un solo punto o un lote en una llamada.

Funciones:

  • Funciona con polígonos complejos, incluidos los que tienen huecos
  • Admite multipolígonos
  • Comprueba cualquier cantidad de puntos en una sola llamada
  • Útil para geocercas, validar zonas de entrega y segmentar clientes

Ejemplo de uso: «¿Cuáles de estas direcciones de entrega están dentro de nuestra zona de servicio?»

Herramienta de destino

Calcula un punto de destino a partir de un punto inicial, un rumbo y una distancia mediante un desplazamiento geodésico (de círculo máximo).

Características:

  • Desplazamiento en línea recta, no una ruta
  • Útil para «encontrar un punto 5 km al norte de X» o crear desplazamientos de búsqueda
  • No requiere llamadas a la API

Ejemplo de uso: «¿Cuál es el punto situado 10 km al noreste de la Space Needle?»

Herramienta de rumbo

Calcula la dirección de la brújula (rumbo) de una coordenada a otra.

Características:

  • Devuelve el rumbo en grados (0-360°)
  • Proporciona la dirección cardinal (N, NE, E, SE, S, SW, W, NW)
  • Útil para navegación y consultas sobre direcciones

Ejemplo de uso: «¿En qué dirección debo ir para llegar desde aquí al aeropuerto?»

Herramienta de punto medio

Encuentra el punto medio geográfico entre dos coordenadas a lo largo de la ruta de círculo máximo.

Características:

  • Calcula el punto medio real sobre la superficie curva de la Tierra
  • Útil para sugerir puntos de encuentro
  • Gestiona correctamente los cálculos de larga distancia

Ejemplo de uso: «¿Cuál es el punto medio entre San Francisco y Nueva York?»

Herramienta de centroide

Calcula el centro geométrico (centroide) de un polígono o multipolígono.

Características:

  • Funciona con formas complejas
  • Devuelve la media aritmética de todos los puntos
  • Útil para colocar etiquetas o marcadores

Ejemplo de uso: «¿Dónde debería colocar un marcador para el límite de este vecindario?»

Herramienta de área

Calcula el área de un polígono.

Características:

  • Admite varias unidades: metros cuadrados, kilómetros cuadrados, acres, hectáreas, millas cuadradas y pies cuadrados
  • Cálculo preciso del área sobre la superficie terrestre
  • Funciona con polígonos de cualquier tamaño

Ejemplo de uso: «¿Cuál es el área de este parque en acres?»

Herramienta de cuadro delimitador

Calcula el cuadro delimitador mínimo (bbox) que contiene una geometría.

Características:

  • Funciona con puntos, líneas, polígonos y multipolígonos
  • Devuelve [minLongitude, minLatitude, maxLongitude, maxLatitude]
  • Útil para calcular ventanas gráficas e indexar datos espaciales

Ejemplo de uso: «¿Cuál es el cuadro delimitador de esta ruta?»

Herramienta de zona de influencia

Crea una zona de influencia (polígono) alrededor de un punto, una línea o un polígono.

Características:

  • Admite varias unidades de distancia
  • Crea zonas de influencia circulares alrededor de puntos
  • Útil para analizar proximidad y crear zonas de influencia

Ejemplo de uso: «Muéstrame una zona de influencia de 5 km alrededor de esta ubicación»

Herramienta de simplificación

Reduce la cantidad de vértices de una línea o un polígono mediante el algoritmo de Douglas-Peucker.

Características:

  • Tolerancia configurable para ajustar el nivel de detalle
  • Conserva la forma general y reduce la complejidad
  • Útil para reducir el tamaño de los archivos y mejorar el rendimiento de renderizado
  • Opción para mantener la topología (evitar autointersecciones)

Ejemplo de uso: «Simplifica este límite complejo para reducir la cantidad de puntos»

Herramienta de longitud

Mide la longitud total de una línea definida por una serie de coordenadas.

Características:

  • Admite kilómetros, millas, metros y pies
  • Útil para medir una ruta, un recorrido o un límite dibujado sin llamar a una API de rutas

Ejemplo de uso: «¿Cuánto mide esta ruta de senderismo?»

Herramienta convexa

Calcula la envolvente convexa de un conjunto de puntos: el polígono convexo más pequeño que los contiene a todos.

Características:

  • Útil para analizar áreas delimitadas o estimar áreas de cobertura
  • Funciona sin conexión y no requiere llamadas a la API

Ejemplo de uso: «¿Cuál es el polígono más pequeño que contiene todas estas ubicaciones de tiendas?»

Herramienta de punto más cercano

Encuentra el punto más cercano de una colección a un punto de destino determinado.

Características:

  • Más eficiente que llamar a distance_tool para cada candidato y ordenarlos
  • Útil para encontrar la tienda, parada o punto de referencia más cercano a una ubicación

Ejemplo de uso: «¿Cuál de estas tiendas está más cerca de mi ubicación actual?»

Herramienta de punto más cercano en una línea

Ajusta un punto a la posición más cercana de una línea o ruta y devuelve ese punto y la distancia hasta él.

Características:

  • Útil para responder «¿qué punto de esta ruta está más cerca de mi ubicación?» o ajustar puntos a una ruta sin llamar a una API

Ejemplo de uso: «¿En qué punto de esta ruta de senderismo estoy más cerca ahora mismo?»

Herramientas de unión, intersección y diferencia

Combina o compara dos o más polígonos: union_tool los fusiona en una sola geometría, intersect_tool encuentra el área que comparten y difference_tool resta uno del otro.

Características:

  • Útiles para combinar zonas de servicio, encontrar áreas de cobertura superpuestas o calcular zonas de exclusión (por ejemplo, «¿qué cubre la zona A que no cubre la zona B?»)
  • Funcionan completamente sin conexión; no requieren llamadas a la API
  • Cada una devuelve una referencia render_map_tool para que el resultado se pueda visualizar directamente

Ejemplo de uso: «Combina estas dos zonas de entrega en una sola área de cobertura» / «¿Dónde se superponen estas dos isócronas?» / «¿Qué parte de esta zona de servicio no está cubierta por nuestra isócrona de 15 minutos?»

Herramientas de la API de Mapbox

Herramienta de lista de categorías (obsoleta)

⚠️ Obsoleta: Usa resource_reader_tool con el URI mapbox://categories en su lugar, o accede directamente al recurso mapbox://categories si tu cliente admite recursos MCP.

Esta herramienta se mantiene por compatibilidad con versiones anteriores de clientes que no admiten recursos MCP ni resource_reader_tool.

Herramienta de matriz

Calcula los tiempos y las distancias de viaje entre varios puntos mediante Mapbox Matrix API. Entre sus características se incluyen:

  • Cálculos de rutas eficientes de uno a varios, de varios a uno o de varios a varios
  • Compatibilidad con distintos perfiles de viaje (driving-traffic, driving, walking, cycling)
  • Especificación de la hora de salida para cálculos que tienen en cuenta el tráfico
  • Resumen de rutas con métricas de distancia y duración
  • Control del lado de aproximación (bordillo/sin restricciones) y del rango de rumbos de salida permitidos

Herramienta de imagen estática

Genera imágenes estáticas de mapas mediante Mapbox static image API. Entre sus características se incluyen:

  • Estilos de mapa personalizados (calles, exteriores, satélite, etc.)
  • Dimensiones de imagen y niveles de zoom ajustables
  • Compatibilidad con varios marcadores con colores y etiquetas personalizados
  • Opciones de superposición, incluidas polilíneas y polígonos
  • Ajuste automático a las coordenadas especificadas

Herramienta de búsqueda por categoría

Realiza una búsqueda por categoría mediante Mapbox Search Box category search API. Entre sus características se incluyen:

  • Búsqueda de puntos de interés por categoría (restaurantes, hoteles, gasolineras, etc.)
  • Filtrado por proximidad geográfica
  • Límites de resultados personalizables
  • Metadatos detallados para cada resultado
  • Compatibilidad con varios idiomas

Herramienta de geocodificación inversa

Realiza una geocodificación inversa mediante Mapbox geocoding V6 API. Entre sus características se incluyen:

  • Convierte coordenadas geográficas en direcciones legibles
  • Niveles de detalle personalizables (calle, vecindario, ciudad, etc.)
  • Filtrado de resultados por tipo (dirección, poi, vecindario, etc.)
  • Compatibilidad con varios idiomas
  • Información contextual detallada sobre la ubicación

Herramienta de ubicación terrestre

Responde en una sola llamada a preguntas como «¿qué hay cerca de esta coordenada?»: nombre del lugar, puntos de interés cercanos y accesibilidad según el tiempo de viaje, con datos actuales de Mapbox y citas. Úsala en lugar de encadenar reverse_geocode_tool con una búsqueda web.

Características:

  • Clasifica la consulta (rutas, contexto del vecindario, búsqueda de POI o región/accesibilidad) y obtiene solo los datos pertinentes
  • Búsqueda de POI cercanos por categoría, cuando se solicita
  • Resumen de accesibilidad según el tiempo de viaje (basado en isócronas)
  • Devuelve una referencia render_map_tool con la ubicación contextualizada y los POI cercanos representados en el mapa

Ejemplo de uso: «¿En qué vecindario está esta coordenada y hay cafeterías cerca?»

Herramienta de detalles del lugar

Obtiene información detallada sobre un lugar específico mediante su ID de Mapbox: fotos, horarios de apertura, valoraciones, números de teléfono y URL de sitios web. Úsala después de search_and_geocode_tool, category_search_tool o reverse_geocode_tool para obtener más detalles sobre un resultado específico.

Ejemplo de uso: «Cuéntame más sobre el primer resultado de cafetería: horarios, número de teléfono y sitio web»

Herramienta de indicaciones

Obtiene indicaciones de ruta mediante Mapbox Directions API. Entre sus características se incluyen:

  • Compatibilidad con distintos perfiles de rutas: conducción (con tráfico en tiempo real o habitual), a pie y en bicicleta
  • Rutas con varios puntos intermedios (de 2 a 25 pares de coordenadas)
  • Opción de rutas alternativas
  • Anotaciones de ruta (distancia, duración, velocidad, congestión)
  • Opciones de programación:
    • Hora de salida futura (depart_at) para los perfiles driving y driving-traffic
    • Hora de llegada deseada (arrive_by) solo para el perfil driving
  • Optimizaciones específicas del perfil:
    • Conducción: restricciones de dimensiones del vehículo (altura, anchura, peso)
  • Opciones de exclusión para las rutas:
    • Exclusiones comunes: rutas de ferry, peajes que solo aceptan efectivo
    • Exclusiones específicas para la conducción: peajes, autopistas, caminos sin pavimentar, túneles, fronteras nacionales y fronteras estatales
    • Exclusiones de puntos personalizados (hasta 50 puntos geográficos que se deben evitar)
  • Formato de salida de geometría GeoJSON

Herramienta de isócronas

Calcula las áreas a las que se puede llegar desde una ubicación en un tiempo determinado mediante Mapbox Isochrone API. Entre sus características se incluyen:

  • Compatibilidad con distintos perfiles de viaje (conducción, a pie y en bicicleta)
  • Tiempos o distancias de viaje personalizables
  • Generación de varios contornos (por ejemplo, intervalos de 15, 30 y 45 minutos)
  • Especificación opcional de la hora de salida o llegada
  • Personalización de colores para la visualización

Herramienta de búsqueda y geocodificación

Usa el endpoint Mapbox Search Box Text Search API para buscar y geocodificar POI, direcciones, lugares y cualquier otro tipo compatible con esa API. Esta herramienta consolida la funcionalidad que antes ofrecían ForwardGeocodeTool y PoiSearchTool (en versiones anteriores de este servidor MCP) en una sola herramienta.

Herramienta de ajuste a la red vial

Ajusta trazas GPS a la red vial mediante Mapbox Map Matching API. Entre sus características se incluyen:

  • Convierte trazas GPS ruidosas en rutas limpias sobre la red vial
  • Compatibilidad con distintos perfiles de viaje (driving, driving-traffic, walking, cycling)
  • Admite hasta 100 pares de coordenadas por solicitud
  • Marcas de tiempo opcionales para mejorar la precisión según la velocidad
  • Radios de ajuste configurables para distintos niveles de calidad del GPS
  • Anotaciones de ruta (límites de velocidad, distancia, duración, congestión del tráfico)
  • Varios formatos de salida de geometría (GeoJSON, polyline)

Ejemplo de uso: «Limpia esta traza GPS y ajústala a las carreteras: [coordenadas con marcas de tiempo]»

Herramienta de optimización

Encuentra la ruta óptima entre varias ubicaciones mediante Mapbox Optimization API. Entre sus características se incluyen:

  • Resuelve el problema del viajante (TSP) para entre 2 y 12 ubicaciones
  • Compatibilidad con distintos perfiles de viaje (driving, driving-traffic, walking, cycling)
  • Configuración flexible de los puntos de inicio y fin
  • Optimización de viajes de ida y vuelta o de solo ida
  • Instrucciones de navegación giro a giro (opcional)
  • Anotaciones de ruta (distancia, duración, velocidad)
  • Varios formatos de salida de geometría (GeoJSON, polyline)

Ejemplo de uso: «Encuentra la ruta óptima para visitar estas 5 paradas: [lista de direcciones o coordenadas]»

Nota: Hay una API V2 con funciones avanzadas (ventanas de tiempo, restricciones de capacidad y varios vehículos), pero requiere acceso beta. La implementación de V2 está incluida en el código base, pero no está registrada de forma predeterminada.

Herramienta de comentarios

Envía los comentarios de un usuario sobre la aplicación o el agente a su desarrollador mediante Mapbox Feedback API (versión preliminar pública). Se registran en la cuenta propietaria del token de acceso. Por tanto, si creas una aplicación o un agente en este servidor con tu propio token, los comentarios de tus usuarios aparecerán en el mismo feed que los informes de Feedback Agent de tus aplicaciones, y podrás revisarlos en Feedback Explorer. No informa de problemas a Mapbox. Al igual que Feedback Agent, sirve para enviar cualquier comentario sobre tu producto que te ayude a entender las necesidades de los usuarios, por ejemplo:

  • Un lugar que ha cerrado, tiene datos incorrectos o aparece en el lugar equivocado
  • Un lugar o una dirección que no se puede encontrar
  • Una carretera cerrada, un límite de velocidad incorrecto o información de tráfico errónea
  • Una ruta con un giro o una entrada ilegal, o sin ruta
  • Algo relacionado con la propia aplicación, como un error o una sugerencia (application_issue)

Envía el texto de los comentarios, una categoría y la ubicación, y devuelve el ID y el estado del elemento. La ubicación es opcional para los comentarios que no se refieren a un lugar; la API la exige, así que la herramienta envía 0, 0, tal como recomienda por ahora el equipo de Feedback API. No se envía nada sin la autorización del usuario: los clientes que admiten la solicitud de información muestran primero un mensaje de confirmación, y la descripción de la herramienta pide al modelo que confirme en el chat en los demás casos.

Feedback API es gratis durante la versión preliminar pública. Cuando esté disponible de forma general, Feedback Agent cobrará $0.02 por cada comentario. Para evitar enviar dos veces el mismo problema, antes de enviar, la herramienta comprueba los informes de la cuenta de los últimos 30 días. Si hay uno de la misma categoría, a menos de 50 m, que aún está pendiente de revisión (no se comprueban los comentarios sin ubicación), devuelve ese informe en lugar de enviar uno nuevo. Feedback API solo muestra los informes de la propia cuenta, así que no puede detectar los informes de otras cuentas. send_anyway: true omite la comprobación cuando el usuario dice que se trata de un problema distinto.

Requisitos: el token de acceso necesita el ámbito user-feedback:write para enviar comentarios y user-feedback:read para comprobar si hay duplicados. Sin el ámbito de escritura, la herramienta devuelve un error que lo indica. Sin el ámbito de lectura, envía el comentario sin comprobar si hay duplicados y lo indica en el resultado. Para excluir la herramienta, inicia el servidor con --disable-tools feedback_tool.

Ejemplo de uso: «Blue Bottle en Mint St cerró el año pasado, ¿puedes enviar ese comentario?»

Herramienta Report

Envía comentarios sobre el propio servidor Mapbox MCP al equipo de Mapbox que lo desarrolla: un error, un resultado incorrecto o confuso de una herramienta, una función que falta o una sugerencia. Se registra en la cuenta de Mapbox, no en la tuya, así que no necesita un ámbito de token adicional y no se puede consultar ni retirar después. No sirve para informar de datos incorrectos de mapas, lugares o rutas.

El servidor añade al final del texto su versión, el nombre y la versión del cliente, y la herramienta a la que se refiere el comentario. No se envía nada sin la autorización del usuario: los clientes que admiten la solicitud de información muestran primero un mensaje de confirmación, y la descripción de la herramienta pide al modelo que confirme en el chat en los demás casos.

Usa el endpoint que el equipo de Feedback API añadió para el comando mapbox report de Mapbox CLI. Para excluir la herramienta, inicia el servidor con --disable-tools report_tool.

Ejemplo de uso: «El mapa no dibujó ninguna de mis isócronas. ¿Puedes avisar al equipo de Mapbox MCP?»

Herramienta List public tokens

Muestra los tokens de acceso públicos (pk.) de la cuenta, para un agente que esté creando una página web o una aplicación fuera del chat que cargue Mapbox GL JS o llame a las API de Mapbox desde el navegador. En el chat, render_map_tool no necesita ningún token. Cada token incluye su nombre, si es el predeterminado, sus restricciones de URL y sus ámbitos.

Pasa site_url (donde se ejecutará la página) y la herramienta recomienda un token restringido a esa URL si la cuenta tiene uno. De lo contrario, recomienda el token público predeterminado e indica que un sitio publicado debería usar un token restringido por URL, con un enlace para crear uno. Cualquiera que copie un token público sin restricciones puede usarlo, y el uso se factura a la cuenta.

Nunca devuelve tokens secretos ni temporales, y no puede crear tokens (para eso se necesita tokens:write; create_token_tool del servidor DevKit lo hace).

Requisitos: para listar tokens se necesita el ámbito tokens:read, el mismo que ya usa el mapa del chat para encontrar el token público predeterminado. Si se usa un token de acceso pk., o si falla la consulta en el servidor con su propio MAPBOX_ACCESS_TOKEN y está configurado MAPBOX_PUBLIC_TOKEN, devuelve ese token. Una persona que llama con su propio token bearer (el servidor alojado) nunca recibe MAPBOX_PUBLIC_TOKEN, y nunca se recomienda un token restringido a otras URL. Para excluir la herramienta, inicia el servidor con --disable-tools list_public_tokens_tool.

Ejemplo de uso: «Créame un sitio de una sola página que muestre las tres ubicaciones de nuestras tiendas en un mapa de Mapbox».

Desarrollo

Inspeccionar el servidor

Con Node.js

# Run the built image
npm run inspect:build

Con 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

Crear una herramienta nueva

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

Publicar una versión nueva

# 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

Importante: el flujo de trabajo de publicación valida que las versiones de package.json y server.json coincidan con la versión de publicación. Omitir la actualización de la versión o la sincronización del manifiesto provocará errores al publicar.

Trazas de OpenTelemetry

Este servidor MCP incluye trazas completas de OpenTelemetry para la observabilidad en producción:

Demostración rápida

# 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

Nota: el servidor carga automáticamente la configuración del archivo .env al iniciarse. El archivo .env.example incluye ejemplos de configuración para varias plataformas de observabilidad.

Plataformas de observabilidad compatibles

El archivo .env.example incluye ejemplos de configuración para:

Proveedores de servicios en la nube:

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

Plataformas SaaS:

  • 📊 Datadog
  • 📊 New Relic
  • 📊 Honeycomb
  • 📊 Cualquier backend compatible con OTLP

Configuración para producción

Consulta docs/tracing.md para ver las instrucciones completas de configuración, que incluyen:

  • 🔧 Guías de configuración específicas para cada plataforma
  • 📊 Configuración de autenticación y endpoints
  • 🎯 Atributos de traza y contexto personalizados
  • 🚀 Optimización del rendimiento (sobrecarga mínima)
  • 🔍 Solución de problemas y depuración

Funciones de trazas:

  • ✅ Trazas de carga de configuración (carga del archivo .env)
  • ✅ Trazas automáticas de ejecución de herramientas
  • ✅ Instrumentación de solicitudes HTTP con ID de correlación de CloudFront
  • ✅ Exportadores configurables (consola, OTLP)
  • ✅ Enfoque en la seguridad (protección de datos, validación de JWT)
  • ✅ Listo para producción (menos del 1 % de sobrecarga de CPU)

Contribuciones

¡Agradecemos las contribuciones al servidor Mapbox MCP! Lee CONTRIBUTING.md antes de enviar una solicitud de incorporación de cambios.

Normas y directrices completas:

Primeros pasos para contribuir

  1. Crea un fork del repositorio y clónalo
  2. Instala las dependencias: npm install
  3. Realiza los cambios siguiendo nuestras normas de programación
  4. Ejecuta las pruebas y el análisis estático: npm test && npm run lint
  5. Añade pruebas para cualquier funcionalidad nueva
  6. Envía una solicitud de incorporación de cambios con una descripción clara

Todas las contribuciones deben superar las comprobaciones de CI y el proceso de revisión del código. Consulta docs/engineering_standards.md para ver los requisitos detallados.

Uso de datos y privacidad

Qué datos se envían a las API de Mapbox

Al usar las herramientas del servidor MCP, los siguientes datos se envían directamente desde tu entorno a las API de Mapbox:

  • Herramientas de geocodificación: texto de direcciones o ubicaciones, coordenadas y filtros de país o región
  • Herramientas de búsqueda: consultas de búsqueda, coordenadas de ubicación para proximidad y filtros de categoría
  • Herramienta de indicaciones: coordenadas de inicio y fin, puntos de paso, preferencias de ruta y restricciones del vehículo
  • Herramienta de matriz: varios pares de coordenadas, perfil de viaje y horas de salida
  • Herramienta de mapas estáticos: coordenadas, nivel de zoom, preferencias de estilo e información de marcadores
  • Herramienta de isócronas: coordenadas de origen, parámetros de tiempo o distancia y perfil de viaje

Tu privacidad

  • Ejecución local: todas las llamadas a la API se realizan directamente desde tu entorno a las API de Mapbox
  • Seguridad del token: tu token de API de Mapbox permanece en tu equipo local y este servidor MCP nunca lo transmite ni lo almacena
  • Sin almacenamiento de datos: este servidor MCP no almacena, registra ni recopila ninguno de tus datos ni solicitudes a la API
  • Comunicación directa: no hay ningún servidor intermediario entre tú y las API de Mapbox

Uso de datos por terceros

  • La política de privacidad de Mapbox rige los datos enviados a sus API: https://www.mapbox.com/legal/privacy/
  • Uso de la API: las condiciones estándar de las API de Mapbox se aplican a todas las solicitudes realizadas mediante estas herramientas
  • Retención de datos: consulta la documentación de Mapbox para conocer sus políticas de retención de datos

Asistencia y contacto

Problemas con el servidor MCP

Preguntas sobre las API de Mapbox

Compromiso de mantenimiento

Mapbox, Inc. mantiene oficialmente este servidor MCP. Ofrecemos:

  • Actualizaciones periódicas para las nuevas funciones de las API de Mapbox
  • Correcciones de errores y actualizaciones de seguridad
  • Compatibilidad con las versiones más recientes del protocolo MCP
  • Asistencia de la comunidad mediante los problemas de GitHub

Licencia MIT