Get the F1 race calendar for a season.

Data source: Ergast API (via FastF1) Coverage: 1950-present

Args: year: Season year (1950-present)

Returns: List of events with: round, raceName, circuitName, country, date, time (if available)

Example: get_schedule(2024) → [ {"round": 1, "raceName": "Bahrain Grand Prix", ...}, ... ]

Get driver championship standings.

Data source: Ergast API (via FastF1) Coverage: 1950-present

Args: year: Season year after_round: Standings after specific round (default: latest)

Returns: Ordered list of drivers with: position, driver code, full name, team, points, wins

Example: get_driver_standings(2024) → [ {"position": 1, "code": "VER", "name": "Max Verstappen", "team": "Red Bull", "points": 575, "wins": 19}, ... ]

Get constructor championship standings.

Data source: Ergast API (via FastF1) Coverage: 1958-present (constructor championship started 1958)

Args: year: Season year after_round: Standings after specific round (default: latest)

Returns: Ordered list of constructors with: position, name, nationality, points, wins

Get driver information.

Data source: Ergast API (via FastF1) Coverage: 1950-present

Args: driver_id: Ergast driver ID (e.g., "max_verstappen", "hamilton") If None, returns all drivers year: Filter to drivers who raced in this season

Returns: Driver info: driverId, code, givenName, familyName, dateOfBirth, nationality, permanentNumber

Note: Use get_session_results to find driver codes, then use this for biographical details.

Get historical race results (pre-2018 or when session data unavailable).

Data source: Ergast API (via FastF1) Coverage: 1950-present

Args: year: Season year round_num: Round number

Returns: Results with: position, driver, constructor, grid, laps, status, time (if finished), fastestLapTime, fastestLapRank

Note: For 2018+ races, prefer get_session_results which has more detail.

Get circuit information.

Data source: Ergast API (via FastF1)

Args: circuit_id: Ergast circuit ID (e.g., "monaco", "silverstone") If None, returns all circuits year: Filter to circuits used in this season

Returns: Circuit info: circuitId, circuitName, locality, country, lat, long

Get session classification/results.

Data source: FastF1 Live Timing Coverage: 2018-present

Args: year: Season year (2018+) event: Race name (e.g., "Monaco") or round number session: Session type — R, Q, S, SQ, FP1, FP2, FP3

Returns: Ordered classification with: position, driverCode, fullName, teamName, gridPosition, time/status, points

Example: get_session_results(2024, "Monaco", "R") → [ {"position": 1, "driverCode": "LEC", "fullName": "Charles Leclerc", "teamName": "Ferrari", "time": "1:45:12.345", ...}, ... ]

Note: Requires year >= 2018. For historical results use get_race_results_historical.

Get all lap times for a driver in a session.

Data source: FastF1 Live Timing Coverage: 2018-present

Set export_path=True when the user mentions data analysis, notebooks, pandas, ML, "save as CSV", "export the data", or any downstream processing — the full per-lap array is then written to a CSV file the user can open directly. Large responses (>50 laps) also auto-export so the user always gets a real file path in the project rather than the MCP client silently spilling the response to a temp file.

Args: year: Season year (2018+) event: Race name or round number session: Session type (R, Q, S, FP1, FP2, FP3) driver: Driver code (e.g., "VER") or number (e.g., "1") include_deleted: Include deleted lap times (default False) export_path: If True, write the full per-lap array to a CSV in the configured export directory (default ./fastf1-exports/, override via FASTF1_MCP_EXPORT_DIR) and omit laps from the response. Pass a string for a custom directory or .csv file path. The server also auto-exports when the lap count exceeds FASTF1_MCP_AUTO_EXPORT_ROWS (default 50).

Returns: Default (no export): { "driver": "VER", "fullName": "Max Verstappen", "teamName": "Red Bull Racing", "summary": {...}, "laps": [{"lapNumber": 1, "lapTime": "0:01:30.456", ...}, ...] }

With export_path:
{
    "driver": "VER", "fullName": ..., "teamName": ...,
    "summary": {...},
    "exportPath": "/abs/path/to/get_lap_times_2024_monaco_r_ver_<ts>.csv",
    "rowCount": 52
}

Note: Deleted laps (e.g., track limits violations) are excluded by default. Set include_deleted=True to include them. summary lets a caller answer fastest/avg/compound questions without re-parsing the full per-lap array. Use export_path=True to grab the full dataset as CSV for downstream analysis / ML work.

