MCP Sport

MCP Sport — F1 Telemetry MCP 🏎️

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 dependencies
git clone https://github.com/andrequeiroz2/mcp-sport.git mcp-sport
cd mcp-sport
uv 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 uvicorn
from starlette.middleware import Middleware
from starlette.middleware.cors import CORSMiddleware
from 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.git
cd ext-apps/examples/basic-host
npm install
npm run build
SERVERS='["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.