Mapbox

Servidor MCP de Mapbox

Servidor Node.js que implementa el Protocolo de Contexto de Modelo (MCP) para las APIs de Mapbox.

Desbloquea 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 plataforma integral de inteligencia de ubicación de Mapbox. Con este servidor, tu IA puede entender y razonar sobre lugares, navegar por el mundo físico y acceder a datos geoespaciales enriquecidos, incluyendo:

• 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 en todo el mundo
• Enrutamiento multimodal para conducir, caminar y andar en bicicleta con tráfico en tiempo real
• Matrices de tiempo de viaje para analizar accesibilidad y optimizar logística
• Optimización de rutas para encontrar el orden de visita óptimo para múltiples paradas (problema del viajante)
• Emparejamiento de mapas para ajustar trazas GPS a la red de carreteras y lograr una visualización limpia de rutas
• Generación de isócronas para visualizar áreas alcanzables dentro de restricciones específicas de tiempo o distancia
• Renderizado 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 dentro del chat
• Imágenes de mapas estáticos para crear representaciones visuales de ubicaciones, rutas y datos geográficos
• Cálculos geoespaciales sin conexión para distancia, área, rumbo, buffers y análisis espacial sin necesidad de llamadas a la API

Ya sea que estés construyendo un asistente de viajes con IA, un optimizador logístico, un recomendador basado en ubicación o cualquier aplicación que necesite entender el "dónde", el Servidor MCP de Mapbox proporciona la inteligencia espacial para hacerlo posible. También puedes habilitarlo en clientes populares como Claude Desktop y VS Code. Consulta los detalles a continuación.

Uso

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

Endpoint MCP Alojado

Para acceso rápido, puedes usar nuestro endpoint MCP alojado:

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

Para instrucciones detalladas de configuración para diferentes clientes y 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. Navega a tu página de Cuenta
3. Crea un nuevo token o usa el token público predeterminado

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

Guías de Integración

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

• Configuración de Claude Desktop - Instrucciones para configurar Claude Desktop para que funcione con este servidor MCP
• Configuración de Goose - Configuración del framework de agentes de IA Goose
• Configuración de VS Code - Configuración de un entorno de desarrollo en Visual Studio Code
• Configuración de Cursor AI IDE - Configuración de un entorno de desarrollo en Cursor AI IDE
• Integración con Smolagents - Ejemplo que muestra cómo conectar agentes de IA Smolagents a las herramientas de Mapbox
• Importación Directa de Herramientas - Usa las herramientas de Mapbox en tus propias aplicaciones sin ejecutar el servidor MCP
• Guía de render_map_tool - La primitiva de visualización de mapas: esquema completo de payload y cómo renderizar tus propios datos de forma independiente, sin ninguna otra herramienta de Mapbox
• Elicitaciones - Cómo search_and_geocode_tool y directions_tool piden al usuario que desambigüe resultados o elija una ruta, y cómo recurren con elegancia cuando el cliente no lo admite

Ejemplos de Prompts

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

Anclaje de Ubicación

Para consultas centradas en coordenadas — "qué hay cerca de mí", "qué vecindario es este", "qué es alcanzable en N minutos" — usa ground_location_tool. Compone geocodificación inversa, búsqueda por categoría e isócronas en una sola llamada, eligiendo adaptativamente la estrategia correcta según la consulta, y devuelve registros tipados (nombres, direcciones, coordenadas, distancias, polígonos de alcanzabilidad) con citas.

Cada uno de los cuatro prompts siguientes ejercita una estrategia diferente en una sola llamada de herramienta:

• Vecindario — "¿Qué vecindario es 47.6097, -122.3408, y qué hay a mi alrededor?"
• POI — "Cafeterías a 10 minutos a pie de 40.7580, -73.9855"
• Región — "¿Qué puedo alcanzar en una caminata de 15 minutos desde 37.7749, -122.4194?"
• Enrutamiento — "Punto transitable más cercano para dejar a alguien en 34.0522, -118.2437"

Descubrimiento de Ubicaciones

