get_championship_standings

Retrieve Formula One championship standings for a specific season, optionally filtered by round number to track team and driver positions throughout the race calendar.

Instructions

Get Formula One championship standings

Input Schema

TableJSON Schema

Name	Required	Description	Default
`year`	Yes	Season year (e.g., 2023)
`round_num`	No	Round number (optional, gets latest standings if not provided)

Implementation Reference

src/f1_mcp_server/f1_data.py:522-580 (handler)

Core handler function that retrieves Formula 1 championship standings for drivers and constructors using FastF1's Ergast API integration. Supports optional round specification and serializes data to JSON.

def get_championship_standings(year, round_num=None):
    """
    Get championship standings for drivers and constructors.

    Args:
        year (int or str): The year of the F1 season
        round_num (int, optional): Specific round number or None for latest

    Returns:
        dict: Status and championship standings or error information
    """
    try:
        year = int(year)

        # Create Ergast API client
        ergast = fastf1.ergast.Ergast()

        # Get Ergast API data
        if round_num:
            round_num = int(round_num)  # Ensure proper type conversion
            drivers_standings = ergast.get_driver_standings(
                season=year, round=round_num
            ).content[0]
            constructor_standings = ergast.get_constructor_standings(
                season=year, round=round_num
            ).content[0]
        else:
            drivers_standings = ergast.get_driver_standings(season=year).content[0]
            constructor_standings = ergast.get_constructor_standings(
                season=year
            ).content[0]

        # Convert driver standings to JSON serializable format
        drivers_list = []
        for _, row in drivers_standings.iterrows():
            driver_dict = row.to_dict()
            clean_dict = {k: json_serial(v) for k, v in driver_dict.items()}
            drivers_list.append(clean_dict)

        # Convert constructor standings to JSON serializable format
        constructors_list = []
        for _, row in constructor_standings.iterrows():
            constructor_dict = row.to_dict()
            clean_dict = {k: json_serial(v) for k, v in constructor_dict.items()}
            constructors_list.append(clean_dict)

        return {
            "status": "success",
            "data": {
                "drivers": drivers_list,
                "constructors": constructors_list,
            },
        }
    except Exception as e:
        logger.error(f"Error analyzing driver performance: {str(e)}", exc_info=True)
        return {
            "status": "error",
            "message": f"Failed to analyze driver performance: {str(e)}",
        }

src/f1_mcp_server/server.py:512-532 (registration)

Registers the 'get_championship_standings' tool with the MCP server, providing its description and input schema defining 'year' (required) and optional 'round_num'.

types.Tool(
    name="get_championship_standings",
    description="Get Formula One championship standings",
    inputSchema={
        "type": "object",
        "properties": {
            "year": {
                "type": "number",
                "description": "Season year (e.g., 2023)",
            },
            "round_num": {
                "type": "number",
                "description": (
                    "Round number (optional, gets latest "
                    "standings if not provided)"
                ),
            },
        },
        "required": ["year"],
    },
),

src/f1_mcp_server/server.py:515-530 (schema)

Input schema for the tool, specifying object with required 'year' number and optional 'round_num' number.

inputSchema={
    "type": "object",
    "properties": {
        "year": {
            "type": "number",
            "description": "Season year (e.g., 2023)",
        },
        "round_num": {
            "type": "number",
            "description": (
                "Round number (optional, gets latest "
                "standings if not provided)"
            ),
        },
    },
    "required": ["year"],

src/f1_mcp_server/server.py:241-252 (handler)

Server-side dispatch handler that validates inputs and calls the get_championship_standings function from f1_data.

elif name == "get_championship_standings":
    round_num = arguments.get("round_num")
    if round_num is not None:
        try:
            round_num = int(round_num)
            if round_num <= 0:
                raise ValueError("Round number must be positive")
        except (ValueError, TypeError) as e:
            raise ValueError(f"Invalid round number: {round_num}") from e

    result = get_championship_standings(sanitized_args["year"], round_num)
else:

Formula One MCP Server (Python)