Get fastest laps in a session, one per driver.

Data source: FastF1 Live Timing Coverage: 2018-present

Args: year: Season year (2018+) event: Race name or round number session: Session type (default "R") top_n: Number of fastest laps to return (default 10)

Returns: Fastest laps sorted by time: lapNumber, lapTime, sector1, sector2, sector3, compound

Example: get_fastest_laps(2024, "Monaco", "R", 5) → [ {"lapNumber": 67, "lapTime": "0:01:15.456", "compound": "SOFT", ...}, ... ]

Note: Returns one fastest lap per driver. Only accurate laps are included.

Calculate average race pace for all drivers.

Data source: FastF1 Live Timing Coverage: 2018-present

Args: year: Season year (2018+) event: Race name or round number exclude_first_laps: Number of opening laps to exclude (default 2) exclude_sc_laps: Exclude laps behind safety car or VSC (default True) exclude_pit_laps: Exclude in-laps and out-laps (default True) min_laps: Minimum valid laps required to include a driver (default 10)

Returns: { "filters": { "excludeFirstLaps": 2, "excludeSafetyCarLaps": true, "excludePitLaps": true, "minLaps": 10 }, "drivers": [ {"driver": "LEC", "fullName": "Charles Leclerc", "teamName": "Ferrari", "avgLapTime": "0:01:15.678", "lapCount": 52, "deltaToFastestSec": 0.0, ...}, ... ] }

Note: SC/VSC filter uses track status "1" (green flag only). Drivers with fewer than min_laps valid laps are excluded. The filters block echoes the applied filters so the caller can clearly state which conditions the pace was computed under.

Analyze tire stints for a race.

Data source: FastF1 Live Timing Coverage: 2018-present

Set export_path=True when the user mentions data analysis, notebooks, pandas, ML, "save as CSV", "export the strategy data", or any downstream processing — the full per-stint array is written to CSV. Large responses (>50 stints, typical for full-grid races) also auto-export.

Args: year: Season year (2018+) event: Race name or round number driver: Optional driver code to filter (default: all drivers) export_path: If True, write the full per-stint array to a CSV in the configured export directory (default ./fastf1-exports/, override via FASTF1_MCP_EXPORT_DIR) and omit stints from the response. Pass a string for a custom directory or .csv file path. The server also auto-exports when the stint count exceeds FASTF1_MCP_AUTO_EXPORT_ROWS (default 50).

Returns: Default (no export): { "summary": {...}, "stints": [{"driver": "LEC", "stintNumber": 1, ...}, ...] }

With export_path:
{
    "summary": {...},
    "exportPath": "/abs/path/to/get_stint_analysis_<...>.csv",
    "rowCount": 45
}

Note: Only accurate laps are included in pace calculations. Stint numbers match FastF1's internal stint counter. Phantom lap-1 stints (single-lap entries with no recorded lap time, paired with the lap-1 pit-stop artifact) are filtered out. The summary.strategies array gives the 1-stop / 2-stop / compound sequence per driver in a compact form.

Get all pit stops from a race.

Data source: FastF1 Live Timing Coverage: 2018-present

Args: year: Season year (2018+) event: Race name or round number

Returns: Pit stops sorted by lap: driver (code), fullName, teamName, lap, stopNumber, duration, tyreFrom, tyreTo

Example: get_pit_stops(2024, "Monaco") → [ {"driver": "LEC", "fullName": "Charles Leclerc", "teamName": "Ferrari", "lap": 28, "stopNumber": 1, "duration": 23.4, "tyreFrom": "MEDIUM", "tyreTo": "HARD"}, ... ]

Note: Duration is calculated from PitInTime (end of in-lap) to PitOutTime (start of out-lap), in seconds. Stops with implausibly long durations (>120s) are filtered as FastF1 data artifacts — commonly a phantom lap-1 entry tied to session start, not a real pit stop.

Get qualifying results split by Q1/Q2/Q3.

Data source: FastF1 Live Timing Coverage: 2018-present

Args: year: Season year (2018+) event: Race name or round number

Returns: { "Q1": [{"driver": "VER", "bestTime": "1:10.123", "lapNumber": 3}, ...], "Q2": [...], "Q3": [...], "eliminated_Q1": ["driver1", "driver2", ...], "eliminated_Q2": ["driver3", "driver4", ...] }

