OSM MCP Server

An OpenStreetMap (OSM) data access server built using the Model Context Protocol (MCP). This server provides geocoding, reverse geocoding, and OSM vector data retrieval capabilities through a standardized MCP interface.

Features

• Geocoding: Convert addresses and place names to geographic coordinates
• Reverse Geocoding: Find place names from geographic coordinates
• OSM Vector Data Query: Retrieve OSM elements (nodes, ways, relations) with custom filters
• GeoJSON Output: All vector data is returned in standard GeoJSON format
• Rate Limiting: Built-in respect for OSM API rate limits
• Error Handling: Comprehensive error handling with detailed error messages

Usage

As an MCP Server

The server is designed to run as a subprocess and communicate via stdio. It can be integrated with any MCP-compatible client.

python main.py

Available Tools

1. Geocoding (geocode)

Convert addresses or place names to coordinates.

Parameters:

• query (string, required): Address or place name to geocode
• limit (integer, optional): Maximum number of results (default: 5, max: 20)

Example:

{
  "name": "geocode",
  "arguments": {
    "query": "Paris, France",
    "limit": 3
  }
}

2. Reverse Geocoding (reverse_geocode)

Find place names from coordinates.

Parameters:

• lat (number, required): Latitude coordinate
• lon (number, required): Longitude coordinate
• zoom (integer, optional): Detail level (3=country, 10=city, 18=building, default: 18)

Example:

{
  "name": "reverse_geocode",
  "arguments": {
    "lat": 48.8566,
    "lon": 2.3522,
    "zoom": 10
  }
}

3. OSM Vector Data Query (query_osm)

Retrieve OSM elements within a specified area.

Parameters:

• area (object, required): Area definition (bbox, place, or around)
• filters (array, required): OSM tag filters
• element_types (array, optional): OSM element types to include (default: all)
• limit (integer, optional): Maximum number of results (default: 100, max: 1000)

Area Types:

Bounding Box:

{
  "type": "bbox",
  "south": 48.8,
  "west": 2.3,
  "north": 48.9,
  "east": 2.4
}

Place Name:

{
  "type": "place",
  "name": "Paris"
}

Around Point:

{
  "type": "around",
  "lat": 48.8566,
  "lon": 2.3522,
  "radius": 1000
}

Filter Examples:

[
  {"key": "amenity", "value": "restaurant"},
  {"key": "name", "contains": "McDonald"},
  {"key": "highway"}
]

Complete Example:

{
  "name": "query_osm",
  "arguments": {
    "area": {
      "type": "bbox",
      "south": 48.8,
      "west": 2.3,
      "north": 48.9,
      "east": 2.4
    },
    "filters": [
      {"key": "amenity", "value": "restaurant"}
    ],
    "element_types": ["node", "way"],
    "limit": 50
  }
}

API Endpoints

The server uses the following external APIs:

• Nominatim API: For geocoding and reverse geocoding

  • Base URL: https://nominatim.openstreetmap.org
  • Rate limit: 1 request per second

• Overpass API: For OSM vector data queries

  • Base URL: https://overpass-api.de/api/interpreter
  • Rate limit: Varies by server load

Error Handling

The server returns structured error responses with the following format:

{
  "error": "error_type",
  "message": "Human-readable error message",
  "details": {
    "additional": "error details"
  }
}

Common Error Types:

• not_found: No results found for the query
• invalid_params: Invalid input parameters
• api_error: External API error
• rate_limit: Rate limit exceeded
• timeout: Request timed out
• network_error: Network connectivity issues
• internal_error: Internal server error

Testing

To verify the installation and functionality:

# Test basic functionality
python -c "import main; print('✓ OSM MCP Server imports successfully')"

# Test MCP server startup
python -c "import subprocess, sys; p = subprocess.Popen([sys.executable, 'main.py']); p.terminate(); p.wait(); print('✓ MCP Server starts successfully')"

You can also test the OSM functionality directly by importing the OSMMCPServer class and calling its methods.