pitwall

<!-- mcp-name: io.github.darshjoshi/pitwall -->
<h1 align="center">Pitwall</h1>

<p align="center">
  <strong>Turn Claude into your F1 race engineer.</strong><br>
  Real telemetry. Real strategy data. 75 years of history.
</p>

<p align="center">
  <a href="https://pypi.org/project/f1pitwall/"><img src="https://img.shields.io/pypi/v/f1pitwall?color=orange&label=PyPI" alt="PyPI"></a>
  <a href="https://pypi.org/project/f1pitwall/"><img src="https://img.shields.io/pypi/dm/f1pitwall?color=blue&label=Downloads" alt="Downloads"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10+-blue.svg" alt="Python 3.10+"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-purple.svg" alt="MCP Compatible"></a>
  <a href="https://github.com/darshjoshi/pitwall/stargazers"><img src="https://img.shields.io/github/stars/darshjoshi/pitwall?style=social" alt="GitHub Stars"></a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/darshjoshi/pitwall/main/assets/ver_vs_nor_abu_dhabi_2024_quali.png" alt="Verstappen vs Norris — Abu Dhabi 2024 Qualifying Speed Trace" width="700">
</p>

---

## Quick Start

**Claude Code** — one command, all 79 tools:

```bash
claude mcp add pitwall -- uvx --from "f1pitwall[full]" f1pitwall
```

Then ask Claude: *"Who won the 2025 Australian GP?"*

> Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (`curl -LsSf https://astral.sh/uv/install.sh | sh`). No pip, no virtualenv, no "which python3" — and you always get the latest release.
>
> First launch downloads the FastF1 stack (~540 MB) and takes about 25 seconds. Every launch after that is under a second. If the very first start times out, just restart Claude Code — the download is already cached.

