MCP Sport

MCP Sport — F1 Telemetry MCP 🏎️

[Animated race replay]

An MCP (Model Context Protocol) server that exposes Formula 1 data from the OpenF1 API as tools for AI assistants (Claude Desktop, Cursor, MCP Inspector, etc.).

Full coverage: 18 data tools matching the 18 documented OpenF1 endpoints — sessions, meetings, drivers, results, laps, pit stops, stints, telemetry, weather, championships and more. Two MCP App views sit on top of that data: a drivers standings board and an animated race replay. Hosts that render MCP Apps show the HTML. Cursor and Claude Desktop do not: they return the same payload as JSON.

Stack

Installation

# Clone and install dependenciesgit clone https://github.com/andrequeiroz2/mcp-sport.git mcp-sportcd mcp-sportuv sync

Usage

Run the server (stdio)

.venv/bin/python src/mcp_sport/server.py

MCP Inspector (web UI to test the tools)

npx @modelcontextprotocol/inspector@latest .venv/bin/python src/mcp_sport/server.py

In the Inspector UI: transport STDIO, command .venv/bin/python, args src/mcp_sport/server.py → Connect.

Claude Desktop / Cursor

Add to the client's MCP configuration:

{  "mcpServers": {    "f1-telemetry": {      "command": "/absolute/path/mcp-sport/.venv/bin/python",      "args": ["/absolute/path/mcp-sport/src/mcp_sport/server.py"]    }  }}

The 18 data tools work in both clients. The views do not render there.

Views (MCP Apps)

get_drivers_championship_view and get_race_replay_view return interactive HTML. Cursor and Claude Desktop are incompatible with MCP Apps: they ignore the UI and show the JSON payload. The MCP Inspector also treats the result as text.

The views were validated in the official basic-host from modelcontextprotocol/ext-apps. The server must be HTTP, with CORS exposing the MCP session headers. Otherwise the browser cannot complete the Streamable HTTP handshake.

Terminal 1 — MCP server on port 8765:

uv run python -c "import uvicornfrom starlette.middleware import Middlewarefrom starlette.middleware.cors import CORSMiddlewarefrom mcp_sport.server import mcp
app = mcp.http_app(middleware=[Middleware(    CORSMiddleware,    allow_origins=['*'],    allow_methods=['*'],    allow_headers=['*'],    expose_headers=['mcp-session-id', 'mcp-protocol-version'],)])uvicorn.run(app, host='127.0.0.1', port=8765)"

Terminal 2 — basic-host (needs Node.js; npm start requires bun, so use tsx):

git clone --depth 1 https://github.com/modelcontextprotocol/ext-apps.gitcd ext-apps/examples/basic-hostnpm installnpm run buildSERVERS='["http://127.0.0.1:8765/mcp"]' npx tsx serve.ts

Open http://localhost:8080 (sandbox on :8081) and call get_drivers_championship_view or get_race_replay_view. After a change to the view HTML, hard-refresh the page (Ctrl+Shift+R) before running the tool again. The host caches the ui:// resource.

Available tools (18)

Example conversation with the AI

"How many points did Norris score in the last two races?"

The AI orchestrates: get_sessions(session_type="Race") to discover recent sessions → get_session_results(session_key=..., driver_number=4) on each one.

Project structure

src/mcp_sport/├── server.py           # Entrypoint: FastMCP instance + tool registration├── exceptions.py       # Domain exceptions├── logging_config.py   # Logging to stderr (stdout is the protocol channel)├── clients/openf1.py   # Single OpenF1 HTTP client├── schemas/            # Pydantic: input (BaseInput) and output per endpoint├── validators/         # Business validations per endpoint├── services/           # Orchestration per endpoint├── tools/              # MCP tools (thin layer) per endpoint└── apps/               # MCP App views (Custom HTML, ui:// resource)    ├── championship_view.py  # Drivers standings board    └── race_replay_view.py   # Animated race replay

Canonical documentation

Configuration

Known limitations

• Historical data from 2023 onwards; real-time data requires a paid OpenF1 subscription
• session_result and starting_grid return HTTP 404 until official results are published
• Telemetry (car_data, location) returns 18–24k samples per session/driver. Narrow the call with range filters such as speed_min and date_from/date_to
• Championship endpoints are in beta on OpenF1

License

MIT. OpenF1 is an unofficial project, not associated in any way with the Formula 1 companies.