mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:847-896 (handler)

  Core handler function for 'get_statcast_batter' tool. Fetches Statcast batter data using pybaseball library, with date validation, size checking, and error handling. The @mcp.tool() decorator registers it as an MCP tool.
  @mcp.tool() def get_statcast_batter( player_id: int, start_date: str, end_date: str, ) -> dict: """ Retrieve MLB Statcast data for a single batter over a date range. Parameters ---------- player_id : int MLBAM ID of the batter. start_date : str The start date in 'YYYY-MM-DD' format. Required. end_date : str The end date in 'YYYY-MM-DD' format. Required. Returns ------- dict Dictionary with Statcast data for the batter. If the result is too large, returns an error message. Notes ----- Data is sourced from MLB Statcast via pybaseball. 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 data = statcast_batter(start_date, end_date, player_id) # Convert all columns to string to ensure JSON serializability data = data.astype(str) result = {"statcast_data": data.to_dict(orient="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, "player") if size_error: return size_error return result except Exception as e: return {"error": str(e)}
• main.py:12-23 (registration)

  Imports and invokes setup_mlb_tools(mcp), which defines and registers the get_statcast_batter tool (and others) with the MCP server instance.
  from mlb_api import setup_mlb_tools # Suppress websockets deprecation warnings warnings.filterwarnings("ignore", category=DeprecationWarning, module="websockets") warnings.filterwarnings("ignore", category=DeprecationWarning, module="uvicorn.protocols.websockets") # Create FastMCP server instance mcp = FastMCP("MLB API MCP Server") # Setup all MLB and generic tools setup_mlb_tools(mcp) setup_generic_tools(mcp)
• mlb_api.py:206-218 (helper)

  Helper function used by get_statcast_batter to validate the input date range.
  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
• mlb_api.py:189-203 (helper)

  Helper function used by get_statcast_batter to check if the result size exceeds limits.
  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