Statcast MCP Server

Instructions

Implementation Reference

• src/statcast_mcp/server.py:495-536 (handler)

  The handler function that executes the `season_batting_stats` tool logic, fetching and formatting batting statistics.

  def season_batting_stats(
      start_season: int,
      end_season: int | None = None,
      min_plate_appearances: int | None = None,
      player_name: str | None = None,
  ) -> str:
      """Get season-level batting statistics from FanGraphs.
  
      Returns comprehensive stats: AVG, OBP, SLG, wOBA, wRC+, HR, SB, WAR,
      and many more for every qualifying batter.
  
      Args:
          start_season: First season to include (e.g. 2024).
          end_season: Last season to include. Omit for a single year.
          min_plate_appearances: Minimum plate appearances to qualify.
              Leave blank to use the FanGraphs default qualified threshold.
          player_name: Optional. Filter to one player (e.g. 'Aaron Judge').
  
      Great for finding league leaders, comparing players, or reviewing a full season.
      """
      from pybaseball import batting_stats
  
      if end_season is None:
          end_season = start_season
  
      try:
          data = batting_stats(start_season, end_season, qual=min_plate_appearances)
      except Exception as e:
          return f"Error fetching batting stats: {e}"
  
      if player_name:
          try:
              data = _filter_player_rows(data, player_name)
          except ValueError as e:
              return str(e)
          if data.empty:
              return (
                  f"No FanGraphs batting row for {player_name} in {start_season}-{end_season} "
                  "with the given PA threshold."
              )
  
      return _fmt(data, max_rows=50)

• src/statcast_mcp/server.py:494-494 (registration)

  The decorator used to register the `season_batting_stats` function as an MCP tool.

  @mcp.tool()