f1-telemetry-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@f1-telemetry-mcp compare my two fastest laps and show me where I lost time"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
f1-telemetry-mcp
An MCP server that gives AI assistants (Claude Desktop, Cursor, any MCP client) structured access to racing-game telemetry: lap and sector times, lap comparisons, braking zones, tyre wear and raw car telemetry.
It ships with a bundled synthetic SAMPLE DATA session (fictional driver and circuit) so it works out of the box, and can ingest a live F1 23 UDP telemetry feed via f1-23-udp.
Not affiliated with Formula 1. This is an independent hobby project. It is not associated with, endorsed by, or connected to Formula 1, the FIA, EA Sports or Codemasters. "F1" and related marks belong to their owners. The bundled data is synthetic.
Quickstart
Requires Node.js 22+.
npm install
npm run build
npm start # stdio transport (what desktop MCP clients use)
npm start -- --http # Streamable HTTP on http://127.0.0.1:3333/mcpHTTP options: --port / PORT, --host / HOST, or MCP_TRANSPORT=http. It binds to localhost by default and has no auth, so don't expose it publicly as-is.
To load your own session file instead of the sample, set F1_SESSION_FILE=/path/to/session.json.
Claude Desktop
Add this to claude_desktop_config.json:
{
"mcpServers": {
"f1-telemetry": {
"command": "node",
"args": ["/absolute/path/to/f1-telemetry-mcp/dist/index.js"]
}
}
}Cursor
Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json:
{
"mcpServers": {
"f1-telemetry": {
"command": "node",
"args": ["/absolute/path/to/f1-telemetry-mcp/dist/index.js"]
}
}
}Or point it at the HTTP transport: { "mcpServers": { "f1-telemetry": { "url": "http://127.0.0.1:3333/mcp" } } }.
To load a recorded session, add "env": { "F1_SESSION_FILE": "/path/to/session.json" }.
Recording a live session (F1 23)
Turn on UDP telemetry in the game (port 20777, format 2023), then run:
npm run record -- --out my-session.json --laps 5 --driver "Me" --circuit "Monza"
F1_SESSION_FILE=my-session.json npm startRecording stops after --laps completed laps or when you press Ctrl+C. The adapter reads lap data, car telemetry, car damage (tyre wear) and car status (visual tyre compound) packets for the player car.
Related MCP server: iRacing MCP Server
Tools
Tool | What it returns |
| Driver, circuit, lap count, fastest lap, top speed, final tyre wear |
| Lap and sector times for every lap |
| Total and per-sector delta between two laps, plus time delta by distance |
| Fastest time for a sector, plus the theoretical best lap |
| Braking zones on a lap: start/end distance, entry and minimum speed |
| Wear (%) per corner per lap and average wear rate |
| Speed/throttle/brake/gear/RPM samples for a distance range, downsampled |
Resources: f1://session/summary and f1://session/laps/{lapNumber}. Inputs are validated with zod. Domain errors, like a lap that doesn't exist, come back as MCP tool errors rather than protocol failures.
Evals
evals/cases.json has 33 natural-language questions about the sample session. Each one lists the tool that should answer it, the JSON path to read and the expected value, with an optional numeric tolerance.
Deterministic (
npm run eval, runs in CI): calls the expected tool through a real in-memory MCP client and checks the answer. This tests the server and analysis code, not an LLM.Agent (
npm run eval:agent, optional): an LLM gets the questions plus the MCP tool list, picks and calls tools itself, and answers in JSON. Answers are scored with the same matcher, and pass rate, latency and tool calls are recorded. It needsANTHROPIC_API_KEYorOPENAI_API_KEY(EVAL_MODELoverrides the model), and skips if neither is set.Expected values come from the seeded sample generator. After changing the generator, run
npm run generate:sample && npx tsx evals/update-expected.tsand review the diff by hand.
Reports are written to evals/report.md and evals/report.json.
Mode | Cases | Passed | Notes |
Deterministic | 33 | 33 (100%) | sub-millisecond per call, in-memory transport |
Agent | 33 | not run yet | needs an API key; run it locally to fill this in |
Cases per tool: session summary 10, lap times 5, compare laps 5, braking points 5, fastest sector 4, tyre wear 4. get_car_telemetry is covered by unit tests only.
Architecture
flowchart LR
subgraph Sources
G[Synthetic generator<br/>seeded, SAMPLE DATA] --> J[(session JSON)]
U[F1 23 UDP feed] --> P[f1-23-udp parser] --> A[SessionAssembler] --> R[record CLI] --> J
end
J --> L[loadSession]
L --> F[Pure analysis functions]
F --> S[McpServer<br/>7 tools + 2 resources, zod]
S --> T1[stdio transport]
S --> T2[Streamable HTTP transport]
T1 --> C1[Claude Desktop / Cursor]
T2 --> C2[HTTP MCP clients]
S -.in-memory.-> E[Eval runners]Development
npm run lint && npm run typecheck && npm test && npm run evalGitHub Actions runs the same steps plus a build on every push and pull request.
How this was built
I built this with an agentic AI coding workflow under human review. I set the scope, the domain model and the constraints: synthetic data only, no real driver or team names, evals before polish. An AI coding agent then worked in small, separately committed steps (scaffold, ingest adapter, generator, analysis, server, tests, evals, transports, CI, docs), and lint, typecheck, unit tests and the eval suite had to pass at each step. I reviewed every change before it landed, including checking that the sample data really exercises the analysis (for example, sector bests come from different laps, so the theoretical best is faster than the fastest lap).
License
MIT
Available Tools
7 toolscompare_lapsA
Compare two laps: total and per-sector delta, plus time delta by distance (positive = lapB slower).
Inputs: lapA (required), lapB (required), stepM.
find_braking_pointsB
Detect braking zones on a lap (start/end distance, entry and minimum speed).
Inputs: lapNumber (required), threshold.
get_car_telemetryB
Speed/throttle/brake/gear/RPM samples for a lap within a distance range (downsampled to maxPoints).
Inputs: lapNumber (required), toM, fromM, maxPoints.
get_fastest_sectorC
Fastest time for a given sector and the theoretical best lap.
Inputs: sector (required), validOnly.
get_lap_timesC
Lap and sector times for every lap.
Inputs: validOnly.
get_session_summaryB
Overview of the loaded session: driver, circuit, laps, fastest lap, top speed, final tyre wear.
Inputs: no named parameters.
get_tyre_wearB
Tyre wear (%) per corner per lap and average wear rate.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct analytical purpose, even when operating on similar underlying data. Lap timing tools are separated into listing, comparison, and fastest-sector extraction, while telemetry tools are separated into raw sample retrieval and braking-zone detection.
All tool names follow a consistent snake_case verb_noun pattern (get_*, compare_*, find_*). The verbs are predictable and accurately describe the action.
Seven tools is a well-scoped set for F1 telemetry analysis. Each tool covers a distinct analysis need without obvious redundancy or bloat.
The surface covers session overview, lap timing, comparison, tyre wear, braking analysis, and raw telemetry. Minor gaps remain, such as weather, track position, stint/compound data, or pit-stop analysis, but core telemetry workflows are well covered.
Maintenance
Related MCP Connectors
AI race engineer for sim racing (Automobilista 2, Assetto Corsa, Assetto Corsa Competizione, Assetto Corsa Evo, RaceRoom). Provides telemetry analysis, braking diagnostics, and leaderboards. Connected via public demo by default. Get your free personal token at [https://flowix.com](https://flowix.com) to analyze your own laps.
Analytics your AI agent can actually use. Track, experiment, and optimize via MCP.
Racing telemetry, saved-run analysis, tracks, car-computer guidance and live pit-wall workflows.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered racing coaching and telemetry analysis for iRacing, providing real-time racing advice, car spotting, lap analysis, and conversational interaction with racing data through live telemetry streaming.2MIT
- AlicenseCqualityDmaintenanceEnables AI assistants to access real-time iRacing telemetry, race information, camera control, pit operations, and replay features through the MCP protocol.171MIT
- AlicenseAqualityDmaintenanceA local MCP server that gives Claude (or any MCP-compatible AI client) access to Formula 1 race data. Load any session from 2018 onwards, ask questions in natural language, and get answers backed by real telemetry, timing, and strategy data.171MIT
- AlicenseBqualityDmaintenanceMCP server that provides F1 telemetry analysis, tyre degradation modeling, and pit strategy recommendations, delivering race engineer-style calls grounded in real data. It exposes tools for degradation fits, fuel correction, and strategy reasoning via LangGraph.4MIT