fastf1-mcp

An MCP server that exposes Formula 1 data to AI assistants via the FastF1 library. Ask Claude (or any MCP-compatible client) questions about race results, lap times, telemetry, standings, and more.

Features

• 21 tools covering standings, race results, lap times, telemetry, pit stops, and qualifying

• 4 MCP resources for schedule, driver, constructor, and circuit reference data

• 5 guided prompts for race recaps, qualifying analysis, strategy deep-dives, and weekend previews

• Async-safe LRU session cache — repeat queries are instant after the first load

• Distance-based telemetry sampling — large raw datasets compressed to ≤ 500 points

• All errors returned as structured dicts — the server never crashes on bad input

Requirements

• Python 3.12+

• uv (recommended) or pip

Installation

With uv (recommended)

git clone https://github.com/Surya96t/fastf1-mcp
cd fastf1-mcp
uv sync

With pip

pip install fastf1-mcp-server

Running the server

# via uv (development)
uv run fastf1-mcp-server

# or directly
python -m fastf1_mcp

MCP Inspector (development / debugging)

# Option A — official npx inspector
npx @modelcontextprotocol/inspector uv --directory . run fastf1-mcp-server

# Option B — fastmcp wrapper
uv run fastmcp dev inspector -m fastf1_mcp.server --with-editable .

Both open the inspector at http://localhost:6274.

Claude Desktop configuration

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "fastf1": {
      "command": "uv",
      "args": ["run", "fastf1-mcp-server"],
      "cwd": "/absolute/path/to/fastf1-mcp",
      "env": {
        "FASTF1_MCP_LOG_LEVEL": "INFO",
        "FASTF1_MCP_MAX_CACHED_SESSIONS": "10"
      }
    }
  }
}

Restart Claude Desktop after saving. The server name fastf1 will appear in the tools panel.

Configuration

All settings are read from environment variables with the FASTF1_MCP_ prefix.

Exporting full datasets for analysis

get_lap_times, get_stint_analysis, get_lap_telemetry, and compare_telemetry route the bulk data array through CSV when the user needs the file rather than the inline JSON.

Two ways the export gets triggered:

1. Auto-export (default for large responses) — when the response's bulk array would exceed FASTF1_MCP_AUTO_EXPORT_ROWS rows (default 50), the server writes it to CSV in FASTF1_MCP_EXPORT_DIR and the response carries exportPath + a note instead of the array. This catches full-race lap-time queries, full-grid stint analyses, and 200-point telemetry traces — exactly the cases where MCP clients would otherwise silently spill the response to an opaque temp file.

2. Explicit export_path parameter — pass it on the tool call:

   • export_path=True → write to <FASTF1_MCP_EXPORT_DIR>/<auto-named>.csv

   • export_path="data/laps" → write the auto-named file into the given directory

   • export_path="data/ver-monaco.csv" → write to exactly that file

The summary field is always included so a chat-only user can still answer "what was the fastest lap / what's the strategy" without opening the file. Relative paths resolve against the MCP server's working directory — under Claude Desktop, that's the cwd set in your MCP config, so files land in the user's project directory by default.

Tools

Quick Lookup (Ergast API — 1950-present)

Session Data (FastF1 Live Timing — 2018-present)

Telemetry (FastF1 Live Timing — 2018-present)

Utility

Resources

Prompts

Example queries (Claude Desktop)

Who won the 2024 Monaco Grand Prix and what was the strategy?
→ use race_recap prompt or call get_session_results + get_stint_analysis

Compare Verstappen and Leclerc's telemetry in 2024 Monaco qualifying
→ compare_telemetry(2024, "Monaco", "Q", "VER", "LEC")

Who had the fastest theoretical lap in 2024 Silverstone qualifying?
→ get_sector_times(2024, "Silverstone", "Q")

Show me the 2024 constructor standings after round 10
→ get_constructor_standings(2024, after_round=10)

Development

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=fastf1_mcp

# Lint
uv run ruff check src/

Data sources & coverage

Note: FastF1 session data is only available from 2018 onwards. Use get_race_results_historical for earlier seasons.

License

MIT