• "Encuentra cafeterías a distancia caminable del Empire State Building"
• "Quiero ir de Seattle a Portland, ¿hay un 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 para conducir de LAX a Hollywood con tráfico actual"
• "¿Cuánto tardaría caminar de Central Park a Times Square?"
• "Calcula el tiempo de viaje desde mi hotel (Four Seasons) al Aeropuerto JFK en taxi durante la hora pico"

Visualización y Mapas

• "Usando la herramienta de renderizado de mapas de Mapbox, muéstrame indicaciones del Golden Gate Bridge a Union Square en San Francisco" — renderiza una ruta interactiva en vivo en un mapa real de Mapbox
• "Crea una imagen de mapa que muestre la ruta del Golden Gate Bridge a Fisherman's Wharf con marcadores en ambas ubicaciones"
• "Muéstrame una vista satelital de Manhattan con los principales puntos de referencia marcados"
• "Genera un mapa que resalte todas las ubicaciones de Starbucks dentro de una milla del centro de Seattle"
• "Muestra un polígono de relleno sobre estas coordenadas: [...], con un marcador etiquetado 'Almacén' en [...]" — renderiza tu propio GeoJSON directamente mediante render_map_tool, sin necesidad de otra herramienta de Mapbox

Análisis y Planificación

• "Muéstrame las áreas alcanzables en 30 minutos en auto desde el centro de Portland"
• "Calcula una matriz de tiempo de viaje entre estas 3 ubicaciones de hoteles (Marriott, Sheraton y Hilton) y el centro de convenciones en Denver"
• "Encuentra la ruta óptima visitando estas 3 atracciones turísticas (Golden Gate, Escaleras Musicales y Fisherman's Wharf) en San Francisco"
• "Optimiza una ruta de entrega para estas 8 direcciones: [lista de direcciones]"

GPS y Emparejamiento de Rutas

• "Limpia esta traza GPS y muestra la ruta real en las carreteras: [lista de coordenadas con marcas de tiempo]"
• "Ajusta este recorrido en bicicleta grabado a la red de ciclovías: [coordenadas GPS]"
• "Empareja esta ruta de conducción con la red de carreteras y muestra los niveles de congestión de 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°O 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 amortiguamiento de 5 millas alrededor de esta ubicación"
• "Calcula el centroide de este límite de vecindario"
• "¿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 Mejores Resultados

• Sé específico sobre las ubicaciones (usa direcciones completas o nombres de puntos de referencia)
• Especifica tu método de viaje preferido (conducir, caminar, andar en bicicleta)
• Incluye restricciones de tiempo cuando sea relevante ("durante la hora pico", "a las 3 PM")
• Solicita formatos de salida específicos cuando sea necesario ("como imagen de mapa", "en formato JSON")

Ejemplos detallados: Consulta examples/search-along-route.md para ejemplos completos del prompt de búsqueda a lo largo de la ruta con diferentes casos de uso e instrucciones de prueba 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 referenciar directamente sin hacer 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 IDs de categorías disponibles para usar con la herramienta de búsqueda por categoría. Las categorías se pueden usar para filtrar resultados de búsqueda por tipo (por ejemplo, "restaurant", "hotel", "gas_station").

Ejemplos:

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

Acceso a Recursos:

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

Vistas Previas de Mapas Enriquecidas (render_map_tool)

Cada herramienta geoespacial en este servidor (indicaciones, isócronas, búsqueda y más) puede mostrar su resultado como un mapa interactivo en vivo de Mapbox GL JS mediante render_map_tool — la primitiva de visualización única del servidor. Se renderiza a través del protocolo MCP Apps (@modelcontextprotocol/ext-apps) como un panel HTML autocontenido directamente dentro del chat, con un botón de Pantalla Completa, en 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 compuesto manualmente directamente — tus propios polígonos, marcadores y rutas — sin dependencia de directions_tool, isochrone_tool ni ninguna otra llamada a la API de Mapbox. Consulta la guía completa de render_map_tool para el esquema del payload y un ejemplo independiente completo.

Si necesitas una imagen estática garantizada en clientes sin soporte de MCP Apps, usa static_map_image_tool en su lugar — devuelve un PNG/JPEG codificado en base64 que todo cliente puede mostrar.

CLIENT_NEEDS_RESOURCE_FALLBACK

Herramientas de Respaldo de Recursos (Opt-In para Clientes No Compatibles)

