F1 数据 MCP 服务器

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

• 36 tools covering standings, race results, lap times, telemetry, pit stops, qualifying, race control, weather, race progression, tyre degradation, corner analysis, DRS zones and live championship projections
• Real circuit maps offline — every F1 circuit since 2018 drawn from bundled outline data, no download needed
• Charts — track maps, speed traces, race position charts, tyre strategies and lap-time plots returned as PNG images Claude can show inline
• Live replay bridge — follow a race playing in f1-race-replay and get race-engineer commentary
• 4 MCP resources for schedule, driver, constructor, and circuit reference data
• 6 guided prompts for race recaps, qualifying analysis, strategy deep-dives, weekend previews and live replay commentary
• 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

Gallery

These are unedited PNGs from the server's chart tools, the same images Claude shows inline, drawn from real F1 timing data via FastF1. Under each one is a question that brings it up and the tool it calls.

Quick start

No clone needed — uv runs the published package.

Claude Code

claude mcp add fastf1 -- uvx fastf1-mcp-server

Claude Desktop — add to claude_desktop_config.json and restart:

{
  "mcpServers": {
    "fastf1": {
      "command": "uvx",
      "args": ["fastf1-mcp-server"]
    }
  }
}

Then ask: "Plot the tyre strategies from the 2025 British Grand Prix" or "Who led every lap of the 2021 Saudi Arabian GP, and when were the red flags?"

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 (from a clone)

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)

Race Analysis (FastF1 Live Timing — 2018-present)

Charts (PNG images)

All chart tools accept save_path to also write the PNG into the export directory. plot_speed_trace also shades where DRS was open.

Live Replay (f1-race-replay)

These read the telemetry stream that f1-race-replay broadcasts on localhost:9999 while a replay is playing. Start a replay there (python main.py --viewer --year 2024 --round 12), then ask Claude what's happening.

The client drains the stream continuously and disconnects promptly — f1-race-replay's server writes on its render thread, so a client that stopped reading would freeze the replay.

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")

Where did Norris lose pole to Verstappen in 2024 Spain qualifying?
→ get_corner_analysis(2024, "Spain", "Q", "NOR", driver2="VER")

Why did everyone pit on lap 34? Were there any penalties?
→ get_race_control_messages(2024, "Hungary")

How quickly did the mediums degrade compared to the hards?
→ get_tyre_degradation(2024, "Bahrain")

Show me how the 2024 Brazil race unfolded
→ plot_position_chart(2024, "Brazil", highlight=["VER", "NOR", "RUS"])

Where was everyone when the safety car came out on lap 34?
→ plot_track_map(2024, "Hungary", "R", at_lap=34)

Draw the Suzuka circuit / show me all the 2026 tracks
→ plot_circuit("Suzuka") / plot_circuit(year=2026)

Who was leading the championship on the road at half distance in Abu Dhabi?
→ get_championship_projection(2024, "Abu Dhabi", after_lap=29)

What's happening in the replay right now?
→ get_replay_state() / watch_replay(duration_sec=10)

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