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}")