Los recursos son una característica central 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 en absoluto. Para estos clientes, el servidor puede proporcionar "herramientas de respaldo de recursos" que entregan el mismo contenido que los recursos pero mediante llamadas a herramientas.

Herramientas de Respaldo:

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

Por defecto, estas herramientas NO están incluidas (asume que tu cliente admite recursos). Si tu cliente no admite recursos, habilita las herramientas de respaldo:

export CLIENT_NEEDS_RESOURCE_FALLBACK=true

Cuándo configurar esto:

• ✅ Configúralo en true si usas smolagents u otros clientes sin soporte de recursos
• ❌ Déjalo sin configurar (predeterminado) si usas Claude Desktop, VS Code, MCP Inspector o cualquier cliente con capacidad de recursos
• ❌ Déjalo sin configurar 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 los 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: El URI del recurso a leer (por ejemplo, mapbox://categories, mapbox://categories/ja)

Ejemplo de Uso:

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

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

Herramientas Geoespaciales Sin Conexión

Estas herramientas realizan cálculos geoespaciales completamente sin conexión, sin requerir llamadas a la API de Mapbox. Usan Turf.js para 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 usando la fórmula de Haversine.

Características:

• Admite múltiples unidades: kilómetros, millas, metros, pies, millas náuticas
• Cálculo preciso de 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°O) y Nueva York (40.7128°N, 74.0060°O)?"

Herramienta de Puntos Dentro de Polígono

Prueba uno o más puntos contra un polígono o multipolígono, devolviendo solo aquellos que están dentro. Maneja un solo punto o un lote en una sola llamada.

Características:

• Funciona con polígonos complejos, incluidos los que tienen agujeros
• Admite multipolígonos
• Prueba por lotes cualquier número de puntos en una sola llamada
• Útil para geocercas, validación de zonas de entrega y segmentación de clientes

Ejemplo de uso: "¿Cuáles de estas direcciones de entrega están dentro de nuestra área de servicio?"

Herramienta de destino

Calcula un punto de destino dado un punto de partida, un rumbo y una distancia utilizando un desplazamiento geodésico (círculo máximo).

Características:

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

Ejemplo de uso: "¿Cuál es el punto a 10 km al noreste de la Aguja Espacial?"

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, SO, O, NO)
• Útil para navegación y consultas direccionales

Ejemplo de uso: "¿En qué dirección debo dirigirme para ir de aquí al aeropuerto?"

Herramienta de punto medio

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

Características:

• Calcula el punto medio real en la superficie curva de la Tierra
• Útil para sugerencias de puntos de encuentro
• Maneja correctamente cálculos de larga distancia

Ejemplo de uso: "¿Qué hay a mitad de camino 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 debo colocar un marcador para este límite de vecindario?"

Herramienta de área

Calcula el área de un polígono.

Características:

• Admite múltiples unidades: metros cuadrados, kilómetros cuadrados, acres, hectáreas, millas cuadradas, pies cuadrados
• Cálculo preciso del área en la superficie de la Tierra
• 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 [minLongitud, minLatitud, maxLongitud, maxLatitud]
• Útil para cálculos de viewport e indexación espacial

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

Herramienta de buffer

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

Características:

• Admite múltiples unidades de distancia
• Crea buffers circulares alrededor de puntos
• Útil para análisis de proximidad y creación de zonas de influencia

Ejemplo de uso: "Muéstrame una zona de amortiguamiento de 5 km alrededor de esta ubicación"

Herramienta de simplificación

Reduce el número de vértices en una línea o polígono utilizando el algoritmo Douglas-Peucker.

Características:

• Tolerancia configurable para el nivel de detalle
• Preserva la forma general mientras reduce la complejidad
• Útil para reducir tamaños de archivo y mejorar el rendimiento de renderizado
• Opción para mantener la topología (evitar auto-intersecciones)

Ejemplo de uso: "Simplifica este límite complejo para reducir el número 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 dibujada, un camino o un límite sin una llamada a la API de enrutamiento

Ejemplo de uso: "¿Cuánto mide este sendero de excursión?"

Herramienta de convexo

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 análisis de área delimitada o estimación del área de cobertura
• Funciona sin conexión sin 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 en una colección a un punto objetivo dado.

Características:

