mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:898-980 (handler)

  The primary handler for the 'get_statcast_team' MCP tool. It uses @mcp.tool() decorator for automatic registration and schema definition via type hints. Fetches Statcast data for a team using pybaseball, filters by fields, handles validation and size limits.
  @mcp.tool() def get_statcast_team( team: str, start_date: str, end_date: str, fields: List[str], ) -> dict: """ Retrieve MLB Statcast data for all players on a team over a date range. Parameters ---------- team : str Team ID or team name (see MLB team list for valid values). start_date : str The start date in 'YYYY-MM-DD' format. Required. end_date : str The end date in 'YYYY-MM-DD' format. Required. fields: List[str] The field to return. If not provided, defaults to all fields. Available fields: pitch_type, game_date, release_speed, release_pos_x, release_pos_z, player_name, batter, pitcher, events, description, spin_dir, spin_rate_deprecated, break_angle_deprecated, break_length_deprecated, zone, des, game_type, stand, p_throws, home_team, away_team, type, hit_location, bb_type, balls, strikes, game_year, pfx_x, pfx_z, plate_x, plate_z, on_3b, on_2b, on_1b, outs_when_up, inning, inning_topbot, hc_x, hc_y, tfs_deprecated, tfs_zulu_deprecated, umpire, sv_id, vx0, vy0, vz0, ax, ay, az, sz_top, sz_bot, hit_distance_sc, launch_speed, launch_angle, effective_speed, release_spin_rate, release_extension, game_pk, fielder_2, fielder_3, fielder_4, fielder_5, fielder_6, fielder_7, fielder_8, fielder_9, release_pos_y, estimated_ba_using_speedangle, estimated_woba_using_speedangle, woba_value, woba_denom, babip_value, iso_value, launch_speed_angle, at_bat_number, pitch_number, pitch_name, home_score, away_score, bat_score, fld_score, post_away_score, post_home_score, post_bat_score, post_fld_score, if_fielding_alignment, of_fielding_alignment, spin_axis, delta_home_win_exp, delta_run_exp, bat_speed, swing_length, estimated_slg_using_speedangle, delta_pitcher_run_exp, hyper_speed, home_score_diff, bat_score_diff, home_win_exp, bat_win_exp, age_pit_legacy, age_bat_legacy, age_pit, age_bat, n_thruorder_pitcher, n_priorpa_thisgame_player_at_bat, pitcher_days_since_prev_game, batter_days_since_prev_game, pitcher_days_until_next_game, batter_days_until_next_game, api_break_z_with_gravity, api_break_x_arm, api_break_x_batter_in, arm_angle, attack_angle, attack_direction, swing_path_tilt, intercept_ball_minus_batter_pos_x_inches, intercept_ball_minus_batter_pos_y_inches Returns ------- dict Dictionary with Statcast data for all players on the team. If the result is too large, returns an error message. Notes ----- This uses the pybaseball `statcast` function, which returns all Statcast events for the specified team and date range. See the official documentation for more details: https://github.com/jldbc/pybaseball/tree/master/docs """ try: # Validate date range date_error = validate_date_range(start_date, end_date) if date_error: return date_error abbreviation = get_team_abbreviation_from_name(team) if not abbreviation: return {"error": f"Could not find 3-letter abbreviation for team '{team}'"} data = statcast(start_date, end_date, team=abbreviation) # Convert all columns to string to ensure JSON serializability data = data.astype(str) records = data.to_dict(orient="records") # Always include batter and pitcher, plus all requested fields filtered_records = [] for row in records: filtered_row = {} for key in ["batter", "pitcher", *list(fields)]: if key in row: filtered_row[key] = row[key] filtered_records.append(filtered_row) result = {"statcast_data": filtered_records} if not result["statcast_data"]: return { "error": ( f"No Statcast data found for the given date range ({start_date} to {end_date}). The date " "range may have resulted in nothing being returned." ) } size_error = check_result_size(result, "team") if size_error: return size_error return result except Exception as e: return {"error": str(e)}
• mlb_api.py:177-187 (helper)

  Helper utility to resolve team name to MLB 3-letter abbreviation, used in get_statcast_team for querying Statcast data.
  def get_team_abbreviation_from_name(team: str) -> Optional[str]: """ Given a team name, partial name, or ID, return the 3-letter team abbreviation (e.g., 'NYY' for Yankees). Returns None if not found. """ team_id = get_team_id_from_name(team) if team_id is None: return None team_info = mlb.get_team(team_id) return getattr(team_info, "abbreviation", None)
• mlb_api.py:189-203 (helper)

  Helper to check if result size exceeds limit (100k words), returns error if too large; used for get_statcast_team.
  def check_result_size(result: dict, context: str) -> Optional[dict]: """ Utility to check the size of a result dictionary (by word count). Returns an error dict if too large, else None. """ import json word_count = len(json.dumps(result).split()) if word_count > 100000: return { "error": ( f"Result too large ({word_count} words). Please narrow your query " f"(e.g., shorter date range, specific {context})." ) } return None
• mlb_api.py:206-218 (helper)

  Helper to validate date range (format and start <= end), returns error dict if invalid; used in get_statcast_team.
  def validate_date_range(start_date: str, end_date: str) -> Optional[dict]: """ Utility to check that start_date is before or equal to end_date. Returns an error dict if invalid, else None. """ try: start = datetime.strptime(start_date, "%Y-%m-%d") end = datetime.strptime(end_date, "%Y-%m-%d") if start > end: return {"error": f"start_date ({start_date}) must be before or equal to end_date ({end_date})"} except Exception as e: return {"error": f"Invalid date format: {e}"} return None