OpenStreetMap MCP Server

Instructions

Implementation Reference

• src/osm_mcp_server/server.py:202-237 (handler)

  The primary handler function for the 'geocode_address' tool. It is registered via the @mcp.tool() decorator and implements the core logic by calling the OSMClient.geocode method, enhancing results with coordinates, and returning the geocoded locations.
  @mcp.tool() async def geocode_address(address: str, ctx: Context) -> List[Dict]: """ Convert an address or place name to geographic coordinates with detailed location information. This tool takes a text description of a location (such as an address, landmark name, or place of interest) and returns its precise geographic coordinates along with rich metadata. The results can be used for mapping, navigation, location-based analysis, and as input to other geospatial tools. Args: address: The address, place name, landmark, or description to geocode (e.g., "Empire State Building", "123 Main St, Springfield", "Golden Gate Park, San Francisco") Returns: List of matching locations with: - Geographic coordinates (latitude/longitude) - Formatted address - Administrative boundaries (city, state, country) - OSM type and ID - Bounding box (if applicable) - Importance ranking """ osm_client = ctx.request_context.lifespan_context.osm_client results = await osm_client.geocode(address) # Enhance results with additional context for result in results: if "lat" in result and "lon" in result: result["coordinates"] = { "latitude": float(result["lat"]), "longitude": float(result["lon"]) } return results
• src/osm_mcp_server/server.py:25-44 (helper)

  The supporting 'geocode' method in the OSMClient class that performs the actual HTTP request to Nominatim API for geocoding the address.
  async def geocode(self, query: str) -> List[Dict]: """Geocode an address or place name""" if not self.session: raise RuntimeError("OSM client not connected") nominatim_url = "https://nominatim.openstreetmap.org/search" async with self.session.get( nominatim_url, params={ "q": query, "format": "json", "limit": 5 }, headers={"User-Agent": "OSM-MCP-Server/1.0"} ) as response: if response.status == 200: return await response.json() else: raise Exception(f"Failed to geocode '{query}': {response.status}")
• src/osm_mcp_server/server.py:12-24 (helper)

  The OSMClient class that manages the HTTP session and provides the geocoding functionality used by the tool handler.
  class OSMClient: def __init__(self, base_url="https://api.openstreetmap.org/api/0.6"): self.base_url = base_url self.session = None self.cache = {} # Simple in-memory cache async def connect(self): self.session = aiohttp.ClientSession() async def disconnect(self): if self.session: await self.session.close()
• src/osm_mcp_server/server.py:202-202 (registration)

  The @mcp.tool() decorator registers the geocode_address function as an MCP tool.
  @mcp.tool()