# OpenStreetMap MCP Server

A Model Context Protocol (MCP) server that integrates OpenStreetMap routing capabilities with Claude AI for advanced route planning, cost estimation, and place search using OpenRouteService API.

## Features

- **Route Calculation**: Get optimal routes between multiple points
- **Route Comparison**: Compare different routing options (avoid tolls, highways, etc.)
- **Distance Matrix**: Calculate distances and durations between multiple origins and destinations
- **Cost Estimation**: Estimate fuel and toll costs for trips
- **Place Search**: Find places using OpenStreetMap geocoding
- **Multiple Transport Modes**: Support for driving, walking, and cycling

## Prerequisites

- **Node.js** (LTS version 18+ recommended) - Download from [nodejs.org](https://nodejs.org)
- **OpenRouteService API Key** - Get one free from [openrouteservice.org](https://openrouteservice.org)
- **Claude Desktop** application for MCP integration

## Setup Instructions

### 1. Clone and Install

```bash
git clone [your-repo-url]
cd openstreetmap-mcp-server
npm install
```

### 2. Get OpenRouteService API Key

1. Go to [openrouteservice.org](https://openrouteservice.org)
2. Sign up for a free account
3. Navigate to your dashboard
4. Create a new API key
5. Copy the API key for configuration

### 3. Configure API Key

Edit `config/config.json` and replace the API key:

```json
{
  "openStreetMap": {
    "apiKey": "your-actual-api-key-here"
  }
}
```

### 4. Test the Server

```bash
# Test configuration
npm test

# Start in development mode
npm run dev
```

### 5. Configure Claude Desktop

Add this to your Claude Desktop MCP settings file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "openstreetmap": {
      "command": "node",
      "args": ["/absolute/path/to/openstreetmap-mcp-server/src/index.js"],
      "cwd": "/absolute/path/to/openstreetmap-mcp-server"
    }
  }
}
```

### 6. Start Using

Restart Claude Desktop and you can now ask questions like:

- "Find the best route from Paris to Berlin"
- "Compare routes to the airport with and without tolls"
- "What's the estimated cost for driving from London to Edinburgh?"
- "Find restaurants near Times Square"

## Available Tools

### calculate_route
Get optimal route using OpenStreetMap data with waypoints support.

**Parameters:**
- `origin` (required): Starting point (address or coordinates in lat,lng format)
- `destination` (required): Ending point (address or coordinates in lat,lng format)
- `waypoints` (optional): Array of intermediate points
- `mode` (optional): Transport mode - driving, walking, bicycling, transit
- `avoidTolls` (optional): Boolean to avoid toll roads
- `avoidHighways` (optional): Boolean to avoid highways

### compare_routes
Compare multiple route alternatives with different options.

**Parameters:**
- `origin` (required): Starting point
- `destination` (required): Ending point
- `options` (required): Array of routing options to compare

### get_matrix
Get distance and duration matrix between multiple origins and destinations.

**Parameters:**
- `origins` (required): Array of origin points
- `destinations` (required): Array of destination points

### get_traffic_info
Get basic route information (Note: Real-time traffic not available in OpenStreetMap).

**Parameters:**
- `origin` (required): Starting point
- `destination` (required): Ending point

### estimate_costs
Calculate trip costs including fuel and toll estimates.

**Parameters:**
- `origin` (required): Starting point
- `destination` (required): Ending point
- `fuelPricePerLiter` (optional): Price of fuel per liter (default: 1.50)
- `vehicleFuelEfficiency` (optional): Vehicle efficiency in km/liter (default: 8.0)
- `tollEstimatePerKm` (optional): Estimated toll cost per km (default: 0.05)

### find_places
Search for places using OpenStreetMap geocoding service.

**Parameters:**
- `query` (required): Search query (e.g., "restaurants", "hotels")
- `location` (optional): Center location for search
- `radius` (optional): Search radius in meters (default: 1000)

## Configuration Options

Edit `config/config.json` to customize:

```json
{
  "openStreetMap": {
    "apiKey": "your-api-key"
  },
  "server": {
    "port": 3001,
    "host": "localhost"
  },
  "routing": {
    "defaultProfile": "driving-car",
    "maxWaypoints": 25,
    "maxAlternatives": 3,
    "units": "metric"
  },
  "costs": {
    "fuelPricePerLiter": 1.50,
    "vehicleFuelEfficiency": 8.0,
    "tollEstimatePerKm": 0.05
  }
}
```

## Troubleshooting

### Common Issues

**1. "Error loading config" message**
- Check that `config/config.json` exists and has valid JSON format
- Ensure the API key is properly set

**2. "API request failed" errors**
- Verify your OpenRouteService API key is valid and active
- Check your API quota limits at openrouteservice.org
- Ensure you have internet connectivity

**3. "Address not found" errors**
- Try using coordinates instead of addresses (lat,lng format)
- Verify the location exists and is accessible
- Check spelling of address

**4. Server won't start**
```bash
# Check Node.js version
node --version  # Should be 18+

# Clear dependencies and reinstall
rm -rf node_modules package-lock.json
npm install

# Check for configuration errors
npm test
```

**5. Claude Desktop can't find the server**
- Use absolute paths in Claude Desktop config
- Restart Claude Desktop after configuration changes
- Check that the MCP config file path is correct for your OS

### Debug Mode

Run with debug logging:

```bash
DEBUG=* npm start
```

### Testing Individual Functions

You can test the server functionality by creating test scripts or using the npm test command.

## Differences from Google Maps

This OpenStreetMap MCP server provides similar functionality to Google Maps but with some key differences:

### Advantages
- **Free and Open Source**: No usage limits for basic features
- **Privacy Focused**: No tracking or data collection
- **Community Driven**: Data maintained by volunteers worldwide
- **Customizable**: Full control over routing profiles and preferences

### Limitations
- **No Real-time Traffic**: Traffic data is not available
- **Limited Transit**: Public transportation routing is limited
- **Geocoding Quality**: May be less accurate in some regions compared to Google
- **Commercial POI**: Fewer commercial points of interest

## API Rate Limits

OpenRouteService free tier includes:
- 2,000 requests per day
- 40 requests per minute
- 2,000 requests per month for matrix calculations

For higher limits, consider upgrading to a paid plan at openrouteservice.org.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - feel free to modify and distribute.

## About

OpenStreetMap MCP Server - Bringing open-source mapping to Claude AI

Built with:
- [OpenRouteService API](https://openrouteservice.org)
- [OpenStreetMap](https://openstreetmap.org)
- [Model Context Protocol](https://modelcontextprotocol.io)



### reverse_geocode
Get location name and address from latitude and longitude coordinates.

**Parameters:**
- `latitude` (required): Latitude coordinate (between -90 and 90)
- `longitude` (required): Longitude coordinate (between -180 and 180)
- `zoom` (optional): Zoom level for detail (1-18, higher = more detailed, default: 18)

**Example Usage:**
```javascript
reverse_geocode({
  latitude: 48.8584,
  longitude: 2.2945
})
```

**Response Format:**
```json
{
  "status": "success",
  "coordinates": {
    "latitude": 48.8584,
    "longitude": 2.2945
  },
  "address": {
    "formatted_address": "Tour Eiffel, Avenue Gustave Eiffel, Gros-Caillou, 7e Arrondissement, Paris, Île-de-France, France métropolitaine, 75007, France",
    "name": "Tour Eiffel",
    "street": "Avenue Gustave Eiffel",
    "neighbourhood": "Gros-Caillou",
    "locality": "Paris",
    "region": "Île-de-France",
    "country": "France",
    "country_code": "FR",
    "postal_code": "75007"
  }
}
```