Formula One MCP Server

Instructions

Implementation Reference

• python/f1_data.py:197-239 (handler)

  Core handler function implementing get_telemetry logic: loads F1 session, retrieves driver lap (specific or fastest), fetches telemetry data via fastf1 library, serializes to JSON-compatible format with lap info.

  def get_telemetry(year, event_identifier, session_name, driver_identifier, lap_number=None):
      """Get telemetry data for a specific lap or fastest lap"""
      try:
          year = int(year)
          session = fastf1.get_session(year, event_identifier, session_name)
          session.load()
          
          # Get laps for the specified driver
          driver_laps = session.laps.pick_driver(driver_identifier)
          
          # Get the specific lap or fastest lap
          if lap_number:
              lap = driver_laps[driver_laps['LapNumber'] == int(lap_number)].iloc[0]
          else:
              lap = driver_laps.pick_fastest()
          
          # Get telemetry data
          telemetry = lap.get_telemetry()
          
          # Convert to JSON serializable format
          telemetry_dict = telemetry.to_dict(orient='records')
          clean_data = []
          
          for item in telemetry_dict:
              clean_item = {k: json_serial(v) for k, v in item.items()}
              clean_data.append(clean_item)
          
          # Add lap information
          lap_info = {
              "LapNumber": int(lap['LapNumber']) if not pd.isna(lap['LapNumber']) else None,
              "LapTime": str(lap['LapTime']) if not pd.isna(lap['LapTime']) else None,
              "Compound": lap['Compound'] if not pd.isna(lap['Compound']) else None,
              "TyreLife": int(lap['TyreLife']) if not pd.isna(lap['TyreLife']) else None
          }
          
          result = {
              "lapInfo": lap_info,
              "telemetry": clean_data
          }
          
          return {"status": "success", "data": result}
      except Exception as e:
          return {"status": "error", "message": str(e), "traceback": traceback.format_exc()}

• src/index.ts:223-252 (schema)

  MCP tool schema definition for get_telemetry, including input parameters and descriptions for validation.

  {
    name: 'get_telemetry',
    description: 'Get telemetry data for a specific Formula One lap',
    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")',
        },
        driver_identifier: {
          type: 'string',
          description: 'Driver identifier (number, code, or name; e.g., "44", "HAM", "Hamilton")',
        },
        lap_number: {
          type: 'number',
          description: 'Lap number (optional, gets fastest lap if not provided)',
        },
      },
      required: ['year', 'event_identifier', 'session_name', 'driver_identifier'],
    },
  },

• src/index.ts:350-365 (handler)

  MCP TypeScript handler for get_telemetry tool: parses arguments, constructs parameter list, calls Python backend via executePythonFunction.

  case 'get_telemetry': {
    const typedArgs = args as TelemetryArgs;
    const telemetryArgs = [
      typedArgs.year.toString(),
      typedArgs.event_identifier.toString(),
      typedArgs.session_name.toString(),
      typedArgs.driver_identifier.toString(),
    ];
    
    if (typedArgs.lap_number !== undefined) {
      telemetryArgs.push(typedArgs.lap_number.toString());
    }
    
    result = await executePythonFunction('get_telemetry', telemetryArgs);
    break;
  }

• python/f1_data.py:290-299 (registration)

  Python dispatch dictionary registering get_telemetry function for invocation from command-line arguments in main().

  functions = {
      "get_event_schedule": get_event_schedule,
      "get_event_info": get_event_info,
      "get_session_results": get_session_results,
      "get_driver_info": get_driver_info,
      "analyze_driver_performance": analyze_driver_performance,
      "compare_drivers": compare_drivers,
      "get_telemetry": get_telemetry,
      "get_championship_standings": get_championship_standings
  }