# fastf1-mcp

A local MCP server that gives Claude (or any MCP-compatible AI client) access to Formula 1 race data. Load any session from 2018 onwards, ask questions in natural language, and get answers backed by real telemetry, timing, and strategy data.

No hosted API. No credentials for data. Everything runs locally on your machine.

## Install

```bash
pip install fastf1-mcp
```

## Use with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "f1": {
      "command": "fastf1-mcp"
    }
  }
}
```

Restart Claude Desktop. Then ask:

## Use with Claude Code

```bash
claude mcp add f1 fastf1-mcp
```

Then in any Claude Code session, ask:

> "Load the 2024 Monaco qualifying and tell me who got pole"

> "Compare Verstappen and Leclerc's race pace at Silverstone"

> "What was Hamilton's pit strategy at Monza?"

## What It Does

The MCP server exposes 17 tools that Claude can call to fetch specific F1 data:

| Tool | What It Answers |
|------|----------------|
| `load_session` | Load a race, qualifying, or practice session |
| `season_calendar` | "What races are in 2024?" |
| `race_result` | "Who won?", "What was the podium?" |
| `qualifying_result` | "Who got pole?", "Q3 times?" |
| `lap_times` | "How consistent was Leclerc?" |
| `fastest_laps` | "Who set the fastest lap?" |
| `pit_stops` | "When did everyone pit?" |
| `tire_stints` | "What compounds did they use?" |
| `driver_telemetry` | "What was Verstappen's top speed?" |
| `head_to_head` | "Compare Norris vs Piastri" |
| `weather` | "Was it wet?" |
| `session_summary` | "Give me an overview of the race" |
| `track_evolution` | "Did the track get faster?" |
| `overtake_analysis` | "Who gained the most positions?" |
| `identify_driver` | "Who is car 44?" |
| `list_drivers` | "Who was in this session?" |
| `session_status` | "What session is loaded?" |

## Fuzzy Input Normalization

You don't need to know exact driver codes or race names. The server resolves natural language:

| You Say | Resolves To |
|---------|-------------|
| "Leclerc", "charles", "LEC", "16" | Charles Leclerc (LEC) |
| "checo", "Perez", "11" | Sergio Perez (PER) |
| "spa" | Belgian Grand Prix |
| "monza" | Italian Grand Prix |
| "silverstone" | British Grand Prix |
| "qualifying", "quali", "Q" | Qualifying session |

## How It Works

```
You ask Claude: "Who won the 2024 Bahrain race?"
     │
     ▼
Claude picks tool: load_session(year=2024, race="Bahrain", session="race")
     │
     ▼
fastf1-mcp loads data via FastF1 (cached locally after first download)
     │
     ▼
Claude picks tool: race_result()
     │
     ▼
fastf1-mcp returns structured JSON with the classification
     │
     ▼
Claude answers: "Verstappen won from Perez and Sainz..."
```

- **First load** of a session downloads from F1 servers (~10-30 seconds)
- **Every load after** is instant (cached at `~/.cache/f1_mcp/`)
- **No API keys** needed for F1 data — it's public timing data via FastF1
- Claude only sees small JSON tool results, not raw telemetry dumps

## Data Coverage

- **Seasons:** 2018 onwards (FastF1 limitation)
- **Sessions:** Race, Qualifying, Sprint, Practice (FP1/FP2/FP3)
- **Data:** Results, lap times, pit stops, tyre stints, telemetry (speed/throttle/brake), weather, circuit info

## Testing

```bash
pip install fastf1-mcp[test]

# Unit tests (no network, instant)
pytest tests/ -m "not integration" -v

# Full suite (downloads F1 data on first run, cached after)
pytest tests/ -v
```

133 tests covering normalization, session management, tool execution, and MCP protocol (stdio JSON-RPC handshake, tool listing, tool calls).

## Use as a Python Library

You can also import the package directly without MCP:

```python
from f1_mcp.session import SessionManager

mgr = SessionManager()
mgr.load(2024, "Monaco", "qualifying")

print(mgr.qualifying_result())
print(mgr.lap_times("Leclerc"))
print(mgr.head_to_head("Verstappen", "Norris"))
```

## License

MIT