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.

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

- 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

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

- 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

- Open Claude Desktop settings
- Add to your MCP configuration:

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

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

-

Update thecwdpath to your actual project location

Try these commands in Claude Desktop to verify everything works:

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

- "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!

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

- 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)

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

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

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

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

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.envfile values.

The server implements the standard MCP protocol and works with any compliant client. Usestdiotransport 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

- @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:

- Route calculation: < 200ms (local Valhalla instance)
- Isochrone generation: < 300ms
- Tile serving: < 30ms
- Health check: < 5ms

Performance depends on Valhalla configuration and available OSM data.
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests
- Submit a pull request

MIT License - seeLICENSEfile for details.

- Open an issue on GitHub
- Check theMCP documentation
- Review Valhalla documentation

A Node.js server for the Model Context Protocol that provides access to the Autodesk Platform Services (APS) API with fine-grained access control.