Valhalla MCP Server

Un servidor para el motor de enrutamiento Valhalla, que ofrece servicios de enrutamiento, isócronas, estado y teselas.

Documentación

Valhalla MCP Server

Un servidor de Model Context Protocol (MCP) que proporciona una integración perfecta entre Claude Desktop y el motor de enrutamiento Valhalla de Open-Street-Map. Acceda a capacidades profesionales de enrutamiento e isócronas directamente desde sus conversaciones con IA sin APIs complejas.

Ejemplo de Uso

Claude Desktop Integration

Claude Desktop mostrando un cálculo de ruta entre dos puntos con respuesta GeoJSON detallada de Valhalla MCP Server

Características

Servicios Valhalla Actualmente Soportados

Herramienta/Recurso MCP	Servicio Valhalla	Descripción
`route` herramienta	`/route`	Enrutamiento de origen único → destino con alternativas
`isochrone` herramienta	`/isochrone`	Polígonos de tiempo de viaje que muestran áreas alcanzables
`health` recurso	`/status`	Información de estado y versión del servidor
`tile` recurso	`/tile/{z}/{x}/{y}`	Teselas vectoriales para renderizado en el cliente

Servicios Valhalla - Próximamente

Servicio	Descripción	Casos de Uso
Matrix	Matrices de distancia/tiempo para múltiples orígenes/destinos	Optimización de entregas, planificación logística
Map-matching	Coincidir coordenadas GPS con la red de carreteras	Limpieza de trazas GPS, corrección de rutas
Elevation	Perfiles de elevación a lo largo de rutas o en puntos	Rutas de senderismo, análisis de dificultad
Expansion	Visualización de recorrido de grafos	Análisis de redes, estudios de accesibilidad
Locate	Metadatos detallados sobre nodos y aristas	Geocodificación de direcciones, atributos de carreteras
Centroid	Punto de convergencia óptimo desde múltiples ubicaciones	Optimización de puntos de encuentro
Optimized Route	Enrutamiento de entregas con múltiples paradas y restricciones	Logística, servicios de entrega

Modos de Transporte

auto - Enrutamiento en coche
bicycle - Enrutamiento en bicicleta
pedestrian - Rutas a pie
taxi - Enrutamiento en taxi
bus - Enrutamiento en transporte público

Inicio Rápido

Requisitos Previos

Node.js 18+
Claude Desktop
Gestor de paquetes NPM o Yarn

Opción 1: Servidor Valhalla Local

Para uso en producción o conjuntos de datos personalizados:

# Prerequisites: Docker and Docker Compose
./start-mcp.sh

Este script:

Compilará el servidor MCP
Iniciará Valhalla local con datos OSM de Mónaco
Esperará a que los servicios estén listos
Ejecutará pruebas de integración
Proporcionará configuración de Claude Desktop

Opción 2: Usar su Servidor Valhalla Existente

Si ya tiene un servidor Valhalla ejecutándose en otro lugar:

# Clone and setup
git clone <repository-url>
cd valhalla-mcp
npm install
npm run build

# Configure environment variables
cp env.example .env
# Edit .env file and set VALHALLA_BASE_URL=http://your-valhalla-server:8002

Integración con Claude Desktop

Abra la configuración de Claude Desktop
Añada a su configuración de MCP:

Para API de demostración (recomendado para pruebas):

{
  "mcpServers": {
    "valhalla-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/YOUR/PATH/TO/valhalla-mcp",
      "env": {
        "VALHALLA_BASE_URL": "https://valhalla1.openstreetmap.de"
      }
    }
  }
}

Para Servidor Valhalla Local:

{
  "mcpServers": {
    "valhalla-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/YOUR/PATH/TO/valhalla-mcp",
      "env": {
        "VALHALLA_BASE_URL": "http://localhost:8002"
      }
    }
  }
}

Actualice la ruta cwd a la ubicación real de su proyecto
Reinicie Claude Desktop

Pruebe su Instalación

Pruebe estos comandos en Claude Desktop para verificar que todo funciona:

Enrutamiento básico:

"Calcular ruta desde Monaco-Ville hasta Monte Carlo"
"Obtener indicaciones de conducción desde 43.7384,7.4246 hasta 43.7396,7.4263"
"Calcular ruta en bicicleta desde 43.7350,7.4200 hasta 43.7450,7.4300"

Análisis de tiempo de viaje:

"Mostrar isócrona de 10 minutos en coche desde el centro de Mónaco"
"Generar polígono de viaje en bicicleta de 15 minutos desde 43.7311,7.4197"

¡Debería recibir respuestas GeoJSON detalladas con geometrías de ruta y estadísticas de viaje!

