Strava MCP Server

Instructions

Implementation Reference

• server.py:107-117 (handler)

  MCP tool registration and handler for get_activity_laps_tool. Decorated with @mcp.tool(), this function accepts activity_id parameter, authenticates the client, calls get_activity_laps service function, and returns lap data as list of dictionaries.

  @mcp.tool()
  def get_activity_laps_tool(activity_id: int) -> list[dict]:
      """
      Get lap breakdowns for a specific activity.
  
      Args:
          activity_id: The ID of the activity to retrieve laps for
      """
      client = get_client()
      laps = get_activity_laps(client, activity_id)
      return [lap.to_dict() for lap in laps]

• strava_mcp/services/streams.py:8-40 (handler)

  Core implementation of get_activity_laps. Fetches lap data from Strava API using client.get_activity_laps(), processes each lap's attributes (moving_time, elapsed_time, distance, speed, cadence, watts, heartrate, elevation), and converts them to LapSummary objects.

  def get_activity_laps(client: Client, activity_id: int) -> list[LapSummary]:
      """Get lap breakdowns for a specific activity."""
      laps = client.get_activity_laps(activity_id)
  
      result = []
      for lap in laps:
          moving_time = getattr(lap.moving_time, "seconds", 0) if lap.moving_time else 0
          elapsed_time = (
              getattr(lap.elapsed_time, "seconds", 0) if lap.elapsed_time else 0
          )
  
          summary = LapSummary(
              id=lap.id or 0,
              activity_id=getattr(lap, "activity_id", 0) or 0,
              lap_index=getattr(lap, "lap_index", 0),
              name=lap.name or "",
              elapsed_time=elapsed_time,
              moving_time=moving_time,
              distance=float(lap.distance) if lap.distance else 0.0,
              average_speed=float(lap.average_speed) if lap.average_speed else 0.0,
              max_speed=float(lap.max_speed) if lap.max_speed else 0.0,
              average_cadence=float(lap.average_cadence) if lap.average_cadence else None,
              average_watts=float(lap.average_watts) if lap.average_watts else None,
              average_heartrate=float(lap.average_heartrate)
              if lap.average_heartrate
              else None,
              max_heartrate=float(lap.max_heartrate) if lap.max_heartrate else None,
              total_elevation_gain=float(lap.total_elevation_gain)
              if lap.total_elevation_gain
              else 0.0,
          )
          result.append(summary)
      return result

• strava_mcp/models.py:82-103 (schema)

  LapSummary dataclass schema defining the structure of lap data returned by get_activity_laps_tool. Contains fields: id, activity_id, lap_index, name, elapsed_time, moving_time, distance, average_speed, max_speed, average_cadence, average_watts, average_heartrate, max_heartrate, total_elevation_gain. Includes to_dict() method for serialization.

  @dataclass
  class LapSummary:
      """Summary of a lap in a Strava activity."""
  
      id: int
      activity_id: int
      lap_index: int
      name: str
      elapsed_time: int
      moving_time: int
      distance: float
      average_speed: float
      max_speed: float
      average_cadence: Optional[float]
      average_watts: Optional[float]
      average_heartrate: Optional[float]
      max_heartrate: Optional[float]
      total_elevation_gain: float
  
      def to_dict(self) -> dict:
          """Convert to dictionary for serialization."""
          return asdict(self)