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.
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.
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.
Add this to claude_desktop_config.json:
{
"mcpServers": {
"f1-telemetry": {
"command": "node",
"args": ["/absolute/path/to/f1-telemetry-mcp/dist/index.js"]
}
}
}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" }.
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
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/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 needs ANTHROPIC_API_KEY or OPENAI_API_KEY (EVAL_MODEL overrides 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.ts and 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.
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]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.
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).
MIT
Compare two laps: total and per-sector delta, plus time delta by distance (positive = lapB slower).
| Name | Required | Description | Default |
|---|---|---|---|
| lapA | Yes | Lap number (1-based) | |
| lapB | Yes | Lap number (1-based) | |
| stepM | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the output convention ('positive = lapB slower'), which is real behavioral context, but says nothing about read-only nature, error behavior for invalid lap numbers, or any limits — notable gaps for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with the core action front-loaded and the output list and sign convention appended. No filler, nothing redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description does well to enumerate the returned deltas, but stepM's meaning (sampling step for the distance delta) is unexplained and the shape of the per-sector/distance output is not described. Adequate but with clear gaps for a 3-parameter analytical tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: lapA and lapB are documented as 1-based lap numbers, but stepM has no schema description. The description does clarify the ordering semantics between lapA and lapB via the sign convention, adding value beyond the schema, but it never explains stepM, leaving a parameter undocumented in both places.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Compare two laps') and enumerates the outputs it produces (total delta, per-sector delta, delta by distance). It is functionally distinguishable from siblings like get_lap_times or get_fastest_sector, though it never names an alternative to sharpen that boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the name and the 'Compare two laps' phrasing, but there is no explicit when-to-use guidance, no condition selecting it over get_lap_times, and no prerequisite or exclusion statements. The sign-convention note is interpretive, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect braking zones on a lap (start/end distance, entry and minimum speed).
| Name | Required | Description | Default |
|---|---|---|---|
| lapNumber | Yes | Lap number (1-based) | |
| threshold | No | Brake input threshold 0..1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden; it partially discharges it by disclosing the returned quantities (start/end distance, entry/minimum speed). However, it says nothing about read-only safety, cost, or how the threshold affects detection, so key traits remain implicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the parenthetical efficiently conveys the output payload. It is compact and wastes nothing, though it is too short to cover the remaining gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter, read-only analytics tool with full schema coverage, this is minimally adequate: purpose and outputs are stated. But with no annotations and no output schema, the missing safety/handling context and the unexplained effect of the threshold leave it short of complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both lapNumber and threshold are already documented in the schema with ranges and a default. The description adds no syntax or semantics beyond that, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Detect braking zones on a lap') and even summarizes the produced values (start/end distance, entry and minimum speed). This clearly separates it from siblings like get_lap_times or get_tyre_wear, though it never names an alternative to route against.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use, when-not-to-use, or alternative is given. The phrase 'on a lap' weakly implies the lapNumber requirement, but nothing tells the agent why to pick this over get_car_telemetry for braking data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Speed/throttle/brake/gear/RPM samples for a lap within a distance range (downsampled to maxPoints).
| Name | Required | Description | Default |
|---|---|---|---|
| toM | No | ||
| fromM | No | ||
| lapNumber | Yes | Lap number (1-based) | |
| maxPoints | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure. It usefully states that samples are downsampled to maxPoints, which adds behavior beyond the schema, but it does not mention read-only nature, permissions, ordering, units, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that contains no wasted words. The key resource and constraints are stated immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations, no output schema, and low schema coverage, the description is minimal but conveys the core return content and one important behavior (downsampling). It still omits units, return structure, and usage context, leaving gaps an agent must infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (lapNumber only), so the description should compensate. It adds meaning for the distance range and maxPoints downsampling but does not define fromM/toM individually, their units, defaults, or bounds beyond what the schema already shows.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names specific telemetry channels (speed, throttle, brake, gear, RPM) and scopes them to a lap and distance range, making the tool's resource clear. It does not explicitly differentiate itself from siblings like get_lap_times or find_braking_points, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It says what the tool returns and that it is scoped by distance, but gives no explicit guidance on when to use this tool versus alternatives such as get_lap_times or find_braking_points. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fastest time for a given sector and the theoretical best lap.
| Name | Required | Description | Default |
|---|---|---|---|
| sector | Yes | ||
| validOnly | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read operation but says nothing about what the returned 'fastest time' is scoped to (driver, session, lap), what 'theoretical best lap' is derived from, or how validOnly alters results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, which is front-loaded and easy to scan. However it is terse to the point of under-specification rather than genuinely efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 0% schema description coverage, the description is the only source of information and it leaves key gaps: result granularity, the meaning of the theoretical best lap, and the validOnly behavior are all undocumented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only alludes to the sector parameter without explaining the valid values (1/2/3). The validOnly flag, which defaults to true and presumably filters out invalid laps, is completely unexplained and materially changes results.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (fastest sector time) plus an additional output (theoretical best lap), so the agent knows what it returns. It does not differentiate itself from siblings like get_lap_times or compare_laps, leaving the boundary between 'fastest sector' and 'lap times' implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no mention of alternatives, and no indication of how this differs from get_lap_times or compare_laps. The agent must guess whether this is the right tool for sector-level analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lap and sector times for every lap.
| Name | Required | Description | Default |
|---|---|---|---|
| validOnly | No | Exclude invalidated laps |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no read-only confirmation, no statement about invalidated laps, no return shape, no pagination. The existence of invalidated laps is only implied indirectly through the schema's validOnly parameter, not through the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is front-loaded and free of waste, but brevity here reflects under-specification rather than disciplined concision. It is short without being informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and only a terse noun phrase, the definition leaves key questions unanswered: what identifies the laps being fetched, what the return structure looks like, and whether invalidated laps are included by default. For a data-retrieval tool this is a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, so the schema already documents validOnly ('Exclude invalidated laps'). The description adds nothing about that flag or its default behavior, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the resource (lap and sector times) and scope ('every lap'), but offers no verb and no differentiation from siblings like compare_laps or get_fastest_sector, which also return lap timing data. An agent can guess the purpose but cannot tell from the text how this differs from fetching fastest-sector or session-summary data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of prerequisites (e.g., a session or driver identifier), and no route to alternatives among the siblings. The agent must infer the use case entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overview of the loaded session: driver, circuit, laps, fastest lap, top speed, final tyre wear.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It mentions a 'loaded session' prerequisite but does not disclose read-only status, side effects, permissions, rate limits, or any other operational trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that lists the key contents with no filler. Every phrase contributes directly to understanding what the tool returns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Because there is no output schema, the description must carry return-value information, and it does list the summary fields. However, it omits return format, units, and other structural details, leaving clear gaps for a tool with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so per the rubric the baseline is 4. No additional parameter semantics are needed or missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear resource ('loaded session') and enumerates the summary fields returned (driver, circuit, laps, fastest lap, top speed, final tyre wear). It does not explicitly differentiate this tool from siblings such as get_lap_times or get_tyre_wear, though the field list implies a distinct aggregate view.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no when-to-use guidance or alternative-tool routing. An agent is not told when to prefer this overview over get_lap_times, compare_laps, get_tyre_wear, or get_car_telemetry.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tyre wear (%) per corner per lap and average wear rate.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It does reveal genuinely useful behavior: the metric is a percentage, it is broken down per corner and per lap, and an averaged wear rate is also returned. However, it says nothing about which session/driver the data is scoped to, whether results are paginated or large, or what happens if no session is active.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the granularity and unit with no filler. It is appropriately sized, though the terseness leaves the scoping question unaddressed rather than using the space for it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no annotations, and no output schema, the description is the only place to explain how the data is scoped — which session, which driver, which lap range. It omits that entirely, so an agent cannot tell whether the call needs implicit session context or returns everything. This is a meaningful gap for a data-retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema declares zero parameters, so there is nothing for the description to disambiguate and no coverage gap to compensate for. The baseline for a parameterless tool applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (tyre wear per corner per lap, plus average wear rate) with a unit, which cleanly separates it from get_car_telemetry and get_lap_times. It is framed as a return-value summary rather than an action, so the verb is only implied, but the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of how this differs from get_car_telemetry (which may also carry tyre data), and no indication of prerequisites or session context. The agent must infer everything about invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0compare_lapsfind_braking_pointsget_car_telemetryget_fastest_sectorget_lap_timesget_session_summaryget_tyre_wearScored 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.
Analytics your AI agent can actually use. Track, experiment, and optimize via MCP.
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
MCP server for building and testing AI agents with multi-model experimentation and insights.
