Skip to main content
Glama
aatakansalar

Valhalla MCP Server

by aatakansalar
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Valhalla MCP Server

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

Example Usage

Claude Desktop Integration

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

Features

Currently Supported Valhalla Services

MCP Tool/Resource

Valhalla Service

Description

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

Service

Description

Use 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

Transportation Modes

  • auto - Car routing

  • bicycle - Bicycle routing

  • pedestrian - Walking routes

  • taxi - Taxi routing

  • bus - Public transit routing

Quick Start

Prerequisites

  • 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

Test Your Installation

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!

Development Mode

For development with auto-reload:

npm run dev

Configuration

Environment Variables

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

cp env.example .env

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.

Docker Deployment

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

Usage Examples

Route Calculation

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

Isochrone Generation

Generate a 15-minute travel time polygon:

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

Health Check

Access server health information:

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

Integration with MCP Clients

Claude Desktop

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.

Other MCP Clients

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

Architecture

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

Development

Installation

# 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

Testing

# 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

Type Checking

The project uses strict TypeScript configuration:

# Type check npx tsc --noEmit

Performance

  • Route calculation: < 200ms (local Valhalla instance)

  • Isochrone generation: < 300ms

  • Tile serving: < 30ms

  • Health check: < 5ms

Performance depends on Valhalla configuration and available OSM data.

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests

  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

For issues and questions:

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/aatakansalar/valhalla-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server