mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:427-449 (handler)

  The main handler function for the 'get_mlb_sabermetrics' tool, decorated with @mcp.tool(). It parses the comma-separated player_ids, calls the helper function get_sabermetrics_for_players, and handles errors.

  @mcp.tool()
  def get_mlb_sabermetrics(
      player_ids: str, season: int, stat_name: Optional[str] = None, group: str = "hitting"
  ) -> dict:
      """
      Get sabermetric statistics (including WAR) for multiple players for a specific season.
  
      Args:
          player_ids (str): Comma-separated list of player IDs.
          season (int): Season year.
          stat_name (Optional[str]): Specific sabermetric stat to extract (e.g., 'war', 'woba', 'wRc').
          group (str): Stat group ('hitting' or 'pitching').
  
      Returns:
          dict: Sabermetric statistics.
      """
      try:
          player_ids_list = [pid.strip() for pid in player_ids.split(",")]
          result = get_sabermetrics_for_players(mlb, player_ids_list, season, stat_name, group)
          return result
      except Exception as e:
          return {"error": str(e)}

• mlb_api.py:79-150 (helper)

  Supporting helper function that performs the actual API call to fetch sabermetrics data from MLB stats API, filters for the specified players, extracts relevant stats including WAR, wOBA, etc., and formats the output.

  def get_sabermetrics_for_players(
      mlb, player_ids: list, season: int, stat_name: Optional[str] = None, group: str = "hitting"
  ) -> dict:
      """
      Get sabermetric statistics (like WAR) for multiple players for a specific season.
  
      Parameters
      ----------
      mlb : mlbstatsapi.Mlb
          The MLB stats API instance
      player_ids : list
          List of player IDs to get sabermetrics for
      season : int
          The season year to get stats for
      stat_name : str, optional
          Specific sabermetric stat to extract (e.g., 'war', 'woba', 'wRc'). If None, returns all sabermetrics.
      group : str, optional
          The stat group ('hitting' or 'pitching'). Default is 'hitting'.
  
      Returns
      -------
      dict
          Dictionary containing player sabermetrics data
      """
  
      # Build the API endpoint URL
      endpoint = f"stats?stats=sabermetrics&group={group}&sportId=1&season={season}"
  
      # Make the API call directly
      response = mlb._mlb_adapter_v1.get(endpoint=endpoint)
  
      if 400 <= response.status_code <= 499:
          return {"error": f"API error: {response.status_code}"}
  
      if not response.data or "stats" not in response.data:
          return {"error": "No stats data found"}
  
      # Extract the relevant data
      result = {"season": season, "group": group, "players": []}
  
      # Filter for our specific players
      player_ids_int = [int(pid) for pid in player_ids]
  
      for stat_group in response.data["stats"]:
          if "splits" in stat_group:
              for split in stat_group["splits"]:
                  if "player" in split and split["player"]["id"] in player_ids_int:
                      player_data = {
                          "player_id": split["player"]["id"],
                          "player_name": split["player"].get("fullName", "Unknown"),
                          "position": split.get("position", {}).get("abbreviation", "N/A"),
                          "team": split.get("team", {}).get("name", "N/A"),
                          "team_id": split.get("team", {}).get("id", None),
                      }
  
                      # Extract the sabermetric stats
                      if "stat" in split:
                          if stat_name:
                              # Return only the specific stat requested
                              if stat_name.lower() in split["stat"]:
                                  player_data[stat_name] = split["stat"][stat_name.lower()]
                              else:
                                  player_data[stat_name] = None
                                  player_data["available_stats"] = list(split["stat"].keys())
                          else:
                              # Return all sabermetric stats
                              player_data["sabermetrics"] = split["stat"]
  
                      result["players"].append(player_data)
  
      return result

• main.py:19-23 (registration)

  In the main server file, after creating the FastMCP instance, setup_mlb_tools(mcp) is called, which defines and registers the get_mlb_sabermetrics tool (along with others) using @mcp.tool() decorators.

  mcp = FastMCP("MLB API MCP Server")
  
  # Setup all MLB and generic tools
  setup_mlb_tools(mcp)
  setup_generic_tools(mcp)