mlb-api-mcp

Instructions

Implementation Reference

• mlb_api.py:713-795 (handler)

  The handler function decorated with @mcp.tool(), implementing the logic to fetch game boxscore and extract detailed lineup information for away and home teams, including player IDs, names, positions, batting orders, and game statuses.
  @mcp.tool() def get_mlb_game_lineup(game_id: int) -> dict: """ Get lineup information for a specific game by game_id. Args: game_id (int): The game ID. Returns: dict: Game lineup information. """ try: # Get the boxscore data boxscore = mlb.get_game_box_score(game_id) result = {"game_id": game_id, "teams": {}} # Process both teams (away and home) for team_type in ["away", "home"]: if hasattr(boxscore, "teams") and hasattr(boxscore.teams, team_type): team_data = getattr(boxscore.teams, team_type) team_info = { "team_name": getattr(team_data.team, "name", "Unknown"), "team_id": getattr(team_data.team, "id", None), "players": [], } # Get players from the team data if hasattr(team_data, "players") and team_data.players is not None: players_dict = team_data.players # Extract player information for player_key, player_data in players_dict.items(): if player_key.startswith("id"): player_info = { "player_id": getattr(player_data.person, "id", None), "player_name": getattr(player_data.person, "fullname", "Unknown"), "jersey_number": getattr(player_data, "jerseynumber", None), "positions": [], "batting_order": None, "game_entries": [], } # Get position information if hasattr(player_data, "allpositions") and player_data.allpositions is not None: for position in player_data.allpositions: position_info = { "position": getattr(position, "abbreviation", None), "position_name": getattr(position, "name", None), } player_info["positions"].append(position_info) # Get batting order from player data directly if hasattr(player_data, "battingorder"): player_info["batting_order"] = getattr(player_data, "battingorder", None) # Get game entry information (substitutions, etc.) if hasattr(player_data, "gamestatus"): game_status = player_data.gamestatus entry_info = { "is_on_bench": getattr(game_status, "isonbench", False), "is_substitute": getattr(game_status, "issubstitute", False), "status": getattr(game_status, "status", None), } player_info["game_entries"].append(entry_info) team_info["players"].append(player_info) # Sort players by batting order (starting lineup first, then substitutes) def sort_key(player): batting_order = player.get("batting_order") if batting_order is None: return 999 # Put non-batting order players at the end return int(str(batting_order).replace("0", "")) # Handle batting order formatting team_info["players"].sort(key=sort_key) result["teams"][team_type] = team_info return result except Exception as e: return {"error": str(e)}
• main.py:19-23 (registration)

  Registration of the MLB tools, including get_mlb_game_lineup, by calling setup_mlb_tools(mcp) after initializing the FastMCP server.
  mcp = FastMCP("MLB API MCP Server") # Setup all MLB and generic tools setup_mlb_tools(mcp) setup_generic_tools(mcp)
• mlb_api.py:221-221 (registration)

  The setup function that defines and registers all MLB tools, including the @mcp.tool() decorator for get_mlb_game_lineup.
  def setup_mlb_tools(mcp):