Magic Lane MCP Server
The [Magic Lane MCP Server](https://developer.magiclane.com/docs/guides/mcp-server/) empowers AI agents with advanced geospatial intelligence. Built on [Magic Lane's](https://www.magiclane.com/) global mapping engine, it delivers fast place search, multi-stop and round-trip routing, isochrone analysis, reverse geocoding, geofencing, and rich visual map outputs for seamless, data-driven experiences.
Documentación
Magic Lane MCP Server
Introducción
El Servidor Magic Lane Model Context Protocol (MCP) permite que cualquier agente o aplicación de IA se convierta en un asistente geoespacialmente inteligente, capaz de actuar como un compañero confiable para peatones, ciclistas y conductores por igual.
Construido sobre la avanzada tecnología de mapas y enrutamiento de Magic Lane, este servidor MCP basado en TypeScript permite a los agentes de IA:
- Comprender y procesar datos geoespaciales,
- Interpretar la intención del usuario en un contexto espacial,
- Entregar orientación de navegación precisa y contextualmente relevante.
Al aprovechar los datos de mapas globales de Magic Lane y la inteligencia geoespacial en tiempo real, el Servidor MCP permite experiencias de navegación y planificación de viajes profundamente personalizadas a través de herramientas principales:
-
Intelligent Search - Encuentre direcciones, puntos de interés (POI) o coordenadas con capacidades de búsqueda inteligente y filtrado por categoría de POI.
-
Smart Routing - Genere rutas optimizadas entre múltiples puntos de paso con soporte para varios modos de transporte, preferencias de ruta e integración dinámica de POI.
-
Round Trip Planning - Cree rutas circulares que comienzan y terminan en la misma ubicación, perfectas para rutas para correr, circuitos en bicicleta o recorridos de entrega.
-
Reverse Geocoding - Convierta coordenadas geográficas en información de dirección detallada, incluyendo nombre de calle, ciudad, estado, país y código postal.
-
Isochrone Analysis - Calcule polígonos de accesibilidad que muestran áreas accesibles dentro de restricciones específicas de tiempo o distancia.
-
Route Visualization - Cree imágenes de mapas visuales de rutas calculadas, isocronas y viajes circulares para contexto geográfico y presentación inmediatos.
-
Geofence Management - Cree, gestione y consulte límites geográficos para monitoreo de activos, alertas basadas en ubicación y análisis espacial con soporte para polígonos, círculos y rectángulos.
-
Interactive Map - Muestre un mapa de teselas vectoriales interactivo directamente dentro de la conversación usando MapLibre GL JS y teselas vectoriales de MagicLane. Admite vistas de ubicación, visualización de rutas, superposiciones de isocronas, rutas de viaje circular, marcadores de resultados de búsqueda, áreas de geofence y rutas de coordenadas personalizadas — con una o muchas superposiciones por mapa e interacciones de paneo y zoom.
Las funcionalidades de mapas se pueden visualizar como imágenes de mapas de alta calidad a través de nuestra nueva función beta:
- Static Map Rendering - Genere vistas de mapas personalizadas con marcadores, cuadros delimitadores o áreas centradas en la ubicación sin cálculo de rutas, complementando la visualización de rutas para rutas, isocronas y viajes circulares.
En conjunto, estas capacidades permiten que los agentes de IA actúen como verdaderos copilotos geoespaciales — comprendiendo el contexto espacial, anticipando las necesidades del usuario y optimizando cada viaje con precisión y facilidad.
Opciones de transporte: El servidor admite tanto stdio (para clientes nativos de MCP como Claude Desktop) como HTTP (para aplicaciones web, implementaciones sin servidor e integraciones personalizadas).
Primeros pasos
Requisitos previos
El Servidor Magic Lane MCP se integra perfectamente con cualquier aplicación o agente de IA, proporcionando acceso a datos geoespaciales y funcionalidad de navegación. Antes de la configuración, asegúrese de tener lo siguiente:
Requisitos del sistema:
- Node.js 22+ instalado (Descargar aquí)
- npm (viene con Node.js)
- Una clave API de Magic Lane válida (para acceso a datos de mapas)
- Un cliente de IA compatible con MCP, como:
- Claude Desktop
- Cursor IDE
- Visual Studio Code con GitHub Copilot
Verificar requisitos previos:
# Check Node.js version (should be 22+)
node --version
# Check npm version
npm --version
Inicio rápido
Para pruebas inmediatas, use npx para ejecutar el servidor sin instalación:
# Set your API key as environment variable
export MAGICLANE_API_KEY="your_api_key"
# Run the server directly
npx @magiclane/mcp-server
Configuración de la clave API
Para obtener un token de API de Magic Lane, siga nuestra guía paso a paso. Los pasos detallados son:
-
Cree una cuenta de Magic Lane
- Visite developer.magiclane.com/api/register y regístrese para obtener una cuenta gratuita.
-
Genere una clave API
- Inicie sesión en su cuenta
- Navegue al Panel de Proyectos
- Siga las instrucciones para generar su clave API única, que servirá como su token de acceso para el Servidor MCP
Instalación
Para explorar e integrar el Servidor MCP localmente, siga estos pasos para instalar dependencias y compilar el proyecto:
# Clone or navigate to the Magic Lane MCP Server directory
cd path/to/magiclane-mcp
# Install dependencies
npm install
# Build the TypeScript project
npm run build
# Verify the build was successful
ls dist/ # Should show map-server.esm.js and other compiled files
Nota: Asegúrese de que Node.js 22+ y npm estén instalados correctamente antes de ejecutar estos comandos.
Ejecución del servidor
Servidor MCP estándar (transporte stdio):
# Option 1: Using .env file (recommended)
cp .env.example .env
# Edit .env with your actual API key
npm start
# Option 2: Using Node's built-in env file support
node --env-file=.env dist/map-server.esm.js
# Option 3: Using environment variable directly
MAGICLANE_API_KEY=your_api_key npm start
Servidor HTTP (para clientes web y personalizados):
# Development mode (with auto-reload)
npm run dev:http
# Production mode (after build)
npm run start:http
Para documentación completa del servidor HTTP, incluidos endpoints, ejemplos de JSON-RPC e integración de clientes, consulte la Guía de configuración del servidor HTTP.
Configuración
Configure su cliente MCP para conectarse al servidor de Magic Lane. Siga la guía de configuración detallada para su cliente de IA específico:
- Guía de configuración de Claude Desktop - Instrucciones completas de configuración para Claude Desktop
- Guía de configuración de Cursor AI - Configuración paso a paso para Cursor IDE
- Guía de configuración de VS Code - Guía de integración para Visual Studio Code con GitHub Copilot
Cada guía incluye:
- Ubicaciones de archivos de configuración específicos del cliente
- Múltiples opciones de instalación (compilación local, NPM, Docker)
- Instrucciones específicas de plataforma (Windows, macOS, Linux)
Docker
Compile y ejecute el servidor usando Docker:
# Build the Docker image
docker build -t magiclane-mcp-server .
# Run the container (pass API key via environment variable)
docker run --rm -e MAGICLANE_API_KEY=your_api_key magiclane-mcp-server
# Or use an env file
docker run --rm --env-file .env magiclane-mcp-server
Variables de entorno:
| Variable | Requerida | Descripción |
|---|---|---|
MAGICLANE_API_KEY | Sí | Su clave API de Magic Lane para autenticación |
VERBOSE | No | Establezca en true para imprimir registros informativos/de depuración/advertencias. Los errores siempre se registran. El valor predeterminado es false. |
HTTP_TIMEOUT_SECONDS | No | Tiempo de espera (en segundos) para solicitudes salientes a la API de Magic Lane. Entero positivo. El valor predeterminado es 30. |
El contenedor se ejecuta con --enable-source-maps para mejores seguimientos de pila en producción.
Herramientas disponibles
El Servidor Magic Lane MCP proporciona varias herramientas geoespaciales integradas que permiten a los sistemas de IA buscar, planificar, analizar y visualizar rutas y ubicaciones.
¿Busca imágenes de mapas renderizadas y demostraciones de mapas interactivos en vivo? Consulte Ejemplos visuales.
1. Búsqueda de ubicaciones
La Herramienta de búsqueda de ubicaciones utiliza la API REST de búsqueda de Magic Lane para encontrar:
- Coordenadas, direcciones o áreas administrativas.
- Puntos de interés (POI) alrededor de una ubicación de referencia (restaurantes, gasolineras, farmacias, etc.).
Parámetros de entrada
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
text | string | - | Consulta de texto libre (p. ej., nombre de POI, dirección o ciudad) |
target | string | - | Tipo de resultado: pois (POI), addresses (direcciones de calle) o cities. Requerido. |
poi_categories | array | - | Filtros de categoría de POI. Requerido cuando target es pois. Valores válidos: gas_stations, parking, food&drink, accommodation, medical_services, shopping, car_services, public_transport, sightseeing, etc. |
reference_location | object | - | Contexto geográfico: { coordinates: { longitude, latitude } } (preferido) y/o { location_text } (nombre de ciudad/región/país). Al menos uno es requerido. |
locale | string | "en" | Idioma de respuesta (código de idioma ISO 639-2 / ISO 639-3) |
limit | number | 5 | Número máximo de resultados, clasificados por relevancia |
Ejemplos de indicaciones
-
Exploración urbana y turismo
- "Busque restaurantes italianos auténticos en el centro de Chicago a poca distancia a pie de Millennium Park."
- "¿Dónde están los cajeros automáticos cerca de la Puerta de Brandeburgo, Berlín?"
-
Negocios y logística
- "Localice el 'DHL Service Point' más cercano a la Estación Central de Berlín."
- "Encuentre todas las ubicaciones de Starbucks dentro de 1 km de nuestra oficina en 1 Market Street, San Francisco."
- "¿Dónde están los estacionamientos cerca de la Estación Central de Ámsterdam?"
-
Bienes raíces y propiedades
- "Muestre todas las escuelas primarias cerca de 456 Maple Avenue, Portland, Oregón, con sus distancias exactas desde la propiedad."
- "Localice farmacias, tiendas de comestibles y paradas de transporte público cerca de la propiedad en Baker Street 221B, Londres."
2. Planificador de rutas
La Herramienta de planificador de rutas genera rutas optimizadas entre múltiples puntos utilizando la API REST de enrutamiento de Magic Lane y la API REST de gestión de flotas de Magic Lane. Esta herramienta admite las siguientes capacidades:
- Enrutamiento de punto a punto y de múltiples paradas (A -> B -> C).
- Inclusión de POI (p. ej., gasolineras, restaurantes).
- Optimización avanzada de VRP para rutas de múltiples entregas.
- Consideraciones de tráfico, restricciones y terreno.
- Instrucciones de ruta multilingües.
Parámetros de entrada
| Parameter | Type | Default | Description |
|---|---|---|---|
transport | string | "car" | Tipo de transporte (car, lorry, truck, pedestrian, bike, public) |
type | string | "fastest" | Objetivo de optimización. fastest/shortest funcionan para todos los modos de transporte. economic es solo para eBike: requiere transport: "bike" y un vehicle.profile de pedelec/spedelec. scenic no es válido para transport: "bike". |
origin | string | - | Ubicación de inicio (nombre o coordenadas) |
destination | string | - | Ubicación de fin (nombre o coordenadas) |
intermediate_waypoints | array | [] | Lista de paradas entre el inicio y el fin. El orden determina la generación de la ruta. Cada punto de paso define preferencias y restricciones específicas. |
avoid | array | [] | Elementos a evitar (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks) |
vehicle | object | null | Características del vehículo, incluyendo dimensiones, peso, tipo de combustible, parámetros EV y preferencia de perfil. Consulte Especificación del vehículo para obtener detalles completos. |
details | string | "full" | Nivel de detalle de la respuesta: full (geometría + giro a giro), path (solo geometría), timedistance (solo totales) |
number_of_routes | number | 1 | Número de rutas (1-3 para coche/camión/bicicleta/peatón; 1-11 para transporte público) |
fitness_factor | number | 0.5 | Tolerancia de esfuerzo del terreno para bicicleta / peatón, 0.0 (fácil) a 1.0 (exigente) |
emergency | boolean | false | Habilitar enrutamiento de vehículos de emergencia (relaja ciertas restricciones de tráfico) |
locale | string | "en" | Idioma de las instrucciones giro a giro (código de idioma ISO 639-2 / ISO 639-3) |
Estructura de Puntos de Paso Intermedios
Cada entrada en intermediate_waypoints representa una parada. El discriminador type determina la forma de waypoint y qué campos se aplican:
| Parameter | Type | Default | Description |
|---|---|---|---|
type | string | - | Discriminador de forma de parada. Uno de: coordinates (punto fijo), address (resuelto desde un lugar/dirección de texto libre), reference_poi (POI resuelto cerca de una ubicación de referencia), along_route_poi (búsqueda de categoría de POI a lo largo del corredor de la ruta). |
waypoint | object | - | Datos de ubicación. La forma debe coincidir con type: para coordinates, proporcione coordinates: { longitude, latitude }; para address/reference_poi/along_route_poi, proporcione location con parámetros de búsqueda (text, target, reference_location y poi_categories cuando el objetivo sea pois). |
max_poi_deviation | number | 1000 | Distancia perpendicular máxima desde la polilínea de la ruta (en metros) para considerar candidatos POI. Se aplica solo a along_route_poi. |
location_poi_preference | string | "no matter" | Indicación de colocación para paradas along_route_poi. Uno de: based on reference location, midpoint of the route, after some distance from departure, no matter. |
location_poi_distance | number | - | Indicación de colocación numérica. Cuando location_poi_preference es after some distance from departure y representa el número de metros desde la salida. Se ignora en caso contrario. |
Ejemplos de Prompts
-
Viajes y Turismo Internacional
- "Genera una ruta en bicicleta panorámica desde Viena hasta Bratislava, evitando autopistas."
- "Planifica un viaje por carretera desde Múnich hasta Venecia con paradas en Innsbruck y Bolzano, optimizado para vistas panorámicas."
-
Transporte Público y Desplazamientos
- "Encuentra una ruta de transporte público desde Londres hasta Oxford con transferencias mínimas."
- "¿Cuál es la forma más rápida de ir desde el Aeropuerto JFK hasta Manhattan usando transporte público?"
-
Turismo y Eventos con Múltiples Paradas
- "Crea un recorrido a pie desde el Coliseo hasta la Fontana de Trevi, parando en el Panteón y en una heladería."
- "Estoy en la Torre Eiffel y necesito visitar Notre-Dame, el Museo del Louvre y volver a mi hotel cerca de Gare du Nord. Planifica la mejor ruta en coche."
-
Enrutamiento de Emergencia y Prioridad
- "Encuentra la ruta más rápida desde la Estación de Ambulancias St. John, Westminster, hasta el Hospital General, evitando tráfico y bloqueos."
- "Calcula la ruta más rápida para servicios de emergencia desde la Estación de Bomberos 23 hasta el incidente reportado en Pike Place Market."
-
Enrutamiento de Vehículos Eléctricos
- "Estoy conduciendo un Tesla Model 3 con 60% de batería desde San Francisco hasta Los Ángeles. Encuentra la ruta óptima con paradas de carga necesarias, asegurando que llegue con al menos 20% de carga."
- "Calcula una ruta para mi furgoneta eléctrica (batería de 80 kWh, autonomía de 250 km) desde Berlín hasta Praga con paradas de carga rápida en el camino."
3. Isochrone Calculator
La Isochrone Calculator Tool proporciona análisis espacial para determinar todas las áreas alcanzables desde un punto de referencia dentro de restricciones específicas de tiempo de viaje o distancia, utilizando la Magic Lane Isochrones REST API. Esto permite a los sistemas de IA analizar zonas de accesibilidad, áreas de cobertura de servicios y estudios de alcanzabilidad.
Características clave:
- Calcular polígonos de alcanzabilidad basados en restricciones de tiempo o distancia
- Soporte para múltiples modos de transporte (caminar, andar en bicicleta, conducir, transporte público)
- Resolución de la ubicación de salida mediante coordenadas o geocodificación
- Análisis de múltiples rangos para estudios de accesibilidad complejos
Parámetros de entrada
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
transport | string | "car" | Modo de transporte (car, lorry, truck, pedestrian, bike, public) |
type | string | "fastest" | Modelo de coste y unidades para ranges. fastest/shortest funcionan para todos los modos de transporte. economic es solo eBike — requiere transport: "bike" Y un vehicle.profile pedelec/spedelec. scenic NO es válido para transport: "bike". |
departure | object | - | Punto de origen: { coordinates: { longitude, latitude } } o { location: { text, ... } } |
ranges | array | - | Uno o más umbrales. Segundos cuando type es fastest/economic/scenic; metros cuando type es shortest. Todos los valores positivos. |
avoid | array | [] | Elementos a evitar (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks) |
vehicle | object | null | Características del vehículo, incluyendo dimensiones, peso, tipo de combustible, parámetros EV y preferencia de perfil. Consulte Especificación del vehículo para obtener detalles completos. |
locale | string | "en" | Idioma del resultado (código de idioma ISO 639-2 / ISO 639-3) |
Ejemplos de prompts
- "¿A dónde puedo ir en bicicleta en 45 minutos desde la Estación Central de Ámsterdam?"
- "Mostrar todas las áreas a 10 minutos a pie de la estación Atlantic Avenue-Barclays Center en Brooklyn."
- "Mostrar el área de influencia de 1 hora en coche desde la ubicación propuesta del almacén en Fráncfort."
4. Planificador de rutas circulares
La herramienta Planificador de rutas circulares genera rutas circulares que comienzan y terminan en la misma ubicación. Esta herramienta es perfecta para crear rutas de exploración, circuitos en bicicleta, senderos para correr y recorridos de entrega.
Características principales:
- Rutas circulares con retorno garantizado al punto de partida
- Generación de rutas basada en tiempo o distancia
- Soporte para múltiples modos de transporte (caminar, bicicleta, conducir)
- Preferencias de terreno y omisión de colinas para ciclistas
- Longitud y complejidad de ruta personalizables
Parámetros de entrada
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
transport | string | "car" | Modo de transporte (car, lorry, truck, pedestrian, bike, public) |
type | string | "fastest" | Objetivo de optimización y unidades para range. fastest/shortest funcionan para todos los modos de transporte. economic es solo eBike — requiere transport: "bike" Y un vehicle.profile pedelec/spedelec. scenic NO es válido para transport: "bike". |
departure | object | - | Punto de inicio Y fin del bucle: { coordinates: { longitude, latitude } } o { location: { text, ... } } |
range | number | - | Tamaño objetivo del bucle. Segundos cuando type es fastest/economic/scenic; metros cuando type es shortest. Debe ser positivo. |
avoid | array | [] | Elementos a evitar (highway, toll, ferry, unpaved, turnaround, traffic, roadblocks) |
terrain | boolean | false | Incluir perfil de elevación/terreno en la respuesta |
departure_time | number | 0 | Hora de salida como segundos de época Unix; 0 usa la hora actual del servidor |
profile | string | - | Atajo de subperfil de nivel superior para bicicleta (city, road, cross, mountain, opcionalmente con sufijo _pedelec/_spedelec) o peatón (walk, hike). Si vehicle.profile también está configurado, vehicle.profile gana. |
vehicle | object | null | Características del vehículo, incluyendo dimensiones, peso, tipo de combustible, parámetros EV y preferencia de perfil. Consulte Especificación del vehículo para obtener detalles completos. |
random_seed | number | 0 | Semilla entera para la generación reproducible de bucles |
locale | string | "en" | Idioma de respuesta (código de idioma ISO 639-2 / ISO 639-3) |
Ejemplos de prompts
-
Fitness y recreación
- "Crea un circuito de 10 km para correr desde Central Park."
- "Diseña un circuito de 90 minutos en bicicleta desde Stephansplatz."
-
Turismo y exploración
- "Genera un circuito de 45 minutos a pie desde la Torre Eiffel."
- "Planifica un circuito de 2 horas a pie desde Times Square."
-
Rutas en bicicleta
- "Crea un circuito de 25 km en bicicleta desde Whistler Village, evitando autopistas."
- "Diseña un circuito de 1 hora en bicicleta desde Golden Gate Park usando la ruta más corta."
5. Geocodificación inversa
La herramienta de Geocodificación inversa convierte coordenadas geográficas o áreas en información de dirección detallada utilizando la API REST de Geocodificación inversa de Magic Lane. Esta herramienta proporciona componentes de dirección completos para diversas consultas espaciales.
Características principales:
- Conversión de punto a dirección para coordenadas específicas
- Búsqueda alrededor de un punto, dentro de un área o a lo largo de una ruta
- Devuelve múltiples resultados de dirección con clasificación por distancia
- Incluye jerarquía administrativa (asentamiento, ciudad, condado, estado, país)
- Identifica puntos de interés cercanos
Parámetros de entrada
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
coordinates | object | - | Punto de coordenadas específico { longitude, latitude } para búsqueda de dirección |
insideArea | object | - | Definición de área: cuadro delimitador (bbox) con límites east, west, north, south; área circular con center y radius metros; o polígono a partir de cadena de polilínea o matriz de coordenadas (mínimo 3 puntos) |
along | object | - | Definición de ruta (polilínea codificada o coordenadas) con radius en metros para encontrar direcciones a lo largo |
limit | number | 5 | Número máximo de resultados a devolver |
locale | string | "en" | Idioma del resultado (código de idioma ISO 639-2 / ISO 639-3) |
Ejemplos de prompts
- "¿Cuál es la dirección en las coordenadas 51.5074, -0.1278?"
- "Encuentra todas las direcciones en un radio de 500 metros de la Puerta de Brandeburgo."
6. Administrador de geocercas
La herramienta Administrador de geocercas proporciona operaciones completas de geocercas para definir y gestionar límites geográficos, habilitando servicios basados en ubicación y monitoreo de activos. Esta herramienta admite crear, recuperar, actualizar, eliminar geocercas y verificar si los puntos caen dentro de los límites definidos.
Características principales:
- Crear geocercas con geometrías de polígono, círculo o rectángulo
- Consultar geocercas por ID, dentro de cuadros delimitadores o por proximidad a un punto
- Actualizar propiedades de geocerca (nombre, palabras clave)
- Eliminar geocercas por ID
- Verificar si coordenadas específicas caen dentro de geocercas
- Soporte para metadatos y etiquetas personalizados
Operaciones y parámetros
Operación de creación - Crea una o más geocercas con los siguientes parámetros:
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
id | string | - | Identificador personalizado (se genera automáticamente si no se proporciona) |
name | string | - | Nombre legible por humanos |
keywords | array | [] | Etiquetas para búsqueda y filtrado |
properties | object | - | Metadatos personalizados adicionales |
geojson_type | string | - | Tipo de geometría: polygon, circle o rectangle |
geojson_area | object | - | Definición del área (coordenadas de polígono, centro/radio de círculo o bbox) |
Operación de lectura - Recupera una o más geocercas con los siguientes parámetros:
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
geofence_ids | array | - | Matriz de IDs de geocercas a recuperar |
box_limited | object | - | Filtro de caja delimitadora (norte, sur, este, oeste) |
proximity_area | object | - | Buscar geocercas cerca de un punto (reference_point, distance, limit) |
Operación de actualización - Modifica propiedades de una geocerca existente con los siguientes parámetros:
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
geofence_id | string | - | ID de la geocerca a actualizar |
name | string | - | Nombre legible por humanos para actualizar la geocerca |
keywords | array | [] | Palabras clave/etiquetas actualizadas para el área de la geocerca |
Operación de eliminación - Elimina una o más geocercas con los siguientes parámetros:
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
geofence_ids | array | - | Matriz de IDs de geocercas a eliminar |
Operación de verificación de punto - Determina si las coordenadas caen dentro de geocercas con los siguientes parámetros:
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
geofence_ids | array | - | Matriz de IDs de geocercas a verificar |
points | array | - | Matriz de ubicaciones a probar; cada entrada usa coordinates: { longitude, latitude } o location (parámetros de búsqueda) |
Ejemplos de solicitudes
-
Monitoreo y seguimiento de activos
- "Crea una geocerca circular con radio de 500m alrededor de nuestro almacén en 123 Main Street, Chicago."
- "¿Está el vehículo de reparto en las coordenadas 40.7589, -73.9851 dentro de la geocerca de la zona de Main Street?"
-
Gestión de áreas restringidas
- "Crea una geocerca rectangular 'construction-zone-1' que cubra el centro de Seattle delimitada por estas coordenadas: norte 47.6205, sur 47.5990, este -122.3250, oeste -122.3450."
- "Actualiza la geocerca 'construction-zone-1' para incluir las palabras clave 'temporary' y 'high-priority'."
-
Área de servicio y zonas de entrega
- "Crea tres geocercas circulares de zona de entrega: 'berlin-warehouse-1' en coordenadas 13.3777, 52.5163 con radio de 2km, 'berlin-warehouse-2' en 13.4050, 52.5200 con radio de 1.5km, y 'berlin-warehouse-3' en 13.3888, 52.5170 con radio de 2.5km."
- "Muéstrame todas las geocercas dentro de 2km de la Puerta de Brandeburgo en coordenadas 13.3777, 52.5163."
- "Recupera todas las geocercas con IDs: 'zone-premium-01', 'zone-premium-02' y 'zone-premium-03' que estén etiquetadas con 'premium-service'."
-
Alertas basadas en ubicación
- "Elimina las geocercas temporales de eventos con IDs: 'summer-festival-2025-main', 'summer-festival-2025-parking' y 'summer-festival-2025-stage' ahora que el evento ha terminado."
- "Lista todas las geocercas dentro de la caja delimitadora que cubre Manhattan: norte 40.8820, sur 40.7006, este -73.9070, oeste -74.0479."
- "Encuentra todas las geocercas cerca de Times Square dentro de 1000 metros y muestra sus nombres y palabras clave."
7. Renderizador de mapas estáticos
La herramienta de renderizado genera imágenes de mapas estáticos de rutas calculadas, isocronas, viajes de ida y vuelta y vistas de mapas personalizadas utilizando el servicio de renderizado de Magic Lane. Proporciona contexto visual inmediato superponiendo datos geográficos en un mapa y devolviendo el resultado como una imagen incrustada.
Características principales:
- Renderiza rutas, isocronas y viajes de ida y vuelta como imágenes PNG, JPEG o WebP
- Calcula automáticamente el viewport óptimo para encuadrar todos los datos relevantes
- Genera vistas de mapas estáticos centrados en una ubicación o delimitados por coordenadas personalizadas
- Entrega imágenes directamente al cliente MCP como datos codificados en base64; para
routing,isochroneyround_tripun bloque de texto JSON con los detalles de la ruta subyacente acompaña a la imagen, por lo que no se necesita una llamada de cálculo separada
Parámetros de entrada
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
render_type | string | - | Tipo de visualización: routing, isochrone, round_trip o map_location |
output_format | string | "image/png" | Formato de imagen de salida: image/png (predeterminado), image/jpeg o image/webp |
parameters | object | - | Parámetros que coinciden con el render_type seleccionado. Para routing, isochrone y round_trip, acepta los mismos parámetros que la herramienta de cálculo respectiva. Para map_location: width (px, predeterminado 800), height (px, predeterminado 600), corners ([minLon, minLat, maxLon, maxLat]) para ajustar una caja delimitadora, o around_location (referenceLocation + radio de distance en metros, predeterminado 500) para centrar en un punto. |
Ejemplos de solicitudes
-
Representación de ruta
- "Estoy en 10 Downing Street, Londres - por favor muestra una ruta en coche a la Catedral de San Pablo."
-
Representación de viaje de ida y vuelta
- "Visualiza una ruta de jogging de 5.5km que comienza desde el Rijksmuseum en Ámsterdam."
-
Representación de isocrona
- "Por favor muestra un mapa de París con una isocrona de 15 minutos a pie."
-
Representación de mapa estático
- "Muestra una vista amplia de Miami, incluyendo la playa y el Distrito Histórico Art Deco."
Consulta Ejemplos visuales para ver la salida renderizada de estas solicitudes.
8. Mapa interactivo
La herramienta de mapa interactivo renderiza teselas vectoriales de MagicLane en un mapa totalmente interactivo directamente dentro de la conversación usando MapLibre GL JS y MCP Apps. A diferencia del renderizador estático, los usuarios pueden desplazarse, hacer zoom y explorar el widget del mapa sin salir del cliente de chat.
Características principales:
- Transmite teselas vectoriales en vivo desde el servicio de mapas global de MagicLane
- Ajusta automáticamente el viewport a los datos mostrados: ubicación, ruta, isocrona, viaje de ida y vuelta, resultados de búsqueda, áreas de geocercas o una ruta de coordenadas personalizada
- Dibuja una o muchas superposiciones en el mismo mapa (rutas, isocronas, geocercas, rutas) - cada forma en su propio color
- Soporta interacciones de desplazamiento y zoom en clientes compatibles con MCP Apps
Parámetros de entrada
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
zoom | number | 12 | Nivel de zoom del mapa (0 = vista mundial, 16 = nivel de calle). Se ignora para routing, isochrone, round_trip y path (y cuando se dibujan múltiples superposiciones) - el viewport se ajusta automáticamente a los datos. |
overlayParameters | array | - | Superposiciones a dibujar (al menos una entrada). Cada entrada es un objeto { display_type, parameters }. Pasa una sola entrada para una superposición, o varias para dibujarlas todas en el mismo mapa - las entradas pueden repetir un tipo (por ejemplo, dos entradas routing para dos rutas) o mezclar tipos (por ejemplo, una ruta más una isocrona más geocercas). Cada forma dibujada recibe automáticamente un color distinto. |
Cada entrada overlayParameters tiene:| Campo | Tipo | Descripción |
| :------------: | :----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| display_type | string | Modo de visualización: location, routing, isochrone, round_trip, search_results, geofence o path |
| parameters | object | Acepta los mismos parámetros que la herramienta de cálculo correspondiente y debe coincidir con el display_type de esta entrada. Renderiza rutas con visualización completa del trazado, polígonos de accesibilidad como áreas sombreadas o rutas circulares con puntos de inicio/fin marcados, según el display_type seleccionado. Para display_type: path, pasa coordinates como un array de puntos [longitude, latitude] (al menos 2) más un label opcional para dibujar la polilínea tal cual. |
Ejemplos de Prompts
-
Vista de Ubicación
- "Muéstrame un mapa interactivo centrado en la Torre Eiffel"
- "Muestra un mapa interactivo del centro de Tokio."
-
Visualización de Rutas
- "Muestra un mapa interactivo de la ruta en coche de Ámsterdam a Bruselas."
- "Muestra una ruta en bicicleta desde Central Park hasta Brooklyn Bridge en un mapa interactivo, incluyendo una parada en una farmacia."
-
Superposición de Isócronas
- "Muestra en un mapa interactivo todos los lugares a los que puedo llegar en coche en 30 minutos desde la Estación Central de Berlín."
- "Muestra una isócrona a pie de 20 minutos desde Trafalgar Square en un mapa interactivo."
-
Viaje de Ida y Vuelta
- "Muestra un circuito de jogging de 10 km desde Vondelpark en un mapa interactivo."
-
Resultados de Búsqueda
- "Muestra todas las cafeterías cerca del Louvre en un mapa interactivo."
- "Muestra restaurantes a menos de 1 km de Notre-Dame en un mapa interactivo."
-
Ruta Personalizada
- "Dibuja esta pista GPS en un mapa interactivo: [[2.35, 48.85], [2.34, 48.86], [2.33, 48.87]]."
- "Traza una línea en un mapa interactivo, etiquétala como 'Ruta de reparto', usando las coordenadas [[11.8793, 46.4372], [11.8694, 46.4329], [11.8597, 46.4339], [11.8504, 46.4341], [11.8406, 46.4187], [11.8378, 46.4149], [11.8437, 46.4103]]."
Explora demos HTML ejecutables para cada
display_typeen Ejemplos Visuales.
Solución de Problemas
Problemas Comunes
El Servidor No Se Inicia
# Check if Node.js version is 22+
node --version
# Verify API key is set
echo $MAGICLANE_API_KEY
# Check for build errors
npm run build
Problemas con la Clave de API
- Asegúrate de que tu clave de API sea válida y esté activa en el Panel de Magic Lane
- Verifica que la variable de entorno esté configurada correctamente:
MAGICLANE_API_KEY=your_key - Comprueba si hay espacios adicionales o comillas en la clave de API
Problemas de Conexión
- Verifica que la configuración de tu cliente MCP coincida con la ruta del servidor
- Asegúrate de que el servidor esté ejecutándose antes de conectar el cliente
- Revisa la configuración del firewall si usas conexiones remotas
Límites de Velocidad
- La API de Magic Lane tiene límites de velocidad; consulta tu panel para ver el uso actual
- Implementa caché de solicitudes para rutas de acceso frecuente
- Considera actualizar tu plan de API si se exceden los límites
Mensajes de Error Comunes
- Acceso no autorizado (401): Clave de API no válida. Revisa tu configuración.
- Sin resultados (404): No se pudo encontrar la ubicación. Prueba con una consulta diferente.
- Demasiadas solicitudes (429): Límite de velocidad excedido. Revisa tu panel de uso.
- Solicitud incorrecta (400): Parámetros no válidos. Revisa el formato de tu entrada.
Política de Privacidad
Magic Lane está comprometido con proteger tu privacidad y manejar tus datos de manera responsable. Para información completa sobre privacidad, consulta nuestra política de privacidad completa: https://www.magiclane.com/web/terms-and-conditions#privacy
Recopilación de Datos
- Datos de consulta: Los términos de búsqueda de ubicaciones, orígenes/destinos de rutas y coordenadas enviadas a través del servidor MCP se transmiten a la API de Magic Lane para su procesamiento. No se almacenan ni registran por Magic Lane después de entregar la respuesta.
- Clave de API: Tu clave de API se transmite con cada solicitud únicamente para autenticación y límites de velocidad. Nunca se comparte con terceros.
- Sin perfilado de usuarios: Magic Lane no crea perfiles de usuario, no rastrea patrones de uso entre sesiones ni correlaciona solicitudes individuales.
Cómo Se Usan los Datos
- Todas las solicitudes se procesan en tiempo real para generar la respuesta geoespacial solicitada (ruta, resultado de búsqueda, isócrona, etc.).
- Los datos procesados se descartan inmediatamente después de entregar la respuesta.
- El renderizado de mapas se realiza dinámicamente; las imágenes generadas no se conservan después de la transmisión.
Almacenamiento y Retención de Datos
- Magic Lane no almacena de forma persistente el contenido de solicitudes de rutas, consultas de ubicaciones, parámetros de búsqueda ni entradas de geocodificación inversa.
- No se retienen datos de sesión ni historial de solicitudes en los servidores de Magic Lane.
Datos de Terceros
- Magic Lane utiliza datos de OpenStreetMap y otros conjuntos de datos geográficos disponibles públicamente
- No se comparten datos de ubicación personales o propietarios con terceros
- Los datos de tráfico y rutas se agregan y anonimizan en el origen
Para información detallada, revisa nuestros Términos de Servicio y Política de Privacidad.
Soporte
- Documentación: developer.magiclane.com/docs
- Panel de API: developer.magiclane.com/api/dashboard
- Problemas en GitHub: github.com/magiclane/magiclane-mcp-server/issues
- Soporte del Portal de Desarrolladores: Contacta con el soporte a través del portal de desarrolladores