io.github.darshjoshi/pitwall
Pitwall is an F1 data MCP server that acts as an F1 race engineer, providing access to real-time and historical Formula 1 data without requiring API keys.
Historical Data: Access race results and championship standings from 1950 to present, and list available seasons (2018–present).
Session & Calendar: Retrieve full race calendars, session details, and available data feeds for any race weekend.
Race Results: Get full race classification with positions, gaps, best laps, pit stops, and retirements. Retrieve lap-by-lap times for drivers, filterable by lap range.
Car Telemetry: Access detailed telemetry (speed, RPM, throttle, brake, gear, DRS) for specific laps at ~4Hz.
Strategy & Pit Stops: Analyze tyre strategies (compound, stint lengths, new/used) and pit stop details (fastest stops).
Race Control & Weather: View race control messages (flags, penalties, safety cars, investigations) and weather conditions (temperature, rain, wind, humidity). Also get speed trap readings at multiple track points per driver.
Driver Comparison: Compare two drivers head-to-head on position, pace, strategy, and pit stops.
Live Timing (No Auth Required): During live sessions, access session status, live running order with gaps, lap and sector times, tyre and stint info, race control messages, weather, speed trap rankings, mini-sector statuses, and more.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.darshjoshi/pitwall Who won the 2025 Australian GP?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Quick Start
Claude Code — one command, all 79 tools:
claude mcp add pitwall -- uvx --from "f1pitwall[full]" f1pitwallThen 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 f1pitwallpip install "f1pitwall[full]" # or just f1pitwall for lite
claude mcp add pitwall -- f1pitwallgit 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.pyInstall 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@pitwallClaude 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 flagsQuestion | Tool Used |
"Who won the Chinese GP?" |
|
"What was Verstappen's speed on lap 25?" |
|
"Compare Hamilton vs Leclerc" |
|
"What tyres did everyone use?" |
|
"Fastest pit stop at Australia 2025?" |
|
"When was the safety car?" |
|
"Was it raining during the race?" |
|
"Top speeds at Monza 2024?" |
|
"Norris's lap times in the race" |
|
"Who won the 2005 championship?" |
|
"Plot Verstappen vs Hamilton speed trace" |
|
"Show me the gear shift map at Monaco" |
|
"Who gained the most positions?" |
|
"Overtakes in the race" |
|
"Compare Verstappen lap 5 vs lap 50" |
|
"Ferrari head-to-head in qualifying" |
|
"Deleted laps in qualifying" |
|
"Gap to leader throughout the race" |
|
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 |
| Available seasons (2018-present) |
| Full season calendar with dates |
| Session details and available data feeds |
| Race classification — positions, gaps, best laps, pits |
| Lap-by-lap times, filterable by driver and lap range |
| Speed, RPM, throttle, brake, gear, DRS for a specific lap |
| Compound, stint length, new/used for every driver |
| All pit stops sorted by fastest |
| Flags, penalties, safety cars, investigations |
| Air/track temp, rain, humidity, wind |
| Speed at 4 measurement points per driver |
| Head-to-head: position, pace, strategy, pit stops |
| Race results from 1950 to present |
| Driver/constructor championships from 1950+ |
Live Timing (lite — no auth, reads F1's real-time SignalR feed during a session)
Tool | Description |
| Session name, flag/track status, lap count |
| Live running order with gap + interval |
| Last + best lap per driver |
| Sector times + speed trap for one driver |
| Gap to leader + interval to car ahead (mode-aware) |
| Personal-best sectors + best lap, ranked |
| Speed-trap (ST) ranking across the field |
| Best speed at I1/I2/FL/ST per driver |
| Compound, age (laps), stint number per driver |
| Full compound sequence per driver |
| Pit count + in-pit / out-lap flags |
| Air/track temp, humidity, wind, rain |
| Flags, penalties, track-limit deletions, SC/VSC |
| Time remaining in the session |
| Chronological track/session status log |
| Mini-sector status (green/purple/yellow) per driver |
FastF1 Tools (requires FastF1)
Category | Tools |
Visual Plots |
|
Telemetry Analysis |
|
Lap Analysis |
|
Strategy |
|
Race Analysis |
|
Pit Stops |
|
Driver & Team |
|
Track & Safety |
|
Speed & Position |
|
History |
|
Live (auth-gated) |
|
Session |
|
Setup
Claude Code:
claude mcp add pitwall -- python3 /absolute/path/to/pitwall.pyClaude 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 pythonThis 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.pyClaude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json:
To open this folder, press
Win + R, type%APPDATA%\Claude, and hit Enter. If theClaudefolder orclaude_desktop_config.jsondoesn'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 ispython(notpython3) on Windows.
Claude Code:
claude mcp add pitwall -- python3 /absolute/path/to/pitwall.pyClaude 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 |
2018-present | Telemetry, timing, strategy, pit stops, weather, race control | |
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 3000Live 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.pyThis 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 PrixDriver 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 = LindbladProject Files
File | Purpose |
| MCP server — 79 tools, auto-degrades to 30 without FastF1 |
| Raw SignalR Core WebSocket client for live race data |
| Zlib decompression for CarData.z / Position.z |
| Keyframe + delta state management for F1's incremental format |
| All 20 SignalR topics with auth/compression metadata |
| F1 TV token setup — browser-based OAuth flow |
Contributing
Found a bug? Want to add a tool? Contributions are welcome.
Fork the repo
Create a feature branch
Make your changes
Run the test suite:
python3 tests/pitwall_tool_validation.pyOpen 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
License
MIT
Available Tools
30 toolsget_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
Scored across 30 tools
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.
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.
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.
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
Related MCP Connectors
Anonymous read-only Formula 1 tools, resources, prompts, completion, and interactive dashboard.
Turn Claude or ChatGPT into a cycling coach that plans your week, grades it, and adapts. Free beta.
Describe your business to Claude and it builds your cockpit: a custom work tool with its assistant.
AI race engineer for sim racing (Automobilista 2, Assetto Corsa, Assetto Corsa Competizione, Assetto Corsa Evo, RaceRoom). Provides telemetry analysis, braking diagnostics, and leaderboards. Connected via public demo by default. Get your free personal token at [https://flowix.com](https://flowix.com) to analyze your own laps.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP 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.21MIT
- AlicenseAqualityDmaintenanceA 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.171MIT
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive Formula 1 data and analytics for Claude Desktop, including race results, telemetry, standings, and strategy insights through 36+ tools.1MIT
- AlicenseAqualityBmaintenanceTurns 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.147MIT