Show HN: Valhalla MCP – Route and Isochrone API for Claude via Valhalla

4 months ago 12

A Model Context Protocol (MCP) server that provides seamless integration between Claude Desktop and the Valhalla Open-Street-Map routing engine. Access professional routing and isochrone capabilities directly from your AI conversations without complex APIs.

License Node.js Docker

Claude Desktop Integration

Claude Desktop showing a route calculation between two points with detailed GeoJSON response from Valhalla MCP Server

Currently Supported Valhalla Services

MCP Tool/ResourceValhalla ServiceDescription
route tool /route Single origin → destination routing with alternatives
isochrone tool /isochrone Travel time polygons showing reachable areas
health resource /status Server status and version information
tile resource /tile/{z}/{x}/{y} Vector tiles for client-side rendering

Valhalla Services - Coming Soon

ServiceDescriptionUse Cases
Matrix Distance/time matrices for multiple origins/destinations Delivery optimization, logistics planning
Map-matching Match GPS coordinates to road network GPS trace cleaning, route correction
Elevation Elevation profiles along routes or at points Hiking routes, difficulty analysis
Expansion Graph traversal visualization Network analysis, reachability studies
Locate Detailed metadata about nodes and edges Address geocoding, road attributes
Centroid Optimal convergence point from multiple locations Meeting point optimization
Optimized Route Multi-stop delivery routing with constraints Logistics, delivery services
  • auto - Car routing
  • bicycle - Bicycle routing
  • pedestrian - Walking routes
  • taxi - Taxi routing
  • bus - Public transit routing
  • Node.js 18+
  • Claude Desktop
  • NPM or Yarn package manager

Option 1: Local Valhalla Server

For production use or custom datasets:

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

This script will:

  • Build the MCP server
  • Start local Valhalla with Monaco OSM data
  • Wait for services to be ready
  • Run integration tests
  • Provide Claude Desktop configuration

Option 2: Use Your Pre-existing Valhalla Server

If you already have a Valhalla server running elsewhere:

# 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

Claude Desktop Integration

  1. Open Claude Desktop settings
  2. Add to your MCP configuration:

For Demo API (recommended for testing):

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

For Local Valhalla Server:

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

  1. Update the cwd path to your actual project location

  2. Restart Claude Desktop

Try these commands in Claude Desktop to verify everything works:

Basic routing:

  • "Calculate route from Monaco-Ville to Monte Carlo"
  • "Get driving directions from 43.7384,7.4246 to 43.7396,7.4263"
  • "Calculate bicycle route from 43.7350,7.4200 to 43.7450,7.4300"

Travel time analysis:

  • "Show 10-minute drive isochrone from Monaco center"
  • "Generate 15-minute bicycle travel polygon from 43.7311,7.4197"

You should receive detailed GeoJSON responses with route geometries and travel statistics!

For development with auto-reload:

The server uses environment variables for configuration. Create a .env file from the template:

Available environment variables:

  • VALHALLA_BASE_URL - Base URL for Valhalla service (default: http://localhost:8002)
  • DEBUG - Enable debug logging (default: false)
  • LOG_LEVEL - Log level: error, warn, info, debug (default: info)
  • MCP_SERVER_NAME - MCP server name (default: valhalla-mcp-server)
  • MCP_SERVER_VERSION - MCP server version (default: 0.1.0)

Common Valhalla endpoints:

  • http://localhost:8002 - Local Docker instance (recommended)
  • https://valhalla1.openstreetmap.de - Public demo API (✅ tested and working)
  • https://your-server.com:8002 - Custom deployment

Note: The main demo URL https://valhalla.openstreetmap.de serves a web interface. Use https://valhalla1.openstreetmap.de for API access.

The complete stack can be deployed using Docker Compose:

# Build and start all services docker-compose up -d # View logs docker-compose logs -f valhalla-mcp # Stop services docker-compose down

Request a route between two points:

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

Response includes GeoJSON LineString with route geometry and summary statistics:

{ "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" } }] }

Generate a 15-minute travel time polygon:

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

Access server health information:

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

Integration with MCP Clients

Add to your Claude Desktop configuration:

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

Note: Environment variables in Claude Desktop config override .env file values.

The server implements the standard MCP protocol and works with any compliant client. Use stdio transport for local integration.

┌─────────────────┐ MCP Protocol ┌─────────────────┐ │ MCP Client │ ◄─────────────────► │ Valhalla MCP │ │ (Claude, etc.) │ (stdio/HTTP) │ Server │ └─────────────────┘ └─────────┬───────┘ │ HTTP REST ┌─────────▼───────┐ │ Valhalla │ │ Routing Engine │ └─────────────────┘
# Install dependencies npm install # Build the project npm run build

Key dependencies:

  • @modelcontextprotocol/sdk - Official MCP SDK
  • axios - HTTP client for Valhalla API calls
  • zod - Runtime type validation
  • geojson - GeoJSON type definitions
  • dotenv - Environment variable management
# 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

The project uses strict TypeScript configuration:

# Type check npx tsc --noEmit
  • Route calculation: < 200ms (local Valhalla instance)
  • Isochrone generation: < 300ms
  • Tile serving: < 30ms
  • Health check: < 5ms

Performance depends on Valhalla configuration and available OSM data.

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

MIT License - see LICENSE file for details.

For issues and questions:

Read Entire Article
  1. Homepage
  2. Technology
  3. Show HN: Valhalla MCP – Route and Isochrone API for Claude via Valhalla

Related

Visualizing Intersecting Sets

Visualizing Intersecting Sets

18 minutes ago 0
Ask HN: What's a Purchase You Regret?

Ask HN: What's a Purchase You Regret?

18 minutes ago 0
Vue-Transify v1.3.0

Vue-Transify v1.3.0

23 minutes ago 0
Hostinger Web Hosting