Example: get_qualifying_breakdown(2024, "Monaco") → { "Q1": [...20 drivers sorted by best time...], "Q2": [...15 drivers...], "Q3": [...10 drivers...], "eliminated_Q1": ["5 driver codes"], "eliminated_Q2": ["5 driver codes"] }

Note: Uses laps.split_qualifying_sessions() to split by session time. Drivers with no recorded lap time in a segment are omitted from that segment's list.

List all events in a season.

Data source: Ergast API (via FastF1) Coverage: 1950-present

Args: year: Season year (1950-present)

Returns: Events with: round, eventName, country, circuitName, date

Example: list_events(2024) → [ {"round": 1, "eventName": "Bahrain Grand Prix", "country": "Bahrain", "circuitName": "Bahrain International Circuit", "date": "2024-03-02"}, ... ]

Note: Minimal version of get_schedule — useful for discovering valid event names to pass to other tools.

List all drivers in a season, optionally filtered to a specific event.

Data source: Ergast API (season list) or FastF1 session (event filter) Coverage: 1950-present (season); 2018-present (event filter)

Args: year: Season year event: Optional race name or round number to filter by event (returns only drivers who participated in that session)

Returns: Drivers with: code, fullName, nationality, team, number

Example: list_drivers(2024) → [ {"code": "VER", "fullName": "Max Verstappen", "nationality": "Dutch", "team": "Red Bull Racing", "number": "1"}, ... ]

Note: When event is provided, data comes from FastF1 session results (requires year >= 2018). Without event, uses Ergast season data.

Check server in-memory session cache status.

Returns: { "sessions_cached": 3, "max_sessions": 10, "cached_sessions": [ {"year": 2024, "event": "Monaco", "session": "R", "loaded_at": "2024-05-26T14:00:00"}, ... ], "fastf1_cache_path": "~/.fastf1_cache", "fastf1_cache_size_mb": 1234.5 }

Example: get_cache_status() → {"sessions_cached": 2, "max_sessions": 10, ...}

Note: Reports in-memory LRU cache only. The FastF1 disk cache (used for raw timing data) is reported separately as size_mb.

Clear cached sessions from in-memory storage.

Args: year: Optional year filter — only clear sessions for this year event: Optional event filter — requires year to be set

Returns: {"cleared": 3, "remaining": 2}

Example: clear_cache() → {"cleared": 5, "remaining": 0} clear_cache(2024, "Monaco") → {"cleared": 1, "remaining": 4}

Note: Clears the in-memory LRU cache only. The FastF1 disk cache (raw timing files) is preserved and unaffected.

Get telemetry data for a specific lap.

Data source: FastF1 Live Timing Coverage: 2018-present

Set export_path=True when the user mentions data analysis, notebooks, pandas, ML, "plot the telemetry", "save the trace", or downstream processing — the sampled per-distance trace is written to CSV. Telemetry responses with the default 200 sample points also auto-export so the user always gets a real file path in the project.

Args: year: Season year (2018+) event: Race name or round number session: Session type (R, Q, S, FP1, FP2, FP3) driver: Driver code (e.g., "VER") lap: Lap number or "fastest" (default) sample_size: Number of telemetry points to return (default 200, max 500) export_path: If True, write the sampled data array to a CSV in the configured export directory (default ./fastf1-exports/, override via FASTF1_MCP_EXPORT_DIR) and omit data from the response. Pass a string for a custom directory or .csv file path. The server also auto-exports when data would exceed FASTF1_MCP_AUTO_EXPORT_ROWS rows (default 50). Use a larger sample_size if you want more detail in the exported file.

Returns: { "driver": "VER", "lapNumber": 42, "lapTime": "0:01:23.456", "summary": { "samplePoints": 200, "maxSpeedKph": 327.5, "minSpeedKph": 80.2, "avgSpeedKph": 218.1, "maxGear": 8, "brakingZones": 7, "fullThrottlePct": 64.5 }, "data": [ {"distance": 0.0, "speed": 280.0, "throttle": 95.0, "brake": false, "gear": 7, "drs": 0}, ... ] }

Example: get_lap_telemetry(2024, "Monaco", "Q", "VER") → fastest Q lap telemetry get_lap_telemetry(2024, "Monaco", "R", "VER", lap=45) → lap 45 telemetry

Note: Raw telemetry has 5000+ points per lap. Response is sampled to sample_size evenly-spaced distance points (capped at 500). summary lets a caller answer top-speed / braking-zone questions without parsing the full per-distance array.