• Más eficiente que llamar a distance_tool para cada candidato y ordenar
• Ú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 línea

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

Características:

• Útil para "¿qué punto de esta ruta está más cerca de mi ubicación?" o coincidencia de mapas sin una llamada a la API

Ejemplo de uso: "¿Dónde en este sendero de excursión estoy más cerca en este momento?"

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 de otro.

Características:

• Útil para combinar áreas de servicio, encontrar superposición de cobertura o calcular zonas de exclusión (por ejemplo, "¿qué está cubierto por la zona A pero no por la zona B?")
• Funciona completamente sin conexión: no se 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 un área de cobertura" / "¿Dónde se superponen estos dos isócronos?" / "¿Qué parte de esta área de servicio no está cubierta por nuestro isócrono de 15 minutos?"

Herramientas de API de Mapbox

Herramienta de lista de categorías (obsoleta)

⚠️ Obsoleta: Use la resource_reader_tool con URI mapbox://categories en su lugar, o acceda al recurso mapbox://categories directamente si su cliente admite recursos MCP.

Esta herramienta se mantiene para compatibilidad con versiones anteriores de clientes que no admiten recursos MCP o la herramienta resource_reader_tool.

Herramienta de matriz

Calcula tiempos de viaje y distancias entre múltiples puntos utilizando la API de matriz de Mapbox. Las características incluyen:

• Cálculos de enrutamiento eficientes de uno a muchos, muchos a uno o muchos a muchos
• Soporte para diferentes perfiles de viaje (tráfico en automóvil, automóvil, caminar, bicicleta)
• Especificación de hora de salida para cálculos conscientes del tráfico
• Resumen de ruta con métricas de distancia y duración
• Control de aproximación (bordillo/sin restricciones) y rango de rumbos de salida permitidos

Herramienta de imagen estática

Genera imágenes de mapas estáticos utilizando la API de imagen estática de Mapbox. Las características incluyen:

• Estilos de mapa personalizados (calles, exteriores, satélite, etc.)
• Dimensiones de imagen y niveles de zoom ajustables
• Soporte para múltiples marcadores con colores y etiquetas personalizados
• Opciones de superposición que incluyen polilíneas y polígonos
• Autoajuste a coordenadas especificadas

Herramienta de búsqueda por categoría

Realiza una búsqueda por categoría utilizando la API de búsqueda por categoría de Mapbox Search Box. Las características 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 enriquecidos para cada resultado
• Soporte para múltiples idiomas

Herramienta de geocodificación inversa

Realiza geocodificación inversa utilizando la API de geocodificación V6 de Mapbox. Las características incluyen:

• Convierte coordenadas geográficas en direcciones legibles por humanos
• Niveles de detalle personalizables (calle, vecindario, ciudad, etc.)
• Filtrado de resultados por tipo (dirección, poi, vecindario, etc.)
• Soporte para múltiples idiomas
• Información de contexto de ubicación enriquecida

Herramienta de ubicación en el terreno

Responde preguntas de "¿qué hay cerca de esta coordenada?" en una sola llamada: nombre del lugar, puntos de interés cercanos y accesibilidad por tiempo de viaje, todo con datos en vivo de Mapbox y citas. Úsela en lugar de encadenar reverse_geocode_tool con una búsqueda web.

Características:

• Clasifica la consulta (enrutamiento, contexto de vecindario, búsqueda de POI o región/accesibilidad) y obtiene solo los datos relevantes
• Búsqueda de POI cercanos por categoría, cuando se solicita
• Resumen de accesibilidad por tiempo de viaje (basado en isócronos)
• Devuelve una referencia render_map_tool con la ubicación fundamentada y los POI cercanos trazados

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

Herramienta de detalles de lugar

Recupera información detallada sobre un lugar específico utilizando su ID de Mapbox: fotos, horarios de apertura, calificaciones, números de teléfono y URL de sitios web. Úsela 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 ese primer resultado de cafetería: horarios, número de teléfono y sitio web"

Herramienta de direcciones

Obtiene direcciones de enrutamiento utilizando la API de direcciones de Mapbox. Las características incluyen:

