Statcast MCP Server

Instructions

Implementation Reference

• src/statcast_mcp/server.py:652-745 (handler)

  The implementation of the team_season_pitching_stats tool, which fetches and formats team pitching statistics from FanGraphs or Baseball Reference.

  @mcp.tool()
  def team_season_pitching_stats(
      team: str,
      season: int,
      min_innings: int = 1,
      player_name: str | None = None,
  ) -> str:
      """Full-season **actual** pitching stats for one MLB team (rotation + bullpen).
  
      Uses **FanGraphs** when available; otherwise scrapes **Baseball Reference**'s team
      pitching table (W, L, ERA, G, GS, SV, IP, SO, WAR, etc.).
  
      Args:
          team: 3-letter abbreviation (e.g. ``PHI``, ``NYY``).
          season: Season year (e.g. 2025).
          min_innings: Minimum IP for the FanGraphs pull (default 1). Ignored for BRef
              fallback (full staff).
          player_name: Optional. One pitcher (e.g. ``Zack Wheeler``).
  
      Split **rotation vs bullpen** by sorting on ``GS`` in the table (starters vs relievers).
      For league-wide pitching only, use ``season_pitching_stats``.
      """
      from pybaseball import pitching_stats
  
      abbr = _normalize_team_abbr(team)
      data: pd.DataFrame | None = None
      fg_note = ""
      try:
          data = pitching_stats(season, season, team=abbr, qual=min_innings)
          if data is None or getattr(data, "empty", True):
              fg_note = "FanGraphs returned no rows."
              data = None
      except Exception as e:
          fg_note = str(e)
          data = None
  
      source = "FanGraphs"
      if data is None or data.empty:
          try:
              data = _team_pitching_from_bref(abbr, season)
              source = "Baseball Reference"
              if fg_note:
                  source += f" — {fg_note}"
          except Exception as e2:
              return (
                  f"Could not load team pitching stats for {abbr} {season}. "
                  f"FanGraphs: {fg_note}. Baseball Reference: {e2}"
              )
  
      if player_name:
          try:
              data = _filter_player_rows(data, player_name)
          except ValueError as e:
              return str(e)
          if data.empty:
              return (
                  f"No pitching row for {player_name!r} on team {abbr} in {season}."
              )
  
      header = f"**Source:** {source}\n**Team:** {abbr} | **Season:** {season}\n\n"
      return header + _fmt(data, max_rows=200)
  
  
  # ---------------------------------------------------------------------------
  # Tools — Statcast Leaderboards (Expected Stats & Exit Velocity)
  # ---------------------------------------------------------------------------
  
  
  @mcp.tool()
  def statcast_batter_expected_stats(
      year: int,
      min_plate_appearances: int = 50,
      player_name: str | None = None,
  ) -> str:
      """Get expected batting stats (xBA, xSLG, xwOBA vs actual) from Statcast.
  
      Returns xBA, xSLG, xwOBA and the gap from actual stats — what a batter
      *deserves* based on quality of contact.
  
      Args:
          year: Season year (e.g. 2024).
          min_plate_appearances: Minimum PA to qualify (default 50).
          player_name: Optional. If set (e.g. 'Aaron Judge'), returns only that
              player's row — use this so a star is not cut off by the 50-row
              leaderboard limit.
  
      Great for identifying lucky/unlucky hitters or a single player's expected line.
      """
      from pybaseball import statcast_batter_expected_stats as _fn
  
      try:
          data = _fn(year, minPA=min_plate_appearances)
      except Exception as e:
          return f"Error fetching expected batting stats: {e}"