Compare telemetry between two drivers on the same session.

Data source: FastF1 Live Timing Coverage: 2018-present

Set export_path=True when the user wants the comparison data for analysis (notebook, pandas, ML, "plot where one driver gains time", "save the comparison"). Comparisons at the default 200 sample size also auto-export.

Args: year: Season year (2018+) event: Race name or round number session: Session type (R, Q, S, FP1, FP2, FP3) driver1: First driver code (e.g., "VER") driver2: Second driver code (e.g., "LEC") lap: Lap number or "fastest" — applied independently to each driver sample_size: Telemetry points per driver (default 200, max 500) export_path: If True, write the per-distance comparison array to a CSV in the configured export directory (default ./fastf1-exports/, override via FASTF1_MCP_EXPORT_DIR) and omit comparison from the response. Pass a string for a custom directory or .csv file path.

Returns: { "driver1": {"code": "VER", "lapNumber": 18, "lapTime": "1:10.123"}, "driver2": {"code": "LEC", "lapNumber": 20, "lapTime": "1:10.456"}, "comparison": [ {"distance": 0.0, "speed1": 280.0, "speed2": 275.0, "speedDelta": 5.0, "timeDelta": 0.0}, ... ], "summary": { "lapTimeDeltaSec": 0.333, "maxSpeedDelta": 8.2, "sectors": { "S1": {"driver1": "0:00:28.123", "driver2": "0:00:28.456", "deltaSec": -0.333}, "S2": {...}, "S3": {...} }, "driver1Telemetry": {"maxSpeedKph": 325.0, "brakingZones": 7, ...}, "driver2Telemetry": {"maxSpeedKph": 320.5, "brakingZones": 8, ...} } }

Example: compare_telemetry(2024, "Monaco", "Q", "VER", "LEC")

Note: timeDelta is the cumulative time gap at each distance point, computed from speed integration. Positive = driver1 is ahead. Comparison is aligned to driver1's distance axis.

Get speed trap and top-speed data for all drivers in a session.

Data source: FastF1 Live Timing (session results) Coverage: 2018-present

Args: year: Season year (2018+) event: Race name or round number session: Session type (R, Q, S, FP1, FP2, FP3)

Returns: { "source": "results" | "laps", "drivers": [ {"driver": "VER", "fullName": "Max Verstappen", "teamName": "Red Bull Racing", "speedTrap": 298.5, "speedFL": 187.2, "speedI1": 245.0, "speedI2": 268.5}, ... ] }

Example: get_speed_trap_data(2024, "Monza", "Q") → {"source": "results", ...}

Note: SpeedST = official speed trap measurement. SpeedFL = speed at the finish line. SpeedI1/I2 = sector intermediate speed measurements. Values are in km/h.

FastF1 publishes per-driver speed columns on `session.results`, but
for many sessions those columns are entirely empty. When the
results-level data is missing, we fall back to the per-lap max
across `session.laps` for the same columns. `source` indicates
which path produced the response.

Get best sector times and theoretical best lap for each driver.

Data source: FastF1 Live Timing Coverage: 2018-present

Set include_laps=True when the user wants per-lap sector breakdowns (e.g. "show me Antonelli's sector times each lap") rather than just the per-driver best/theoretical-best summary.

Args: year: Season year (2018+) event: Race name or round number session: Session type (R, Q, S, FP1, FP2, FP3) driver: Optional driver code to filter (default: all drivers) include_laps: If True, include a laps array per driver with each accurate lap's S1/S2/S3 and total lap time. Default False keeps responses compact for the typical "fastest sectors / theoretical best" question.

Returns: For each driver: driver (code), fullName, teamName, bestS1, bestS2, bestS3, theoreticalBest, actualBest, gapSec. With include_laps, each entry also has laps: [{lapNumber, s1, s2, s3, lapTime}, ...].

Example: get_sector_times(2024, "Monaco", "Q") → [ {"driver": "VER", "fullName": "Max Verstappen", "teamName": "Red Bull Racing", "bestS1": "0:00:22.123", "bestS2": "0:00:24.456", "bestS3": "0:00:21.789", "theoreticalBest": "0:01:08.368", "actualBest": "0:01:08.570", "gapSec": -0.202}, ... ]

Note: A negative gapSec means the theoretical best (sum of individual sector bests) is faster than the actual best lap — typical, since sector bests usually come from different laps.