Skip to main content
Glama
io.github.darshjoshi/pitwall

io.github.darshjoshi/pitwall

by darshjoshi

Quick Start

Claude Code — one command, all 79 tools:

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

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

Needs uv (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.

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

claude mcp add pitwall -- uvx --from f1pitwall f1pitwall
pip install "f1pitwall[full]"        # or just f1pitwall for lite
claude mcp add pitwall -- f1pitwall
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

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

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

Related MCP server: fastf1-mcp

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

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


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.

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

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, compare_sector_times

Strategy

get_driver_tyre_detail, get_stint_analysis, compare_tire_compounds, compare_tire_age_performance, analyze_starting_tires, compare_strategies

Race Analysis

get_race_results, get_sprint_results, get_session_summary, get_fastest_lap_data, detect_overtakes, compare_grid_to_finish, get_qualifying_progression

Pit Stops

get_pit_stop_detail, get_fastest_pit_stops

Driver & Team

get_driver_info, get_driver_standings, get_constructor_standings, team_head_to_head, get_team_laps, analyze_long_run_pace

Track & Safety

get_circuit_info, get_track_status, get_track_record, get_race_control_messages, get_penalties, get_dnf_list

Speed & Position

get_speed_trap_comparison, get_position_changes, get_gap_to_leader

History

get_race_winners_history

Live (auth-gated)

get_live_telemetry, get_live_gps_positions — live car telemetry + GPS, need an F1 TV token

Session

get_schedule, get_session_info, get_weather_data


Setup

Claude Code:

claude mcp add pitwall -- python3 /absolute/path/to/pitwall.py

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pitwall": {
      "command": "python3",
      "args": ["/absolute/path/to/pitwall.py"]
    }
  }
}

1. Find your Python path:

where python

This will return something like C:\Users\YourName\AppData\Local\Programs\Python\Python313\python.exe or C:\Python313\python.exe.

2. Note where you cloned Pitwall: For example: C:\Users\YourName\Projects\pitwall\pitwall.py

Claude Code (PowerShell):

claude mcp add pitwall -- python C:\Users\YourName\Projects\pitwall\pitwall.py

Claude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json:

To open this folder, press Win + R, type %APPDATA%\Claude, and hit Enter. If the Claude folder or claude_desktop_config.json doesn't exist, create them.

{
  "mcpServers": {
    "pitwall": {
      "command": "python",
      "args": ["C:\\Users\\YourName\\Projects\\pitwall\\pitwall.py"]
    }
  }
}

Note: Use double backslashes (\\) in the JSON path, or forward slashes (/) — both work. The command is python (not python3) on Windows.

Claude Code:

claude mcp add pitwall -- python3 /absolute/path/to/pitwall.py

Claude Desktop — add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pitwall": {
      "command": "python3",
      "args": ["/absolute/path/to/pitwall.py"]
    }
  }
}

Restart Claude Code or Claude Desktop after setup. Works with any MCP-compatible client.

Optional: Beginner-Friendly Skill (Claude Desktop)

Upload SKILL.md as a skill in Claude Desktop (Settings → Skills → Upload). Claude will explain F1 jargon inline — DRS, undercut, compound, safety car, etc.


Data Sources

All core data is free and requires no API keys.

Source

Coverage

What it provides

F1 Static Live Timing

2018-present

Telemetry, timing, strategy, pit stops, weather, race control

Jolpica-F1

1950-present

Historical results and championships

FastF1 (optional)

2018-present

Enhanced telemetry analysis and visual plots

F1 SignalR Core (optional)

Live only

Real-time race data during active sessions


How It Works

Pitwall reads from F1's publicly available static timing archive — the same data that powers the official F1 app. After each session ends (~30 minutes), F1 publishes 33 data feeds per session including full car telemetry (speed, RPM, throttle, brake, gear, DRS at ~4Hz per car), GPS positions, tyre data, pit stops, and race control messages.

The telemetry tool (get_telemetry) correlates the timing stream with the car data stream to extract telemetry for a specific driver on a specific lap — something no other F1 MCP server does.

Architecture

