Strava MCP Server

Instructions

Implementation Reference

• server.py:27-35 (registration)

  Tool registration and entry point for get_athlete_stats_tool. Decorated with @mcp.tool(), it retrieves the Strava client, calls the service layer get_athlete_stats function, and returns a formatted string.

  @mcp.tool()
  def get_athlete_stats_tool() -> str:
      """
      Get statistics for the authenticated athlete.
      Returns a formatted string with recent and all-time stats.
      """
      client = get_client()
      stats = get_athlete_stats(client)
      return stats.to_formatted_string()

• strava_mcp/services/athlete.py:7-36 (handler)

  Core handler logic for fetching athlete statistics. Gets athlete info from Strava API, retrieves stats, and constructs an AthleteStats object with recent and all-time run/ride totals.

  def get_athlete_stats(client: Client) -> AthleteStats:
      """Get statistics for the authenticated athlete."""
      athlete = client.get_athlete()
      stats = client.get_athlete_stats(athlete.id)
  
      def get_val(obj, attr, default=None):
          val = getattr(obj, attr, default) if obj else default
          if val is None:
              return default
          return val
  
      recent_run = stats.recent_run_totals
      all_run = stats.all_run_totals
      recent_ride = stats.recent_ride_totals
  
      return AthleteStats(
          firstname=getattr(athlete, "firstname", ""),
          lastname=getattr(athlete, "lastname", ""),
          recent_run_totals=ActivityTotals(
              distance=float(get_val(recent_run, "distance", 0.0)),
              achievement_count=int(get_val(recent_run, "achievement_count", 0)),
          ),
          all_run_totals=ActivityTotals(
              distance=float(get_val(all_run, "distance", 0.0)),
          ),
          recent_ride_totals=ActivityTotals(
              distance=float(get_val(recent_ride, "distance", 0.0)),
              elevation_gain=float(get_val(recent_ride, "elevation_gain", 0.0)),
          ),
      )

• strava_mcp/models.py:16-38 (schema)

  AthleteStats dataclass definition that models the athlete statistics structure, including firstname, lastname, and totals for runs and rides. Includes to_formatted_string() method for display.

  @dataclass
  class AthleteStats:
      """Statistics for the authenticated athlete."""
  
      firstname: str = ""
      lastname: str = ""
      recent_run_totals: ActivityTotals = field(default_factory=ActivityTotals)
      all_run_totals: ActivityTotals = field(default_factory=ActivityTotals)
      recent_ride_totals: ActivityTotals = field(default_factory=ActivityTotals)
  
      def to_formatted_string(self) -> str:
          """Convert stats to formatted string for display."""
          return f"""
  Athlete: {self.firstname} {self.lastname}
  Recent Run Totals:
    Distance: {self.recent_run_totals.distance}
    Achievement Count: {self.recent_run_totals.achievement_count}
  All-Time Run Totals:
    Distance: {self.all_run_totals.distance}
  Recent Ride Totals:
    Distance: {self.recent_ride_totals.distance}
    Elevation Gain: {self.recent_ride_totals.elevation_gain}
  """

• strava_mcp/models.py:7-13 (schema)

  ActivityTotals dataclass definition for modeling activity totals (distance, achievement_count, elevation_gain) used within AthleteStats.

  @dataclass
  class ActivityTotals:
      """Represents activity totals (distance, time, etc.)."""
  
      distance: float = 0.0
      achievement_count: int = 0
      elevation_gain: float = 0.0