OpenStreetMap MCP Server

Instructions

Implementation Reference

• src/osm_mcp_server/server.py:348-439 (handler)

  The main @mcp.tool()-decorated async handler function implementing the 'get_route_directions' tool. Validates input mode, calls OSMClient.get_route to fetch OSRM route data, processes routes to extract summary, turn-by-turn directions, geometry, and waypoints.
  @mcp.tool() async def get_route_directions( from_latitude: float, from_longitude: float, to_latitude: float, to_longitude: float, ctx: Context, mode: str = "car", steps: bool = False, overview: str = "simplified", annotations: bool = False ) -> Dict[str, Any]: """ Calculate detailed route directions between two geographic points. This tool provides comprehensive routing information between two locations using OpenStreetMap/OSRM. The output can be minimized using the steps, overview, and annotations parameters to reduce the response size. Args: from_latitude: Starting point latitude (decimal degrees) from_longitude: Starting point longitude (decimal degrees) to_latitude: Destination latitude (decimal degrees) to_longitude: Destination longitude (decimal degrees) ctx: Context (provided internally by MCP) mode: Transportation mode ("car", "bike", "foot") steps: Turn-by-turn instructions (True/False, Default: False) overview: Geometry output ("full", "simplified", "false"; Default: "simplified") annotations: Additional segment info (True/False, Default: False) Returns: Dictionary with routing information (summary, directions, geometry, waypoints) Example: { "from_latitude": 51.3334193, "from_longitude": 9.4540423, "to_latitude": 51.3295516, "to_longitude": 9.4576721, "mode": "car", "steps": false, "overview": "simplified", "annotations": false } """ osm_client = ctx.request_context.lifespan_context.osm_client # Validate transportation mode valid_modes = ["car", "bike", "foot"] if mode not in valid_modes: ctx.warning(f"Invalid mode '{mode}'. Using 'car' instead.") mode = "car" ctx.info(f"Calculating {mode} route from ({from_latitude}, {from_longitude}) to ({to_latitude}, {to_longitude})") # Get route from OSRM route_data = await osm_client.get_route( from_latitude, from_longitude, to_latitude, to_longitude, mode, steps=steps, overview=overview, annotations=annotations ) # Process and simplify the response if "routes" in route_data and len(route_data["routes"]) > 0: route = route_data["routes"][0] # Extract turn-by-turn directions steps_list = [] if "legs" in route: for leg in route["legs"]: for step in leg.get("steps", []): steps_list.append({ "instruction": step.get("maneuver", {}).get("instruction", ""), "distance": step.get("distance"), "duration": step.get("duration"), "name": step.get("name", "") }) return { "summary": { "distance": route.get("distance"), # meters "duration": route.get("duration"), # seconds "mode": mode }, "directions": steps_list, "geometry": route.get("geometry"), "waypoints": route_data.get("waypoints", []) } else: raise Exception("No route found")
• src/osm_mcp_server/server.py:65-92 (helper)

  Supporting helper method in OSMClient class that queries the OSRM routing API to retrieve raw route data between coordinates, which is then processed by the main handler.
  async def get_route(self, from_lat: float, from_lon: float, to_lat: float, to_lon: float, mode: str = "car", steps: bool = False, overview: str = "overview", annotations: bool = True) -> Dict: """Get routing information between two points""" if not self.session: raise RuntimeError("OSM client not connected") # Use OSRM for routing osrm_url = f"http://router.project-osrm.org/route/v1/{mode}/{from_lon},{from_lat};{to_lon},{to_lat}" params = { "overview": overview, "geometries": "geojson", "steps": str(steps).lower(), "annotations": str(annotations).lower() } async with self.session.get(osrm_url, params=params) as response: if response.status == 200: return await response.json() else: raise Exception(f"Failed to get route: {response.status}")