boxbox-f1 0.1.0

BoxBox — an F1 data agent MCP server for race data, standings, lap times, and strategy simulation

🏎️ BoxBox

Your F1 data agent — real race data, straight into Claude.

Live schedules, standings, lap times, and strategy simulation. One MCP server. Zero guesswork.

Ask Claude about any race weekend and get answers computed from real F1 data — the actual calendar, the actual championship standings, the actual lap times — not a hallucinated podium from two seasons ago.

⭐ Star this repo if you find it useful.

---

Try it in under a minute:

• 📦 Install it — uv pip install boxbox-f1, no config required
• 🔌 Add it to Claude — claude mcp add boxbox -- boxbox
• 🏁 Ask about F1 — "What's the race calendar this season?" and Claude answers with real data

---

🎯 What is this?

BoxBox is an MCP (Model Context Protocol) server that turns Claude into an F1 data agent.

It exposes nineteen tools — race schedules, championship standings, driver profiles and head-to-head comparisons, race results, qualifying, lap times, pit stops, circuit info and weather, real tyre stint data, and a tyre strategy simulator — backed by real F1 data from the Jolpica (Ergast-compatible), OpenF1, and Open-Meteo APIs. A shared async HTTP client and a 5-minute TTL cache keep requests fast and polite to the upstream APIs.

✅ All nineteen tools are live with real data, verified by a 32-test suite against the actual APIs.

---

✨ Features

📅 Race Schedule

• get_race_schedule — the F1 race calendar for any season, defaulting to the current one
• get_next_race — the next upcoming race: name, circuit, country, date, round
• get_race_weekend — every session time for a weekend: FP1–FP3, sprint, qualifying, race

🏆 Championship Standings

• get_driver_standings — position, driver, team, points, and wins for any season
• get_constructor_standings — the constructors' table with points and wins
• get_driver_season_results — race-by-race grid and finishing positions for a driver

👤 Driver Profiles & Comparisons

• get_driver_profile — full name, nationality, date of birth, team, and race number
• compare_drivers — side-by-side points, wins, podiums, poles, and average finish
• get_teammate_comparison — average qualifying gap and race finish gap within one team

⏱️ Race Results, Qualifying & Lap Data

• get_race_results — the classified finishing order: position, driver, team, time, points, grid, status
• get_qualifying_results — Q1/Q2/Q3 times and final grid position per driver
• get_lap_times — every lap a driver completed in a race, from OpenF1 (2023 onwards)
• get_pit_stops — every pit stop in a race: driver, lap, stop number, duration

🏟️ Circuits & Weather

• get_circuit_info — circuit name, city, country, coordinates, and Wikipedia URL
• get_circuit_history — every past winner at a circuit: year, driver, team, time
• get_weather_at_circuit — 3-day forecast at the track: temperature, rain probability, wind

🛞 Tyres & Strategy Simulation

• get_tyre_usage — each driver's real stint breakdown from OpenF1: compound, lap range, length
• simulate_race_strategy — lap-by-lap model with tyre degradation, fuel burn, and 22s pit cost
• find_optimal_strategy — sweeps all 30 valid one- and two-stop combinations and returns the fastest

⚙️ Under the Hood

• Single shared httpx.AsyncClient — lazily initialised, cleanly closed on shutdown
• Dict-backed TTL cache (5-minute default) so repeated questions don't hammer the APIs
• Everything configurable via environment variables, with sensible defaults built in

---

🧰 Tech Stack

Layer	Choice
Language	Python 3.10+
MCP framework	FastMCP 3.x
HTTP client	HTTPX (async, shared client)
CLI	Typer
Caching	In-memory TTL cache (5 min default)
Race data	Jolpica (Ergast-compatible API)
Live/telemetry data	OpenF1
Weather data	Open-Meteo
Build backend	Hatchling (src layout)
Package manager	uv
Testing	pytest

---

⚙️ Getting Started

Prerequisites

• Python 3.10+
• uv (recommended) or pip

Install

uv pip install boxbox-f1

The PyPI package is named boxbox-f1 (plain boxbox collides with an existing project), but the command and Python package are still just boxbox.

Run the server

boxbox
# or
python -m boxbox

Add it to Claude Code

claude mcp add boxbox -- boxbox

Add it to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add:

{
  "mcpServers": {
    "boxbox": {
      "command": "boxbox"
    }
  }
}

Restart Claude Desktop, then ask: "Who leads the F1 drivers championship right now?" — if Claude calls get_driver_standings and answers with real data, BoxBox is live.

If Claude Desktop can't find the boxbox command, use the absolute path to the binary instead (e.g. the output of which boxbox).

The same JSON block works in any other MCP client.

Development setup

git clone https://github.com/NalluriTanavreddy/boxbox.git
cd boxbox
uv venv
uv pip install -e ".[dev]"
pytest

Environment variables

All optional — sensible defaults are built in. See .env.example.

File	Variable	Purpose
.env	BOXBOX_ERGAST_BASE_URL	Base URL for the Jolpica (Ergast-compatible) F1 API
.env	BOXBOX_OPENF1_BASE_URL	Base URL for the OpenF1 live/telemetry API
.env	BOXBOX_OPENMETEO_BASE_URL	Base URL for the Open-Meteo forecast API
.env	BOXBOX_CACHE_TTL	Cache TTL in seconds (default 300)
.env	BOXBOX_HTTP_TIMEOUT	HTTP request timeout in seconds (default 30)

---

🗂️ Project Structure

src/boxbox/
├── server.py                # FastMCP instance, agent instructions, all @mcp.tool() wrappers
├── __main__.py              # `python -m boxbox` entry point
├── tools/
│   ├── schedule.py          # Race calendar, next race, weekend session times
│   ├── standings.py         # Driver + constructor standings, per-driver results
│   ├── drivers.py           # Driver profiles, head-to-head + teammate comparisons
│   ├── laps.py              # Race results, qualifying, lap times, pit stops
│   ├── strategy.py          # Tyre stints + strategy simulation engine
│   └── circuits.py          # Circuit info, history, weather forecast
└── utils/
    ├── http.py              # Shared lazy httpx.AsyncClient (get_client / close_client)
    ├── cache.py             # TTLCache — dict-backed, monotonic clock, 300s default
    ├── ergast.py            # Cached fetch helper for the Jolpica/Ergast API
    └── openf1.py            # Cached OpenF1 helper: session/round + driver resolution

tests/                       # pytest suite

---

🗺️ Roadmap

• Step 1 — Project scaffold: FastMCP server, wired-up placeholder tools, shared HTTP client, TTL cache
• Step 2 — Real data: nine live tools for schedule, standings, and drivers via Jolpica, with a live-API test suite
• Step 3 — Lap times, pit stops, and circuit info from real data
• Step 4 — Strategy simulation: tyre degradation + pit window modelling
• Step 5 — OpenF1 integration for lap and tyre stint data
• Step 6 — Publish to PyPI

---

📄 License

MIT — see LICENSE.

👤 Author

Built by NalluriTanavreddy.