get_mlb_roster
Retrieve MLB team rosters by team name or ID, with options to filter by date, season, roster type, and specific data fields.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | ||
| date | No | ||
| rosterType | No | ||
| season | No | ||
| hydrate | No | ||
| fields | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- mlb_api.py:535-578 (handler)The core handler function for the 'get_mlb_roster' tool, decorated with @mcp.tool() for automatic registration in the MCP server. It resolves the team ID using a helper, constructs parameters, calls mlb.get_team_roster(), and handles errors. The docstring and type hints define the input schema.
@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 utility function used by get_mlb_roster to resolve a team name (full, partial, or ID string) to a numeric team ID by checking a local CSV file.
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