{
  "markdown": "# Pitstop — F1 MCP Server\n\n<!-- mcp-name: io.github.praneethravuri/pitstop -->\n\nAn HTTP-first Model Context Protocol (MCP) server for Formula 1 data. Aggregates real-time, historical, and news data from multiple authoritative sources into 11 tools ready for any MCP client.\n\n**v0.5.0** | Author: [Praneeth Ravuri](https://github.com/praneethravuri)\n\n---\n\n## Install\n\n### Hosted endpoint (nothing to install)\n\nA free public instance runs on [Hugging Face Spaces](https://huggingface.co/spaces/praneeth1025/pitstop):\n\n```\nhttps://praneeth1025-pitstop.hf.space/mcp\n```\n\n```bash\nclaude mcp add --transport http pitstop https://praneeth1025-pitstop.hf.space/mcp\n```\n\nNote: the Space sleeps after long inactivity — the first request after a quiet spell takes a cold start.\n\n### Local install\n\nstdio, via [uvx](https://docs.astral.sh/uv/guides/tools/) (no clone needed):\n\n```bash\nPITSTOP_TRANSPORT=stdio uvx pitstop-f1\n```\n\n[Claude Code](https://docs.claude.com/en/docs/claude-code):\n\n```bash\nclaude mcp add pitstop -e PITSTOP_TRANSPORT=stdio -- uvx pitstop-f1\n```\n\n[Codex CLI](https://github.com/openai/codex):\n\n```bash\ncodex mcp add pitstop --env PITSTOP_TRANSPORT=stdio -- uvx pitstop-f1\n```\n\n[Gemini CLI](https://github.com/google-gemini/gemini-cli):\n\n```bash\ngemini mcp add pitstop uvx pitstop-f1 --env PITSTOP_TRANSPORT=stdio\n```\n\nVS Code:\n\n```bash\ncode --add-mcp '{\"name\":\"pitstop\",\"command\":\"uvx\",\"args\":[\"pitstop-f1\"],\"env\":{\"PITSTOP_TRANSPORT\":\"stdio\"}}'\n```\n\nClaude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), and Windsurf (`~/.codeium/windsurf/mcp_config.json`) share the same JSON shape:\n\n```json\n{\n  \"mcpServers\": {\n    \"pitstop\": {\n      \"command\": \"uvx\",\n      \"args\": [\"pitstop-f1\"],\n      \"env\": { \"PITSTOP_TRANSPORT\": \"stdio\" }\n    }\n  }\n}\n```\n\nDocker (HTTP transport, runs the full server incl. the F1 database):\n\n```bash\ndocker compose up\n# → http://localhost:8000/mcp\n```\n\n---\n\n## Overview\n\nPitstop exposes F1 data as 11 MCP tools over HTTP (default) or stdio. It pulls from FastF1, Jolpica, OpenF1, Wikidata, RSS feeds, and its own seeded F1 database, handling pagination, retries, caching, and concurrency limits transparently.\n\n---\n\n## Data Sources\n\n| Source | Coverage | Type |\n|--------|----------|------|\n| [FastF1](https://github.com/theOehrly/Fast-F1) | 2018–present | Historical / timing / telemetry |\n| [Jolpica-F1](https://github.com/jolpica/jolpica-f1) | 1950–present | Historical (Ergast-compatible) |\n| [OpenF1](https://openf1.org/) | 2023–present | Real-time |\n| [Wikidata](https://www.wikidata.org/) | All eras | SPARQL queries |\n| RSS Feeds (20 sources) | Live | News |\n| Pitstop F1 Database | 1950–present | Owned sqlite (seeded from F1DB, self-updated weekly from Jolpica) + per-lap times |\n\nDatabase refresh: `.github/workflows/db-update.yml` runs weekly to pull new Jolpica results into the owned F1 database.\n\n---\n\n## Tools\n\n| Tool | Description | Key Parameters |\n|------|-------------|----------------|\n| `get_session_data` | Race/qualifying results, lap times, weather, driver details (2018–present) | `year`, `gp`, `session`, `includes`, `page`, `page_size` |\n| `get_telemetry_data` | Lap-by-lap car telemetry (speed, throttle, brake, gears) (2018–present) | `year`, `gp`, `session`, `drivers`, `lap_numbers`, `max_points`, `page`, `page_size` |\n| `get_live_data` | Live intervals, pit stops, team radio, stints, race control, weather, position, laps, overtakes (2023–present) | `data_types`, `year`, `country`, `session_name`, `driver_number`, `compound`, `flag`, `category`, `page`, `page_size` |\n| `get_standings` | Driver and constructor championship standings (1950–present) | `year`, `round`, `type`, `driver_name`, `team_name`, `page`, `page_size` |\n| `get_schedule` | Race calendar and session schedule | `year`, `include_testing`, `round`, `event_name`, `only_remaining`, `page`, `page_size` |\n| `get_reference_data` | Circuits, drivers, constructors encyclopedia (1950–present) | `reference_type`, `year`, `name`, `page`, `page_size` |\n| `get_f1_news` | F1 headlines from 20 RSS sources | `source`, `limit`, `keywords`, `driver`, `team`, `circuit`, `year`, `date_from`, `date_to`, `page`, `page_size` |\n| `get_results` | Race/qualifying/sprint results, lap times, pit stops (1950–present) | `year`, `round`, `result_type`, `driver`, `page` |\n| `get_race_analysis` | Pace, tire degradation, stint summaries, consistency (2018–present) | `year`, `gp`, `session`, `drivers`, `analysis_type`, `page` |\n| `query_wikidata` | SPARQL queries to Wikidata for F1 biography, career records, history | `sparql`, `page`, `page_size` |\n| `query_f1_database` | Read-only SQL over pitstop's owned F1 database (1950–present): results, standings, driver family trees, team lineage | `sql`, `page`, `page_size` |\n\n---\n\n## Transport\n\n### HTTP (default)\n\n```bash\nuv sync\nuv run pitstop\n# → http://localhost:8000\n```\n\nMCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"pitstop\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### stdio (opt-in)\n\n```bash\nPITSTOP_TRANSPORT=stdio uv run pitstop\n```\n\nMCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"pitstop\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/path/to/pitstop\", \"pitstop\"],\n      \"env\": { \"PITSTOP_TRANSPORT\": \"stdio\" }\n    }\n  }\n}\n```\n\n---\n\n## Health API\n\n| Endpoint | Purpose |\n|----------|---------|\n| `GET /health` | Per-source status (FastF1, f1db, Jolpica, OpenF1, RSS) |\n| `GET /live` | Liveness probe |\n| `GET /ready` | Readiness probe |\n\nExample `/health` response:\n\n```json\n{\n  \"version\": \"0.5.0\",\n  \"overall\": \"ok\",\n  \"sources\": [\n    { \"name\": \"fastf1\",  \"status\": \"ok\", \"latency_ms\": 2,   \"detail\": \"cache writable\" },\n    { \"name\": \"f1db\",    \"status\": \"ok\", \"latency_ms\": 1,   \"detail\": \"\" },\n    { \"name\": \"jolpica\", \"status\": \"ok\", \"latency_ms\": 134, \"detail\": \"\" },\n    { \"name\": \"openf1\",  \"status\": \"ok\", \"latency_ms\": 98,  \"detail\": \"\" },\n    { \"name\": \"rss\",     \"status\": \"ok\", \"latency_ms\": 210, \"detail\": \"\" }\n  ]\n}\n```\n\n`overall` is `\"ok\"` / `\"degraded\"` / `\"down\"`. HTTP 200 / 207 / 503.\n\n---\n\n## Wikidata SPARQL\n\n`query_wikidata` runs SPARQL queries against [Wikidata](https://query.wikidata.org/) for biographical and historical F1 facts not covered by race APIs.\n\nOnly `SELECT` and `ASK` queries are accepted (read-only). Always include `LIMIT` in your query.\n\nExample — find F1 drivers with their birthdate:\n\n```sparql\nSELECT ?driver ?driverLabel ?birthDate WHERE {\n  ?driver wdt:P31 wd:Q5 ;\n          wdt:P641 wd:Q1968 ;\n          wdt:P569 ?birthDate .\n  SERVICE wikibase:label { bd:serviceParam wikibase:language \"en\" }\n} ORDER BY DESC(?birthDate) LIMIT 10\n```\n\n---\n\n## Pagination\n\nAll list-returning tools accept `page` (1-based, default 1) and `page_size` (defaults vary per tool: 10–50). Responses include a `pagination` block:\n\n```json\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"page\": 1,\n    \"page_size\": 20,\n    \"total_items\": 47,\n    \"total_pages\": 3,\n    \"has_next\": true,\n    \"has_prev\": false\n  }\n}\n```\n\n---\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PITSTOP_TRANSPORT` | `http` | `http` or `stdio` |\n| `PITSTOP_HOST` | `0.0.0.0` | Bind address (HTTP only) |\n| `PITSTOP_PORT` | `8000` | Listen port (HTTP only) |\n| `PITSTOP_ENV` | `development` | `development` or `production` |\n| `PITSTOP_LOG_LEVEL` | Depends on `PITSTOP_ENV` | `DEBUG` if development, else `INFO` |\n| `PITSTOP_LOG_FORMAT` | Depends on `PITSTOP_ENV` | `text` if development, else `json` |\n| `PITSTOP_ENABLE_CACHING` | `true` | Enable HTTP response and FastF1 disk caching |\n| `PITSTOP_CACHE_TTL_SECONDS` | `300` | HTTP response cache time-to-live (seconds) |\n| `PITSTOP_RATE_LIMIT_ENABLED` | `false` | Enable concurrent-call limiting |\n| `PITSTOP_RATE_LIMIT_PER_HOUR` | `3600` | Max concurrent calls (derived from per-hour quota) |\n| `FASTF1_CACHE` | `cache` | FastF1 cache directory path |\n\n---\n\n## Caching\n\nPitstop uses in-memory HTTP response caching (via [Hishel](https://github.com/karpetrosyan/hishel)) for GET requests with 200 responses. This keeps tool calls inside upstream rate limits:\n\n- **Jolpica**: 4 req/s, 500/hr\n- **OpenF1**: 3 req/s, 30/min\n- **Wikidata**: Query complexity limits\n- **RSS**: Per-feed redirects cached\n\nFastF1 maintains its own disk cache in `FASTF1_CACHE` directory. Control caching via:\n- `PITSTOP_ENABLE_CACHING=true` (default)\n- `PITSTOP_CACHE_TTL_SECONDS=300` (default)\n\n---\n\n## Development\n\n```bash\nuv sync --dev\nuv run pytest\nuv run ruff check src/\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## Credits & attribution\n\n| Source | Description | License |\n|--------|-------------|---------|\n| [F1DB](https://github.com/f1db/f1db) | Database seeded from F1DB and subsequently modified & extended by pitstop | CC BY 4.0 |\n| [FastF1](https://github.com/theOehrly/Fast-F1) | Python library for F1 timing, telemetry, and session data | MIT |\n| [Jolpica-F1](https://github.com/jolpica/jolpica-f1) | Ergast-compatible F1 data API, 1950–present; also used to self-update the F1DB-seeded database weekly | — |\n| [OpenF1](https://openf1.org/) | Free open-source API for real-time F1 data | MIT |\n| [Wikidata](https://www.wikidata.org/) | Open knowledge graph with SPARQL query service | CC0 |\n| [Ergast Motor Racing API](https://ergast.com/mrd/) | Historical F1 data 1950–2024 (now served via Jolpica) | — |\n| RSS Feeds (20 sources) | News headlines, credited collectively; see each feed's `link` field in `get_f1_news` results | Respective publishers |\n\nNot affiliated with Formula 1 or the FIA. Data provided by third-party sources under their respective terms.\n",
  "bytes": 9659,
  "sha": "a83c6a2b8bfc185f13aba25d4f06b1ba25146f2766d3e84e3470fb8d59591a6b",
  "repo_slug": "praneethravuri/pitstop",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_praneethravuri_pitstop_4c80d66a/readme"
}