Claude ──MCP──> Pitwall ──HTTP──> livetiming.formula1.com/static/ (free)
                       ──HTTP──> api.jolpi.ca/ergast/f1/ (free)
                       ──lib──>  FastF1 (optional, local)
                       ──WS───> SignalR Core (optional, live races)

Running the Server

python3 pitwall.py              # MCP stdio (Claude Code / Claude Desktop)
python3 pitwall.py --http       # MCP HTTP (remote / self-hosted)
python3 pitwall.py --http --port 3000

Live Race Data

Pitwall includes a raw SignalR Core WebSocket client for real-time data during active F1 sessions. Most data is free — car telemetry and GPS require an F1 TV Pro or Premium subscription.

Note: The get_live_* MCP tools read this client's live SignalR feed directly. 16 timing tools (running order, gaps, lap/sector times, tyres, weather, race control, speed traps, mini-sectors, …) work in the lite install with no auth; live car telemetry and GPS (get_live_telemetry, get_live_gps_positions) need an F1 TV token and ship in the full install. Post-session data — telemetry, timing, strategy — also remains available through the main tools after each session ends.

Data

Free

F1 TV

Race positions, gaps, lap times

Yes

Yes

Race control, flags, penalties

Yes

Yes

Weather, track status

Yes

Yes

Tyre compounds, stint info

Yes

Yes

Team radio URLs

Yes

Yes

Car telemetry (speed, RPM, throttle, brake)

No

Yes

GPS positions (X/Y/Z coordinates)

No

Yes

All data (including telemetry and GPS) becomes free in the static archive ~30 minutes after a session ends.

python3 auth_setup.py

This opens a browser for F1 TV login. The token is saved locally:

  • <project_dir>/.f1token

  • ~/Library/Application Support/fastf1/f1auth.json (macOS)

Token expires every ~4 days. Re-run to refresh. Never uploaded anywhere.

import asyncio
from signalr_client import F1LiveClient

async def main():
    # Free mode — timing, weather, race control (no auth needed)
    client = F1LiveClient(no_auth=True)

    @client.on("TimingData")
    def on_timing(data, timestamp):
        for num, info in data.get("Lines", {}).items():
            print(f"P{info.get('Position','?')} #{num} Gap: {info.get('GapToLeader','')}")

    @client.on("RaceControlMessages")
    def on_rc(data, timestamp):
        for msg in data.get("Messages", {}).values():
            print(f"[{msg.get('Flag', '')}] {msg.get('Message', '')}")

    await client.connect()

asyncio.run(main())

For full telemetry (speed, RPM, throttle, brake, GPS):

from auth_setup import load_token

client = F1LiveClient(no_auth=False, auth_token=load_token())

@client.on("CarData.z")
def on_telemetry(data, timestamp):
    # Speed, RPM, throttle, brake, gear, DRS at ~4Hz per car
    ...

@client.on("Position.z")
def on_position(data, timestamp):
    # GPS X/Y/Z coordinates at ~4Hz per car
    ...

Reference

Race Names

Race names are fuzzy-matched. All of these work:

"china", "chinese", "shanghai"           → Chinese Grand Prix
"australia", "melbourne", "aus"          → Australian Grand Prix
"monaco", "monte carlo"                  → Monaco Grand Prix
"silverstone", "great britain", "british" → British Grand Prix

Driver Codes

VER = Verstappen    HAM = Hamilton    NOR = Norris     LEC = Leclerc
ANT = Antonelli     RUS = Russell     PIA = Piastri    BEA = Bearman
GAS = Gasly         LAW = Lawson      HAD = Hadjar     SAI = Sainz
ALO = Alonso        STR = Stroll      OCO = Ocon       BOT = Bottas
ALB = Albon         HUL = Hulkenberg  COL = Colapinto  LIN = Lindblad

Project Files

File

Purpose

pitwall.py

MCP server — 79 tools, auto-degrades to 30 without FastF1

signalr_client.py

Raw SignalR Core WebSocket client for live race data

decompressor.py

Zlib decompression for CarData.z / Position.z

merger.py