Want the plugin instead, so you get the `f1` skill along with the server? See [Install as a Claude Code plugin](#install-as-a-claude-code-plugin).

<details>
<summary><strong>Lighter install (30 tools, no plots)</strong></summary>

Skips pandas/numpy/matplotlib/FastF1. Still includes all 16 live-timing tools.

```bash
claude mcp add pitwall -- uvx --from f1pitwall f1pitwall
```

</details>

<details>
<summary><strong>Install with pip instead</strong></summary>

```bash
pip install "f1pitwall[full]"        # or just f1pitwall for lite
claude mcp add pitwall -- f1pitwall
```

</details>

<details>
<summary><strong>Install from source instead</strong></summary>

```bash
git clone https://github.com/darshjoshi/pitwall.git && cd pitwall
pip install -r requirements.txt        # lite (incl. live timing)
pip install -r requirements-full.txt   # full
claude mcp add pitwall -- python3 $(pwd)/pitwall.py
```

</details>

### Install as a Claude Code plugin

The plugin ships the MCP server **and** the `f1` skill together — the skill teaches Claude which of the 79 tools to reach for and how to explain F1 to someone who's never watched a race.

```
/plugin marketplace add darshjoshi/pitwall
/plugin install pitwall@pitwall
```

### Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "pitwall": {
      "command": "uvx",
      "args": ["--from", "f1pitwall[full]", "f1pitwall"]
    }
  }
}
```

---

## Why Pitwall?

Claude knows F1 from training data — but it can't look up last week's race. It can't show you Verstappen's throttle trace through Turn 1. It doesn't know who pitted first or when the safety car came out.

Pitwall connects Claude to **real F1 data**:

- **Real data, not hallucinations** — actual timing feeds from formula1.com
- **Lap-level telemetry** — speed, RPM, throttle, brake, gear, DRS at 4Hz per car
- **Visual plots** — speed trace comparisons, gear shift maps returned as images
- **75 years of history** — every race result and championship since 1950
- **Fresh after every session** — full telemetry and timing published ~30 min after each session ends, back to 2018
- **Zero API keys** — all core data is free, no account needed

---

## What You Can Ask

```
"Who won the 2025 Australian GP?"           → Race results and classification
"Verstappen's speed on lap 25 at Monaco"    → Lap telemetry at 4Hz
"Plot Hamilton vs Norris speed trace"       → Visual speed comparison chart
"Compare Ferrari's tyre strategy"           → Stint-by-stint breakdown
"Who won the 1994 championship?"            → 75 years of history
"When was the safety car at Silverstone?"   → Race control messages and flags
```

<details>
<summary><strong>See all example questions</strong></summary>

| Question | Tool Used |
|----------|-----------|
| "Who won the Chinese GP?" | `get_standings` |
| "What was Verstappen's speed on lap 25?" | `get_telemetry` |
| "Compare Hamilton vs Leclerc" | `get_driver_comparison` |
| "What tyres did everyone use?" | `get_tyre_strategy` |
| "Fastest pit stop at Australia 2025?" | `get_pit_stops` |
| "When was the safety car?" | `get_race_control` |
| "Was it raining during the race?" | `get_weather` |
| "Top speeds at Monza 2024?" | `get_speed_traps` |
| "Norris's lap times in the race" | `get_lap_times` |
| "Who won the 2005 championship?" | `get_championship_standings` |
| "Plot Verstappen vs Hamilton speed trace" | `plot_telemetry_comparison` |
| "Show me the gear shift map at Monaco" | `plot_gear_shifts` |
| "Who gained the most positions?" | `compare_grid_to_finish` |
| "Overtakes in the race" | `detect_overtakes` |
| "Compare Verstappen lap 5 vs lap 50" | `plot_multi_telemetry_comparison` |
| "Ferrari head-to-head in qualifying" | `team_head_to_head` |
| "Deleted laps in qualifying" | `get_deleted_laps` |
| "Gap to leader throughout the race" | `get_gap_to_leader` |

</details>

---

## Features

**79 tools** across two modes. Pitwall auto-detects what's installed — no config changes needed.

### Lite Mode (30 tools)

`pip install f1pitwall` — light deps only (`mcp`, `requests`, plus `websockets`/`aiohttp` for live timing); no pandas/numpy/FastF1.

Race results, lap times, telemetry, tyre strategy, pit stops, weather, race control, speed traps, driver comparison, and historical data back to 1950. **Plus 16 live-timing tools** (running order, gaps, lap/sector times, tyres, weather, race control, speed traps, mini-sectors, …) that read F1's real-time SignalR feed during a session — no auth needed. (Live car telemetry + GPS are auth-gated and live in Full mode.) Uses F1's free static archive and the Jolpica API.

### Full Mode (79 tools)

`pip install -r requirements-full.txt` — adds [FastF1](https://github.com/theOehrly/Fast-F1).

Everything in Lite, plus:

| Category | What You Get |
|----------|-------------|
| **Visual Plots** | Speed trace comparisons, gear shift maps, multi-lap telemetry overlays |
| **Deep Telemetry** | Brake point analysis, RPM patterns, DRS usage, throttle traces |
| **Advanced Strategy** | Stint degradation, compound comparisons, tire age performance |
| **Race Intelligence** | Overtake detection, gap tracking, position changes, qualifying progression |

<details>
<summary><strong>Full tool list (79 tools)</strong></summary>

#### Lite Tools (always available)
| Tool | Description |
|------|-------------|
| `list_seasons` | Available seasons (2018-present) |
| `list_races` | Full season calendar with dates |
| `get_race_info` | Session details and available data feeds |
| `get_standings` | Race classification — positions, gaps, best laps, pits |
| `get_lap_times` | Lap-by-lap times, filterable by driver and lap range |
| `get_telemetry` | Speed, RPM, throttle, brake, gear, DRS for a specific lap |
| `get_tyre_strategy` | Compound, stint length, new/used for every driver |
| `get_pit_stops` | All pit stops sorted by fastest |
| `get_race_control` | Flags, penalties, safety cars, investigations |
| `get_weather` | Air/track temp, rain, humidity, wind |
| `get_speed_traps` | Speed at 4 measurement points per driver |
| `get_driver_comparison` | Head-to-head: position, pace, strategy, pit stops |
| `get_historical_results` | Race results from 1950 to present |
| `get_championship_standings` | Driver/constructor championships from 1950+ |

#### Live Timing (lite — no auth, reads F1's real-time SignalR feed during a session)
| Tool | Description |
|------|-------------|
| `get_live_session_status` | Session name, flag/track status, lap count |
| `get_live_positions` | Live running order with gap + interval |
| `get_live_lap_times` | Last + best lap per driver |
| `get_live_sector_times` | Sector times + speed trap for one driver |
| `get_live_time_gaps` | Gap to leader + interval to car ahead (mode-aware) |
| `get_live_best_sectors` | Personal-best sectors + best lap, ranked |
| `get_live_speed_trap` | Speed-trap (ST) ranking across the field |
| `get_live_speed_comparison` | Best speed at I1/I2/FL/ST per driver |
| `get_live_tyres` | Compound, age (laps), stint number per driver |
| `get_live_stint_history` | Full compound sequence per driver |
| `get_live_pit_activity` | Pit count + in-pit / out-lap flags |
| `get_live_weather` | Air/track temp, humidity, wind, rain |
| `get_live_race_control` | Flags, penalties, track-limit deletions, SC/VSC |
| `get_live_session_clock` | Time remaining in the session |
| `get_live_track_status_history` | Chronological track/session status log |
| `get_live_mini_sectors` | Mini-sector status (green/purple/yellow) per driver |

#### FastF1 Tools (requires FastF1)
| Category | Tools |
|----------|-------|
| **Visual Plots** | `plot_telemetry_comparison`, `plot_gear_shifts`, `plot_multi_telemetry_comparison`, `plot_driver_telemetry_comparison` |
| **Telemetry Analysis** | `analyze_brake_points`, `analyze_rpm_data`, `analyze_drs_usage` |
| **Lap Analysis** | `get_lap_times_fastf1`, `get_deleted_laps`, `analyze_lap_consistency`, `get_fastest_sectors`, `get_personal_best_laps`, `