OpenStreetMap MCP Server

Instructions

Implementation Reference

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

  The primary handler function for the 'get_route_directions' MCP tool. It validates input, fetches raw route data from the OSMClient.get_route helper, processes the response to extract summary, turn-by-turn directions, geometry, and waypoints, and returns structured output.
  @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 makes the actual HTTP request to OSRM routing service, handling parameters for mode, steps, overview, and annotations, and returns raw route JSON data.
  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}")
• src/osm_mcp_server/server.py:360-391 (schema)

  Docstring defining the input parameters, their types, defaults, descriptions, and expected return format for the get_route_directions tool, serving as the schema documentation.
  """ 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 } """
• src/osm_mcp_server/server.py:348-348 (registration)

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