io.github.darshjoshi/pitwall

Quick Start

pip install f1pitwall
claude mcp add pitwall -- f1pitwall

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

Want visual plots and deep analysis? pip install "f1pitwall[full]"

git clone https://github.com/darshjoshi/pitwall.git && cd pitwall
pip install "mcp[cli]" requests        # lite
pip install -r requirements-full.txt   # full
claude mcp add pitwall -- python3 $(pwd)/pitwall.py

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 live 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
• Live during races — real-time positions, gaps, weather, and race control
• 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

Features

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

Lite Mode (14 tools)

pip install "mcp[cli]" requests — no heavy dependencies.

Race results, lap times, telemetry, tyre strategy, pit stops, weather, race control, speed traps, driver comparison, and historical data back to 1950. Uses F1's free static archive and the Jolpica API.

Full Mode (67 tools)

pip install -r requirements-full.txt — adds FastF1.

Everything in Lite, plus:

Lite Tools (always available)

FastF1 Tools (requires FastF1)

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.

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.

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

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

License

MIT