Formula One MCP Server

Instructions

Implementation Reference

• src/f1_mcp_server/f1_data.py:186-249 (handler)

  Core handler function that implements the get_session_results tool logic using FastF1 API to load session data, extract results, serialize to JSON-compatible format, and handle validation/errors.
  def get_session_results( year: Any, event_identifier: str, session_name: str ) -> dict[str, Any]: """ Get results for a specific Formula One session. Args: year (int or str): The year of the F1 season event_identifier (str): Event name or round number session_name (str): Session type (Race, Qualifying, Sprint, etc.) Returns: dict: Status and session results data or error information """ try: # Validate year year_int = validate_year(year) # Validate session name valid_sessions = [ "Race", "Qualifying", "Sprint", "FP1", "FP2", "FP3", "SprintQualifying", ] if session_name not in valid_sessions: raise ValueError( f"Invalid session name. Must be one of: {', '.join(valid_sessions)}" ) logger.debug( f"Fetching session results for {year_int}, " f"event: {event_identifier}, session: {session_name}" ) session = fastf1.get_session(year_int, event_identifier, session_name) # Load session without telemetry for faster results session.load(telemetry=False) # Get results as a DataFrame results = session.results # Convert results to JSON serializable format result_list = [] for _, result in results.items(): driver_result = result.to_dict() # Clean and convert non-serializable values clean_dict = {k: json_serial(v) for k, v in driver_result.items()} result_list.append(clean_dict) logger.info( f"Successfully retrieved results for {year_int}, " f"event: {event_identifier}, session: {session_name}" ) return {"status": "success", "data": result_list} except Exception as e: logger.error(f"Error retrieving session results: {str(e)}", exc_info=True) return { "status": "error", "message": f"Failed to retrieve session results: {str(e)}", }
• src/f1_mcp_server/server.py:320-346 (schema)

  MCP tool schema definition including input validation schema for get_session_results parameters (year, event_identifier, session_name).
  types.Tool( name="get_session_results", description="Get results for a specific Formula One session", inputSchema={ "type": "object", "properties": { "year": { "type": "number", "description": "Season year (e.g., 2023)", }, "event_identifier": { "type": "string", "description": ( "Event name or round number (e.g., 'Monaco' or '7')" ), }, "session_name": { "type": "string", "description": ( "Session name (e.g., 'Race', 'Qualifying', " "'Sprint', 'FP1', 'FP2', 'FP3')" ), }, }, "required": ["year", "event_identifier", "session_name"], }, ),
• src/f1_mcp_server/server.py:24-33 (registration)

  Import of the get_session_results handler function into the MCP server module for registration and use in tool dispatching.
  from .f1_data import ( analyze_driver_performance, compare_drivers, get_championship_standings, get_driver_info, get_event_info, get_event_schedule, get_session_results, get_telemetry, )
• src/f1_mcp_server/server.py:170-200 (registration)

  Tool dispatching logic in the MCP call_tool handler that validates inputs and invokes the get_session_results function.
  elif name == "get_session_results": # Additional validations for session-related tools if "event_identifier" not in arguments: raise ValueError("Missing required argument: event_identifier") if "session_name" not in arguments: raise ValueError("Missing required argument: session_name") event_identifier = str(arguments["event_identifier"]) session_name = str(arguments["session_name"]) # Validate session_name format valid_sessions = [ "Race", "Qualifying", "Sprint", "FP1", "FP2", "FP3", "SprintQualifying", ] if session_name not in valid_sessions: raise ValueError( "Invalid session_name: must be one of " f"{', '.join(valid_sessions)}" ) result = get_session_results( sanitized_args["year"], event_identifier, session_name, )