• Soporte para diferentes perfiles de enrutamiento: automóvil (con tráfico en vivo o típico), caminar y bicicleta
• Ruta desde múltiples puntos de referencia (2-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 perfiles de automóvil y automóvil con tráfico
  • Hora de llegada deseada (arrive_by) solo para el perfil de automóvil
• Optimizaciones específicas del perfil:
  • Automóvil: restricciones de dimensiones del vehículo (altura, ancho, peso)
• Opciones de exclusión para enrutamiento:
  • Exclusiones comunes: rutas de ferry, peajes solo en efectivo
  • Exclusiones específicas de automóvil: peajes, autopistas, caminos sin pavimentar, túneles, fronteras de países, fronteras estatales
  • Exclusiones de puntos personalizados (hasta 50 puntos geográficos a evitar)
• Formato de salida de geometría GeoJSON

Herramienta de isócrono

Calcula áreas que son accesibles dentro de una cantidad de tiempo especificada desde una ubicación utilizando la API de isócrono de Mapbox. Las características incluyen:

• Soporte para diferentes perfiles de viaje (automóvil, caminar, bicicleta)
• Tiempos de viaje o distancias personalizables
• Generación de múltiples contornos (por ejemplo, rangos de 15, 30, 45 minutos)
• Especificación opcional de hora de salida o llegada
• Personalización de colores para visualización

Herramienta de búsqueda y geocodificación

Utiliza el endpoint de la API de búsqueda de texto de Mapbox Search Box para impulsar la búsqueda y geocodificación de POI, direcciones, lugares y cualquier otro tipo admitido por esa API. Esta herramienta consolida la funcionalidad que anteriormente proporcionaban ForwardGeocodeTool y PoiSearchTool (de versiones anteriores de este servidor MCP) en una sola herramienta.

Herramienta de coincidencia de mapas

Ajusta trazas GPS a la red de carreteras utilizando la API de coincidencia de mapas de Mapbox. Las características incluyen:

• Convierte trazas GPS ruidosas en rutas limpias en la red de carreteras
• Soporte para diferentes perfiles de viaje (automóvil, automóvil con tráfico, caminar, bicicleta)
• Maneja hasta 100 pares de coordenadas por solicitud
• Marcas de tiempo opcionales para mayor precisión basada en velocidad
• Radios de ajuste configurables para diferentes niveles de calidad de GPS
• Anotaciones de ruta (límites de velocidad, distancia, duración, congestión de tráfico)
• Múltiples formatos de salida de geometría (GeoJSON, polilínea)

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 a través de múltiples ubicaciones utilizando la API de optimización de Mapbox. Las características incluyen:

• Resuelve el problema del viajante (TSP) para 2-12 ubicaciones
• Soporte para diferentes perfiles de viaje (automóvil, automóvil con tráfico, caminar, bicicleta)
• Configuración flexible de puntos de inicio y fin
• Optimización de viaje de ida y vuelta o de un solo sentido
• Instrucciones de navegación giro a giro (opcional)
• Anotaciones de ruta (distancia, duración, velocidad)
• Múltiples formatos de salida de geometría (GeoJSON, polilínea)

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

Nota: Una API V2 con características avanzadas (ventanas de tiempo, restricciones de capacidad, múltiples vehículos) está disponible pero requiere acceso beta. La implementación V2 está incluida en el código base pero no está registrada por defecto.

Desarrollo

Inspeccionando el servidor

Usando Node.js

# Run the built image
npm run inspect:build

Usando 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 nueva herramienta

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

Publicando una Nueva Versión

# 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 del publicador valida que las versiones de package.json y server.json coincidan con la versión de lanzamiento. Omitir el aumento de versión o la sincronización del manifiesto causará fallos de publicación.

Trazado de OpenTelemetry

Este servidor MCP incluye trazado integral de OpenTelemetry para 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 desde tu archivo .env al iniciar. El archivo .env.example incluye ejemplos de configuración para múltiples plataformas de observabilidad.

Plataformas de Observabilidad Compatibles

Ejemplos de configuración incluidos en .env.example para:

Proveedores de Nube:

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

Plataformas SaaS:

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

Configuración de Producción

Consulta docs/tracing.md para instrucciones completas de configuración, incluyendo:

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

Características de Trazado:

• ✅ Trazado de carga de configuración (carga de archivo .env)
• ✅ Trazado automático de ejecución de herramientas
• ✅ Instrumentación de solicitudes HTTP con IDs de correlación de CloudFront
• ✅ Exportadores configurables (consola, OTLP)
• ✅ Consciente de la seguridad (protección de datos, validación JWT)
• ✅ Listo para producción (<1% de sobrecarga de CPU)

Contribuciones

¡Damos la bienvenida a contribuciones al Servidor MCP de Mapbox! Por favor, lee CONTRIBUTING.md antes de enviar una solicitud de extracción.

Estándares y pautas completos:

• CONTRIBUTING.md - Primeros pasos, proceso de PR, referencia rápida
• Estándares de Ingeniería (docs/engineering_standards.md) - Estándares completos de calidad de código, pruebas, documentación y colaboración
• Guía de Claude Code (CLAUDE.md) - Estándares y patrones para contribuyentes que usan Claude Code
• Instrucciones para Agentes de IA (AGENTS.md) - Guía para otros asistentes de codificación con IA (Cursor, Continue, Aider, etc.)
• Pautas de GitHub Copilot - Mejores prácticas para usar GitHub Copilot de manera responsable

Inicio Rápido para Contribuyentes

1. Haz un fork del repositorio y clona tu fork
2. Instala las dependencias: npm install
3. Realiza tus cambios siguiendo nuestros estándares de codificación
4. Ejecuta pruebas y linting: npm test && npm run lint
5. Añade pruebas para cualquier funcionalidad nueva
6. Envía una solicitud de extracción con una descripción clara

Todas las contribuciones deben pasar nuestras verificaciones de CI y el proceso de revisión de código. Consulta docs/engineering_standards.md para requisitos detallados.

Uso de Datos y Privacidad

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

Cuando usas las herramientas del servidor MCP, los siguientes datos se envían directamente desde tu entorno a las APIs de Mapbox:

• Herramientas de geocodificación: Texto de dirección/ubicación, coordenadas, filtros de país/región
• Herramientas de búsqueda: Consultas de búsqueda, coordenadas de ubicación para proximidad, filtros de categoría
• Herramienta de direcciones: Coordenadas de inicio/fin, puntos de ruta, preferencias de enrutamiento, restricciones de vehículo
• Herramienta de matriz: Múltiples pares de coordenadas, perfil de viaje, tiempos de salida
• Herramienta de mapa estático: Coordenadas, nivel de zoom, preferencias de estilo, información de marcadores
• Herramienta de isócrona: Coordenadas de origen, parámetros de tiempo/distancia, perfil de viaje

Tu privacidad

• Ejecución local: Todas las llamadas a la API se realizan directamente desde tu entorno a las APIs de Mapbox
• Seguridad del token: Tu token de API de Mapbox permanece en tu máquina local y nunca se transmite ni se almacena en este servidor MCP
• Sin almacenamiento de datos: Este servidor MCP no almacena, registra ni recopila ninguno de tus datos o solicitudes de API
• Comunicación directa: No hay servidor intermediario entre tú y las APIs de Mapbox

Uso de datos de terceros

• La política de privacidad de Mapbox rige los datos enviados a sus APIs: https://www.mapbox.com/legal/privacy/
• Uso de la API: Los términos estándar de la API de Mapbox se aplican a todas las solicitudes realizadas a través de estas herramientas
• Retención de datos: Consulta la documentación de Mapbox para sus políticas de retención de datos

Soporte y Contacto

Para Problemas con el Servidor MCP

• Correo electrónico: mcp-feedback@mapbox.com
• Problemas de GitHub: Reporta errores y solicitudes de funciones

Para Preguntas sobre la API de Mapbox

• Soporte de Mapbox: https://support.mapbox.com/
• Documentación: https://docs.mapbox.com/
• Estado de la API: https://status.mapbox.com/

Compromiso de Mantenimiento

Este servidor MCP es mantenido oficialmente por Mapbox, Inc. Proporcionamos:

• Actualizaciones periódicas para nuevas funciones de la API de Mapbox
• Correcciones de errores y actualizaciones de seguridad
• Compatibilidad con las últimas versiones del protocolo MCP
• Soporte comunitario a través de problemas de GitHub

---

Licencia MIT