Keyframe + delta state management for F1's incremental format

topics.py

All 20 SignalR topics with auth/compression metadata

auth_setup.py

F1 TV token setup — browser-based OAuth flow


Contributing

Found a bug? Want to add a tool? Contributions are welcome.

  1. Fork the repo

  2. Create a feature branch

  3. Make your changes

  4. Run the test suite: python3 tests/pitwall_tool_validation.py

  5. Open a pull request


Credits

  • FastF1 by @theOehrly — the gold standard F1 Python library

  • Jolpica-F1 — the Ergast API successor

  • drivenrajat/f1 — inspiration for FastF1 tool patterns

Built by

Darsh Joshi — AI Engineer

LinkedIn GitHub Email

License

MIT

Available Tools

30 tools
get_championship_standingsB

Get championship standings from 1950 to present.

Args: year: Season year (0 = current) standings_type: 'driver' or 'constructor'

Inputs: year, standings_type. Returns: result

get_driver_comparisonA

Compare two drivers head-to-head — position, pace, strategy, pit stops.

Args: driver_a: First driver TLA (e.g. 'VER') driver_b: Second driver TLA (e.g. 'HAM') year: Season year race: Race name (partial match) session_type: Session type

Inputs: driver_a (required), driver_b (required), race, year, +1 more. Returns: result

get_historical_resultsA

Get historical F1 race results from 1950 to present.

Args: year: Specific year (0 = current season) race: Circuit name (e.g. 'monza', 'monaco') driver: Driver ID (e.g. 'verstappen', 'hamilton')

Inputs: race, year, driver. Returns: result

get_lap_timesB

Get lap-by-lap times for one or all drivers. Filterable by lap range.

Args: year: Season year race: Race name (partial match) driver: Driver TLA (e.g. 'VER') or empty for all session_type: Session type lap_start: First lap to include lap_end: Last lap to include

Inputs: race, year, driver, lap_end, +2 more. Returns: result

get_live_best_sectorsB

Live personal-best sector times and overall best lap per driver, ranked by lap position. No auth required.

Inputs: no named parameters. Returns: result

get_live_lap_timesA

Live last + best lap time per driver. No auth required.

Inputs: no named parameters. Returns: result

get_live_mini_sectorsA

Live mini-sector status per driver: g=green/personal-best, p=purple/overall-best, y=yellow, .=no data. No auth required.

Inputs: no named parameters. Returns: result

get_live_pit_activityA

Live pit-stop count and real-time in-pit / out-lap flags per driver. No auth required.

Inputs: no named parameters. Returns: result

get_live_positionsA

Live running order with gap-to-leader and interval. No auth required.

Inputs: no named parameters. Returns: result

get_live_race_controlA

Live race control: flags, penalties, track-limit deletions, SC/VSC. No auth required.

Inputs: no named parameters. Returns: result

get_live_sector_timesA

Live sector times + speed trap for one driver (TLA or car number). No auth required.

Inputs: driver (required). Returns: result

get_live_session_clockA

Live time remaining in the current session. No auth required.

Inputs: no named parameters. Returns: result

get_live_session_statusA

Live F1 session status: session name, flag/track status, lap count. No auth required. Honest 'no live session' message when nothing is running.

Inputs: no named parameters. Returns: result

get_live_speed_comparisonA

Live best speed at each measurement point (I1, I2, FL, ST) for every driver. No auth required.

Inputs: no named parameters. Returns: result

get_live_speed_trapA

Live speed-trap (ST) ranking across the whole field. No auth required.

Inputs: no named parameters. Returns: result

get_live_stint_historyA

Live full compound sequence and stint lengths for every driver in track-position order. No auth required.

Inputs: no named parameters. Returns: result

get_live_time_gapsA

Live gap to leader and interval to car ahead per driver, mode-aware (race gap vs quali/practice fastest). No auth required.

Inputs: no named parameters. Returns: result

get_live_track_status_historyA

Live chronological log of track-status and session-status changes. No auth required.

Inputs: no named parameters. Returns: result

get_live_tyresA