Modo de Desarrollo

Para desarrollo con recarga automática:

npm run dev

Configuración

Variables de Entorno

El servidor utiliza variables de entorno para la configuración. Cree un archivo .env a partir de la plantilla:

cp env.example .env

Variables de entorno disponibles:

VALHALLA_BASE_URL - URL base para el servicio Valhalla (por defecto: http://localhost:8002)
DEBUG - Habilitar registro de depuración (por defecto: false)
LOG_LEVEL - Nivel de registro: error, warn, info, debug (por defecto: info)
MCP_SERVER_NAME - Nombre del servidor MCP (por defecto: valhalla-mcp-server)
MCP_SERVER_VERSION - Versión del servidor MCP (por defecto: 0.1.0)

Endpoints comunes de Valhalla:

http://localhost:8002 - Instancia Docker local (recomendado)
https://valhalla1.openstreetmap.de - API de demostración pública (✅ probada y funcionando)
https://your-server.com:8002 - Despliegue personalizado

Nota: La URL de demostración principal https://valhalla.openstreetmap.de sirve una interfaz web. Use https://valhalla1.openstreetmap.de para acceso a la API.

Despliegue con Docker

La pila completa se puede desplegar usando Docker Compose:

# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f valhalla-mcp

# Stop services
docker-compose down

Ejemplos de Uso

Cálculo de Ruta

Solicite una ruta entre dos puntos:

{
  "tool": "route",
  "arguments": {
    "origin": { "lat": 52.5200, "lon": 13.4050 },
    "destination": { "lat": 52.5170, "lon": 13.3888 },
    "mode": "bicycle",
    "alternatives": 2,
    "units": "kilometers"
  }
}

La respuesta incluye GeoJSON LineString con la geometría de la ruta y estadísticas resumidas:

{
  "type": "FeatureCollection",
  "features": [{
    "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [[13.4050, 52.5200], [13.3888, 52.5170]]
    },
    "properties": {
      "distance_km": 2.1,
      "duration_seconds": 420,
      "duration_minutes": 7,
      "mode": "bicycle"
    }
  }]
}

Generación de Isócronas

Genere un polígono de tiempo de viaje de 15 minutos:

{
  "tool": "isochrone",
  "arguments": {
    "origin": { "lat": 52.5200, "lon": 13.4050 },
    "minutes": 15,
    "mode": "pedestrian"
  }
}

Verificación de Salud

Acceda a la información de salud del servidor:

{
  "resource": "health://status"
}

Integración con Clientes MCP

Claude Desktop

Añada a su configuración de Claude Desktop:

{
  "mcpServers": {
    "valhalla": {
      "command": "node",
      "args": ["/path/to/valhalla-mcp/dist/index.js"],
      "env": {
        "VALHALLA_BASE_URL": "https://valhalla1.openstreetmap.de"
      }
    }
  }
}

Nota: Las variables de entorno en la configuración de Claude Desktop anulan los valores del archivo .env.

Otros Clientes MCP

El servidor implementa el protocolo MCP estándar y funciona con cualquier cliente compatible. Use el transporte stdio para integración local.

Arquitectura

┌─────────────────┐     MCP Protocol     ┌─────────────────┐
│   MCP Client    │ ◄─────────────────► │ Valhalla MCP    │
│ (Claude, etc.)  │    (stdio/HTTP)      │     Server      │
└─────────────────┘                      └─────────┬───────┘
                                                   │ HTTP REST
                                         ┌─────────▼───────┐
                                         │   Valhalla      │
                                         │  Routing Engine │
                                         └─────────────────┘

Desarrollo

Instalación

# Install dependencies
npm install

# Build the project
npm run build

Dependencias clave:

@modelcontextprotocol/sdk - SDK oficial de MCP
axios - Cliente HTTP para llamadas a la API de Valhalla
zod - Validación de tipos en tiempo de ejecución
geojson - Definiciones de tipos GeoJSON
dotenv - Gestión de variables de entorno

Pruebas

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

Verificación de Tipos

El proyecto utiliza configuración estricta de TypeScript:

# Type check
npx tsc --noEmit

Rendimiento

Cálculo de ruta: < 200ms (instancia Valhalla local)
Generación de isócronas: < 300ms
Servicio de teselas: < 30ms
Verificación de salud: < 5ms

El rendimiento depende de la configuración de Valhalla y de los datos OSM disponibles.

Contribuciones

Haga un fork del repositorio
Cree una rama de características
Realice sus cambios
Añada pruebas
Envíe una solicitud de extracción

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.

Agradecimientos

Para problemas y preguntas:

Abra un issue en GitHub
Consulte la documentación de MCP
Revise la documentación de Valhalla