mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:535-578 (handler)

  The primary handler function for the 'get_mlb_roster' tool. It is decorated with @mcp.tool() which also serves as its registration in the MCP server. Resolves team name/ID using helper, fetches roster via mlbstatsapi.Mlb().get_team_roster(), and returns the data or error.
  @mcp.tool() def get_mlb_roster( team: str, date: Optional[str] = None, rosterType: Optional[str] = None, season: Optional[str] = None, hydrate: Optional[str] = None, fields: Optional[str] = None, ) -> dict: """ Get team roster for a specific team (ID or name), with optional filters. Args: team (str): Team ID or team name as a string. Can be numeric string, full name, abbreviation, or location. date (Optional[str]): Date in 'YYYY-MM-DD' format. If not provided, defaults to today. rosterType (Optional[str]): Filter by roster type (e.g., 40Man, fullSeason, etc.). season (Optional[str]): Filter by single season (year). hydrate (Optional[str]): Additional data to hydrate in the response. fields (Optional[str]): Comma-separated list of fields to include. Returns: dict: Team roster information. """ try: if date is None: date = datetime.now().strftime("%Y-%m-%d") params = {} if rosterType is not None: params["rosterType"] = rosterType if season is not None: params["season"] = season params["date"] = date if hydrate is not None: params["hydrate"] = hydrate if fields is not None: params["fields"] = fields team_id = get_team_id_from_name(team) if team_id is None: return {"error": f"Could not find team ID for '{team}'"} roster = mlb.get_team_roster(team_id, **params) return roster except Exception as e: return {"error": str(e)}
• mlb_api.py:152-174 (helper)

  Helper function used by get_mlb_roster to resolve team name (full, partial, abbrev) or ID string to numeric team ID by checking against current_mlb_teams.csv.
  def get_team_id_from_name(team: str) -> Optional[int]: """Helper to get team ID from team name, partial name, or stringified ID.""" # Accept stringified integer as ID try: return int(team) except (ValueError, TypeError): pass import csv team_lower = team.lower().strip() with open("current_mlb_teams.csv", "r") as f: reader = csv.DictReader(f) # First, try exact match for row in reader: if team_lower == row["team_name"].lower().strip(): return int(row["team_id"]) f.seek(0) next(reader) # skip header # Then, try substring match for row in reader: if team_lower in row["team_name"].lower(): return int(row["team_id"]) return None
• main.py:21-23 (registration)

  In the main.py server startup, setup_mlb_tools(mcp) is called, which defines and registers the get_mlb_roster tool (along with others) via @mcp.tool() decorators.
  # Setup all MLB and generic tools setup_mlb_tools(mcp) setup_generic_tools(mcp)