team_season_batting_stats
Retrieve comprehensive batting statistics for an entire MLB team's roster during a specific season, including individual player data like plate appearances, home runs, averages, and WAR.
Instructions
Full-season actual batting stats for one MLB team (entire roster).
Uses FanGraphs when available; if that fails or returns no rows, falls back to scraping Baseball Reference's team page (same numbers as the site: PA, HR, AVG/OBP/SLG, OPS+, WAR, etc.).
Args:
team: 3-letter team abbreviation — same as Baseball Reference
(e.g. PHI, NYY, LAD, ARI).
season: Calendar year of the season (e.g. 2025).
min_plate_appearances: Minimum PA to include on the FanGraphs pull (default 1).
Ignored for the BRef fallback, which lists everyone who appeared.
player_name: Optional. Restrict to one player (e.g. Bryce Harper).
Use this for “Phillies lineup stats”, “Yankees 2024 hitters”, etc. For league
leaderboards without a team filter, use season_batting_stats instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | ||
| season | Yes | ||
| min_plate_appearances | No | ||
| player_name | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/statcast_mcp/server.py:584-650 (handler)The MCP tool handler function `team_season_batting_stats` is defined and registered using the `@mcp.tool()` decorator. It fetches batting stats using pybaseball or fallback scraping and returns a formatted string.
@mcp.tool() def team_season_batting_stats( team: str, season: int, min_plate_appearances: int = 1, player_name: str | None = None, ) -> str: """Full-season **actual** batting stats for one MLB team (entire roster). Uses **FanGraphs** when available; if that fails or returns no rows, falls back to scraping **Baseball Reference**'s team page (same numbers as the site: PA, HR, AVG/OBP/SLG, OPS+, WAR, etc.). Args: team: 3-letter team abbreviation — same as Baseball Reference (e.g. ``PHI``, ``NYY``, ``LAD``, ``ARI``). season: Calendar year of the season (e.g. 2025). min_plate_appearances: Minimum PA to include on the FanGraphs pull (default 1). Ignored for the BRef fallback, which lists everyone who appeared. player_name: Optional. Restrict to one player (e.g. ``Bryce Harper``). Use this for “Phillies lineup stats”, “Yankees 2024 hitters”, etc. For **league** leaderboards without a team filter, use ``season_batting_stats`` instead. """ from pybaseball import batting_stats abbr = _normalize_team_abbr(team) data: pd.DataFrame | None = None fg_note = "" try: data = batting_stats( season, season, team=abbr, qual=min_plate_appearances ) 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_batting_from_bref(abbr, season) source = "Baseball Reference" if fg_note: source += f" — {fg_note}" except Exception as e2: return ( f"Could not load team batting 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 batting row for {player_name!r} on team {abbr} in {season} " "(check spelling and team)." ) header = f"**Source:** {source}\n**Team:** {abbr} | **Season:** {season}\n\n" return header + _fmt(data, max_rows=200)