Live tyre compound, age (laps), and stint number per driver. No auth required.

Inputs: no named parameters. Returns: result

get_live_weatherA

Live track weather (air/track temp, humidity, wind, rain). No auth required.

Inputs: no named parameters. Returns: result

get_pit_stopsB

Get all pit stops sorted by fastest stop time.

Args: year: Season year race: Race name (partial match) session_type: Session type

Inputs: race, year, session_type. Returns: result

get_race_controlC

Get race control messages — flags, penalties, safety cars, investigations.

Args: year: Season year race: Race name (partial match) session_type: Session type category: Filter: 'Flag', 'SafetyCar', 'Drs', 'Other', or empty for all

Inputs: race, year, category, session_type. Returns: result

get_race_infoA

Get session details and list of available data feeds.

Args: year: Season year race: Race name (partial match — 'china', 'monaco', 'silverstone') session_type: 'Race', 'Qualifying', 'Sprint', 'Practice 1', etc.

Inputs: race, year, session_type. Returns: result

get_speed_trapsC

Get speed trap readings at 4 measurement points (I1, I2, FL, ST) per driver.

Args: year: Season year race: Race name (partial match) session_type: Session type

Inputs: race, year, session_type. Returns: result

get_standingsA

Get race classification — positions, gaps, best laps, pit stops, retirements.

Args: year: Season year (2018-2026) race: Race name (partial match — 'china', 'australia', 'monaco') session_type: 'Race', 'Qualifying', 'Sprint', etc.

Inputs: race, year, session_type. Returns: result

get_telemetryA

Get car telemetry — speed, RPM, throttle, brake, gear, DRS for a specific lap.

Returns ~60-90 samples at ~4Hz. Set lap=0 to see available laps.

Args: driver: Driver TLA (e.g. 'VER', 'HAM') — required year: Season year (2018-2026) race: Race name (partial match) lap: Lap number (0 = show available laps) session_type: Session type

Inputs: driver (required), lap, race, year, +1 more. Returns: result

get_tyre_strategyC

Get tyre strategy for every driver — compound, stint length, new/used tyres.

Args: year: Season year race: Race name (partial match) session_type: Session type

Inputs: race, year, session_type. Returns: result

get_weatherB

Get weather conditions during a session — temperature, rain, wind, humidity.

Args: year: Season year race: Race name (partial match) session_type: Session type

Inputs: race, year, session_type. Returns: result

list_racesA

List all races and sessions for a season with dates and session paths.

Args: year: Season year (2018-2026)

Inputs: year (required). Returns: result

list_seasonsA

List all available F1 seasons (2018-present).

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 30 tools

    Disambiguation5/5

    Each tool targets a distinct data subset: standings, driver comparison, lap times, telemetry, live positions, etc. Even similar tools are differentiated by time scope (historical vs live) and specific data (e.g., get_standings vs get_championship_standings). Descriptions are detailed and clarify boundaries.

    Naming Consistency5/5

    All tool names follow a clear verb_noun pattern (get_*, list_*), consistently using snake_case. Live tools are prefixed with 'get_live_', making the pattern predictable and easy to navigate.

    Tool Count4/5

    30 tools is slightly high but appropriate for the breadth of F1 data coverage, including historical, live, and telemetry. A few could potentially be merged (e.g., time gaps and positions) but the current granularity aids agent selection.

    Completeness5/5

    The tool set covers the full lifecycle of F1 data: standings, race results, lap times, pit stops, telemetry, weather, and real-time session updates. No obvious gaps for its stated domain; both historical (1950+) and live data are represented.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for Formula 1 data via the FastF1 library. Ask Claude (or any MCP-compatible client) about race results, lap times, telemetry, standings, pit stops, and qualifying — with historical data back to 1950 via the Ergast API.
      21
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      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.
      17
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive Formula 1 data and analytics for Claude Desktop, including race results, telemetry, standings, and strategy insights through 36+ tools.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Turns Claude into a race engineer for original Assetto Corsa by reading telemetry, storing laps, and providing engineer-grade summaries, alongside read/write access to car setups.
      14
      7
      MIT