RaceHooks

io.github.racehooksPublished by GitHub account racehooksv0.4.4Updated Nov 3, 2026

Predictive models and analytics for motorsport — race intelligence delivered to your endpoint.

Overview

AI-generated overview

RaceHooks MCP gives an assistant access to motorsport (F1) race data, predictive analytics, telemetry and webhook management through a RaceHooks account.

What you can do
  • Query live session state and race weekend schedules
  • Browse races, qualifying, pit stops, tyres, weather and laps
  • Look up drivers, constructors, circuits and seasons with results and standings
  • Read post-race model insights, telemetry aggregates and fantasy scoring
  • Create, update, test, delete and rotate webhook subscriptions, and read delivery logs
  • Check subscription tier, billing plan and delivery usage statistics
When to use it
Useful when you want an assistant to answer questions about Formula 1 history, live sessions or race strategy, or to set up and monitor RaceHooks webhook feeds and delivery usage from chat.
Requirements
Local Node.js process installed from the npm package @racehooks/mcp (or run via npx). Requires a RaceHooks account with the environment variables RACEHOOKS_CLIENT_ID and RACEHOOKS_CLIENT_SECRET; the server exits without them. RACEHOOKS_BASE_URL is optional and defaults to the RaceHooks API. Network access to the RaceHooks API is needed, and many tools depend on the account's plan tier.
Before you install
Requires the account credentials RACEHOOKS_CLIENT_ID and RACEHOOKS_CLIENT_SECRET, which are sent to the RaceHooks API to obtain an access token. Webhook tools change account state: create, update, delete, test and rotate secrets, and rotating a secret invalidates the old one immediately. New webhook signing secrets are shown only once. Data access and features depend on a paid tier, and model outputs are probabilistic estimates, not facts.

Installation

In SourceWeft

  1. Open RaceHooks in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@racehooks/mcp

MCP server for RaceHooks — gives AI assistants (Claude, Cursor, Windsurf) direct access to RaceHooks predictive models and analytics for motorsport — race intelligence delivered to your endpoint.

[npm] [License: MIT]

RaceHooks is an independent service and is not affiliated with or endorsed by Formula One Management or the FIA. "Formula 1," "F1," and related marks are trademarks of Formula One Licensing BV.

What this does

Exposes your RaceHooks account to an AI assistant as 58 tools, 7 resources, and 6 guided prompts. Every call is made with your account's credentials, so what a tool returns depends on your plan (Free, Developer, or Custom). The data tools cover motorsport (including Formula 1).

Tools

Live

ToolWhat it doesKey argsPlan
get_live_sessionCurrent session state: flag, lap, running order, intervals, tyres, race control messages. Empty when nothing is live.—All (Free gets the latest milestone classification instead of live timing)
list_eventsRace weekends with session schedules and status.year, upcoming, limitAll

Post-race insights

ToolWhat it doesKey argsPlan
list_insight_racesRaces with a completed post-race analytics bundle.seasonAll
get_race_insightsPer-driver, per-lap model outputs (pit, safety car, overtake, undercut, tyre health, cliff risk, LTOE, win probability, expected points) plus pit stops, stints, and lap times.raceIdAll (Free gets tyre state only; strategic predictions need Developer+)
get_model_metaPublic model manifest: what each model predicts, model family, calibration tier, last trained.—All
get_session_analyticsPer-lap analytics snapshot for a session.sessionIdDeveloper+
get_race_summaryPost-race analytics status and aggregate telemetry metrics.raceIdAll (aggregates need Developer+)

Races

ToolWhat it doesKey argsPlan
get_raceRace details with results and qualifying grid.raceIdAll (timing fields need Developer+)
get_race_qualifyingQualifying results.raceIdAll (Q1/Q2/Q3 times need Developer+)
get_race_pitstopsPit stop records (driver, stop, lap, duration).raceIdAll
get_race_tyresTyre stints (compound, lap range, tyre age).raceIdAll
get_race_weatherLap-by-lap weather.raceIdAll
get_race_lapsPer-lap times and positions.raceId, driverIdDeveloper+
get_event_pacePractice and qualifying pace summary per driver.eventIdDeveloper+

History (drivers, constructors, circuits, seasons)

ToolWhat it doesKey argsPlan
list_driversDrivers, searchable.search, nationality, active, limit, offsetAll (page size 25 on Free, 100 paid)
get_driverDriver profile with career stats.driverIdAll
get_driver_resultsRace-by-race results for a driver.driverId, seasonAll (timing fields need Developer+)
get_driver_standingsChampionship standings history for a driver.driverId, seasonAll
list_constructorsConstructors.lineage, active, limit, offsetAll
get_constructorConstructor profile with lineage history.constructorIdAll
get_constructor_resultsRace-by-race results for a constructor.constructorId, seasonAll (timing fields need Developer+)
get_constructor_standingsChampionship standings history for a constructor.constructorId, seasonAll
list_circuitsCircuits with location.country, limit, offsetAll
get_circuitCircuit details and analytics.circuitIdAll
list_seasonsSeasons with race counts.—All
get_season_standingsFinal driver and constructor standings for a season.yearAll
get_season_racesRaces in a season.yearAll

Telemetry

ToolWhat it doesKey argsPlan
get_telemetry_lapsPer-lap telemetry aggregates (speed, throttle, brake, DRS, aggression).raceId, driverId, lapNumberDeveloper+
get_telemetry_driver_lapsPer-lap telemetry for one driver.raceId, driverIdDeveloper+
get_telemetry_lap_comparisonEvery driver's telemetry for one lap.raceId, lapNumberDeveloper+
get_telemetry_race_summaryRace-level telemetry summary.raceIdDeveloper+
get_race_telemetry_lapsPer-lap telemetry metrics from the race data API.raceId, driverIdDeveloper+
get_race_telemetry_stintsPer-stint telemetry and degradation slopes.raceId, driverIdCustom
get_race_telemetry_aggressionDriver aggression index rankings.raceIdCustom

Fantasy

ToolWhat it doesKey argsPlan
get_fantasy_scoresEstimated F1 Fantasy points per driver with full breakdown.raceIdDeveloper+
get_fantasy_pit_timesPit-stop time leaderboard (stationary time) for a session.sessionIdDeveloper+

Account, usage and webhooks

ToolWhat it doesKey argsPlan
list_feedsFeed catalog with the plan each feed requires.limitAll
list_webhooksWebhook subscriptions on the account.limit, offsetAll
get_webhookOne webhook by ID.webhookIdAll
create_webhookCreate a webhook; returns the signing secret once.feedId, webhookUrl, webhookMethod, filtersAll
update_webhookChange URL, method, or filters; pause/resume with active.webhookId, webhookUrl, filters, activeAll
delete_webhookDelete a webhook.webhookIdAll
test_webhookSend a test payload now.webhookIdAll
get_webhook_logsRecent delivery logs.webhookId, limitAll
get_webhook_secretCurrent signing secret.webhookIdAll
rotate_webhook_secretRotate the signing secret (old one stops working immediately).webhookIdAll
get_subscriptionTier, plan limits, and usage snapshot.—All
get_usageDeliveries and failures this period, remaining bucket.—All
get_usage_by_feedDeliveries by feed this period.—All
get_usage_latencyDelivery latency percentiles by feed.—All
get_usage_hourlyHourly deliveries for the last 24 hours.—All
get_usage_historyDelivery history across past periods.—All
get_billing_planCurrent plan, limits, usage this period, and billing period dates.—All

Session replay

ToolWhat it doesKey argsPlan
list_replay_sessionsRecorded sessions that can be replayed.year, type, limit, offsetAll (Free and Developer: current season only)
get_demo_sessionThe curated demo session to replay.—All
get_replay_quotaReplay delivery quota (distinct-session slots) for your tier.—All
prepare_replayPrepare a session's playback artifact.sessionIdAll
get_replay_statusWhether a session's playback artifact is ready.sessionIdAll

Resources (read-only context)

  • racehooks://feeds — full feed catalog
  • racehooks://live — current live session state
  • racehooks://webhooks — all webhook subscriptions
  • racehooks://usage — current delivery usage
  • racehooks://drivers — current-season driver roster
  • racehooks://circuits — circuits with location
  • racehooks://seasons — seasons with race counts

Prompts (guided workflows)

  • setup_race_event_webhook — create an events.race subscription with filters
  • setup_fantasy_scoring_webhook — create a fantasy-optimised subscription
  • check_account_health — full account health summary
  • analyze_race_strategy — pit strategy, tyre management, and model predictions for one race
  • compare_drivers — two drivers head-to-head across a race
  • explain_ml_predictions — what the models predicted vs what happened in the latest analysed race

Installation

bash
npm install -g @racehooks/mcp

Or run directly with npx:

bash
npx @racehooks/mcp

Get your API credentials at racehooks.io.

Use of RaceHooks through this MCP server is subject to the RaceHooks Terms of Service and Privacy Policy. Model outputs are probabilistic estimates, not statements of fact.

Configuration

Two environment variables are required; the server exits on start-up without them:

bash
export RACEHOOKS_CLIENT_ID="your-client-id"export RACEHOOKS_CLIENT_SECRET="your-client-secret"# Optional — defaults to https://api.racehooks.ioexport RACEHOOKS_BASE_URL="https://api.racehooks.io"

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

json
{  "mcpServers": {    "racehooks": {      "command": "npx",      "args": ["-y", "@racehooks/mcp"],      "env": {        "RACEHOOKS_CLIENT_ID": "your-client-id",        "RACEHOOKS_CLIENT_SECRET": "your-client-secret"      }    }  }}

Claude Code

Claude Code does not read MCP servers from .claude/settings.json. Add the server with the CLI:

bash
claude mcp add racehooks \  -e RACEHOOKS_CLIENT_ID=your-client-id \  -e RACEHOOKS_CLIENT_SECRET=your-client-secret \  -- npx -y @racehooks/mcp

Add --scope project to write it to a shared .mcp.json in your project, or --scope user to make it available in every project. To check the file in without committing secrets, reference environment variables in .mcp.json:

json
{  "mcpServers": {    "racehooks": {      "command": "npx",      "args": ["-y", "@racehooks/mcp"],      "env": {        "RACEHOOKS_CLIENT_ID": "${RACEHOOKS_CLIENT_ID}",        "RACEHOOKS_CLIENT_SECRET": "${RACEHOOKS_CLIENT_SECRET}"      }    }  }}

Cursor / Windsurf

Add to your MCP config (.cursor/mcp.json or equivalent):

json
{  "mcpServers": {    "racehooks": {      "command": "npx",      "args": ["-y", "@racehooks/mcp"],      "env": {        "RACEHOOKS_CLIENT_ID": "your-client-id",        "RACEHOOKS_CLIENT_SECRET": "your-client-secret"      }    }  }}

Cline

In Cline, open MCP Servers → Installed → Configure MCP Servers and add to cline_mcp_settings.json:

json
{  "mcpServers": {    "racehooks": {      "command": "npx",      "args": ["-y", "@racehooks/mcp"],      "env": {        "RACEHOOKS_CLIENT_ID": "your-client-id",        "RACEHOOKS_CLIENT_SECRET": "your-client-secret"      },      "disabled": false    }  }}

Example usage with Claude

Once configured, you can ask Claude things like:

"Check my RaceHooks account health"

"Create an events.race webhook for https://myapp.com/hook, filtering for Ferrari only"

"Compare VER and NOR tyre degradation in the last race"

"Show me which feeds are using the most delivery quota today"

"Set up a fantasy scoring webhook for my VER, NOR, LEC team at https://scoring.myapp.com/hook"

Security

The MCP server runs as a local stdio process — it never binds a network port. Your credentials are passed via environment variables, are sent only to the RaceHooks API (to obtain an access token), and are never included in tool calls or resource URIs.

All API calls are authenticated using OAuth 2 client credentials (token auto-refreshes before expiry).

Links

Source: README.md at commit 9aba843

Tools

58

list_feeds

List Feeds

List all available RaceHooks data feeds, including which subscription tier each feed requires. The special 'events.race' feed is a synthetic feed that emits structured events (overtakes, pit stops, safety cars, etc.) derived from multiple raw feeds.

Parameterslimit

list_webhooks

List Webhooks

List all webhook subscriptions for the authenticated RaceHooks account.

Parameterslimitoffset

get_webhook

Get Webhook

Get a single webhook subscription by ID.

ParameterswebhookIdrequired

create_webhook

Create Webhook

Register a new webhook subscription. Returns the webhook and the HMAC signing secret (shown once — store it immediately).

ParametersfeedIdrequiredfilterswebhookUrlrequiredwebhookMethod

update_webhook

Update Webhook

Update an existing webhook subscription. Use active: false to pause delivery, active: true to resume. Can also update the endpoint URL, HTTP method, or filters without deleting and recreating the webhook.

ParametersactivefilterswebhookIdrequiredwebhookUrlwebhookMethod

delete_webhook

Delete Webhook

Permanently delete a webhook subscription.

ParameterswebhookIdrequired

test_webhook

Test Webhook

Send a test payload to a webhook endpoint immediately. Useful for verifying your server is reachable and your HMAC verification code is correct.

ParameterswebhookIdrequired

get_webhook_logs

Get Webhook Logs

Retrieve recent delivery logs for a webhook — shows status codes, retry counts, and payload excerpts.

ParameterslimitwebhookIdrequired

get_webhook_secret

Get Webhook Secret

Retrieve the current HMAC signing secret for a webhook.

ParameterswebhookIdrequired

rotate_webhook_secret

Rotate Webhook Secret

Rotate the HMAC signing secret for a webhook. The old secret is invalidated immediately — update your server before calling this. The new secret is shown once.

ParameterswebhookIdrequired

get_live_session

Get Live Session

Get the current live session state: flag status, lap number, driver positions, intervals, tyre compounds, and recent race control messages. Returns an empty/inactive context when no session is live. Live per-driver timing requires Developer or higher; Free receives the latest milestone classification (end of a qualifying segment or the final result) instead.

Takes no parameters.

list_events

List Events

List events (race weekends) for the current or a specific season, including session schedules and status.

Parametersyearlimitupcoming

get_subscription

Get Subscription

Get the current subscription tier, plan limits (webhooks, deliveries, HMAC, analytics enrichment), and live usage snapshot for this account.

Takes no parameters.

get_usage

Get Usage

Get delivery usage summary for the current period: total deliveries, failures, tier, and remaining monthly delivery bucket.

Takes no parameters.

get_usage_by_feed

Get Usage By Feed

Get webhook delivery counts broken down by feed for the current period. Useful for identifying which feeds are driving delivery volume.

Takes no parameters.

get_usage_latency

Get Usage Latency

Get webhook delivery latency percentiles (p50, p95, p99) broken down by feed for the current period.

Takes no parameters.

get_usage_hourly

Get Usage Hourly

Get webhook delivery volume broken down by hour for the last 24 hours. Useful for identifying traffic spikes.

Takes no parameters.

get_usage_history

Get Usage History

Get historical delivery counts and failure rates over past periods.

Takes no parameters.

get_billing_plan

Get Billing Plan

Get the detailed billing plan including tier, subscription period end date, limits, and current usage.

Takes no parameters.

list_replay_sessions

List Replay Sessions

List recorded sessions that have archived data and can be replayed. Only completed sessions with archive paths are returned. Self-serve tiers (Free and Developer) list the current season only, plus the curated demo session; the full historical archive is on Custom. `restrictedToSeason` in the response reports the applied limit.

Parameterstypeyearlimitoffset

get_demo_session

Get Demo Session

Get the curated demo session to replay (the canonical ID of a guaranteed-real event).

Takes no parameters.

get_replay_quota

Get Replay Quota

Get the replay delivery quota for this account: distinct-session lifetime slots for your tier.

Takes no parameters.

prepare_replay

Prepare Replay

Prepare a session for recorded playback, generating its playback artifact if not already cached. Check readiness with get_replay_status.

ParameterssessionIdrequired

get_replay_status

Get Replay Status

Check whether a session's playback artifact is ready to stream.

ParameterssessionIdrequired

list_drivers

List Drivers

List drivers. Available on every plan; page size is capped at 25 on Free and 100 on paid plans.

Parameterslimitactiveoffsetsearchnationality

get_driver

Get Driver

Get a driver profile with career statistics (wins, podiums, poles, championships). Available on every plan.

ParametersdriverIdrequired

get_driver_results

Get Driver Results

Get race-by-race results for a driver. Available on every plan; timing fields (gap, finish time) are only returned on Developer and above.

ParameterslimitoffsetseasondriverIdrequired

get_driver_standings

Get Driver Standings

Get championship standings history for a driver across seasons. Available on every plan.

ParametersseasondriverIdrequired

list_constructors

List Constructors

List constructors. Available on every plan.

Parameterslimitactiveoffsetlineage

get_constructor

Get Constructor

Get a constructor profile including its lineage history (predecessor and successor teams). Available on every plan.

ParametersconstructorIdrequired

get_constructor_results

Get Constructor Results

Get race-by-race results for a constructor. Available on every plan; timing fields (gap, finish time) are only returned on Developer and above.

ParameterslimitoffsetseasonconstructorIdrequired

get_constructor_standings

Get Constructor Standings

Get championship standings history for a constructor across seasons. Available on every plan.

ParametersseasonconstructorIdrequired

list_circuits

List Circuits

List all F1 circuits with location and coordinates. Available on every plan.

Parameterslimitoffsetcountry

get_circuit

Get Circuit

Get circuit details and analytics (compound priors, historical pace data). Available on every plan.

ParameterscircuitIdrequired

list_seasons

List Seasons

List all available F1 seasons with race counts. Available on every plan.

Takes no parameters.

get_season_standings

Get Season Standings

Get final driver and constructor championship standings for a season. Available on every plan.

Parametersyearrequired

get_season_races

Get Season Races

List all races in a season with circuit, date, and data quality tier. Available on every plan.

Parametersyearrequired

get_race

Get Race

Get race details with full results and qualifying grid. Available on every plan; timing fields (gaps, fastest lap, finish time, Q1/Q2/Q3 times) are only returned on Developer and above.

ParametersraceIdrequired

get_race_qualifying

Get Race Qualifying

Get qualifying results for a race. Available on every plan; Q1/Q2/Q3 times are only returned on Developer and above.

ParametersraceIdrequired

get_race_pitstops

Get Race Pitstops

Get all pit stop records for a race (driver, stop number, lap, duration). Available on every plan.

ParametersraceIdrequired

get_race_tyres

Get Race Tyres

Get tyre stint records for a race (driver, stint number, lap range, compound, tyre age). Available on every plan.

ParametersraceIdrequired

get_race_weather

Get Race Weather

Get lap-by-lap weather data for a race. Available on every plan.

ParametersraceIdrequired

get_race_laps

Get Race Laps

Get per-lap times and positions for a race. Requires Developer or higher. Optionally filter to a single driver with driverId.

ParametersraceIdrequireddriverId

get_race_summary

Get Race Summary

Get the post-race analytics status and aggregate telemetry metrics for a race. Status is available on every plan; the aggregate metrics are only returned on Developer and above.

ParametersraceIdrequired

get_race_telemetry_laps

Get Race Telemetry Laps

Get per-lap telemetry metrics (speed, throttle, brake, DRS, aggression) from telemetry data. Requires Developer or higher. Optional driverId to filter to one driver.

ParametersraceIdrequireddriverId

get_race_telemetry_stints

Get Race Telemetry Stints

Get per-stint telemetry metrics and degradation slopes. Requires a Custom plan (not included in Developer).

ParametersraceIdrequireddriverId

get_race_telemetry_aggression

Get Race Telemetry Aggression

Get driver aggression index rankings for a race. Requires a Custom plan (not included in Developer).

ParametersraceIdrequired

get_session_analytics

Get Session Analytics

Get per-lap ML analytics snapshot for a session (pit probability, SC probability, tyre health, LTOE, win probability). Requires Developer or higher.

ParameterssessionIdrequired

get_event_pace

Get Event Pace

Get practice and qualifying pace summary per driver for an event. Requires Developer or higher.

ParameterseventIdrequired

list_insight_races

List Insight Races

List races that have a completed post-race analytics pipeline — i.e. races where get_race_insights will return data. Available on every plan.

Parametersseason

get_race_insights

Get Race Insights

Get the full post-race ML analytics bundle for a race. Includes per-driver per-lap outputs: pit stop probability, safety car probability, overtake probability, undercut probability, tyre health, cliff risk and lap prediction, fuel-corrected lap time (LTOE), win probability, expected championship points. Also includes pit stops, tyre stints, lap times, and safety-car lap list. Output depends on plan: Free receives the descriptive data plus tyre state only (compound, tyre life, tyre health); the strategic predictions require Developer or higher.

ParametersraceIdrequired

get_model_meta

Get Model Meta

Get the public model manifest for each RaceHooks predictive model: what it predicts, its model family, a qualitative calibration tier, when it was last trained, and a changelog. Raw evaluation metrics are not exposed. Available on every plan.

Takes no parameters.

get_telemetry_laps

Get Telemetry Laps

Get per-lap telemetry aggregates (avg/max speed, throttle, brake, DRS, aggression index). Returns all drivers by default. Filter with driverId or lapNumber. Requires Developer or higher.

ParametersraceIdrequireddriverIdlapNumber

get_telemetry_driver_laps

Get Telemetry Driver Laps

Get per-lap telemetry for a single driver across all laps of a race. Requires Developer or higher.

ParametersraceIdrequireddriverIdrequired

get_telemetry_lap_comparison

Get Telemetry Lap Comparison

Get all drivers' telemetry for a single lap — useful for side-by-side lap comparisons. Requires Developer or higher.

ParametersraceIdrequiredlapNumberrequired

get_telemetry_race_summary

Get Telemetry Race Summary

Get race-level telemetry summary: max speed, fastest driver, average throttle/brake percentages, top aggression driver. Requires Developer or higher.

ParametersraceIdrequired

get_fantasy_pit_times

Get Fantasy Pit Times

Get the pit-stop time leaderboard for a session: stationary time (seconds stopped in the box) per stop, with driver code and team. Requires Developer or higher.

ParameterssessionIdrequired

get_fantasy_scores

Get Fantasy Scores

Get estimated F1 Fantasy points per driver for a completed race. Includes full scoring breakdown: race position points, qualifying points, Q2/Q3 bonuses, positions gained, fastest lap, beat-teammate bonuses, and DNF penalty. Requires Developer or higher.

ParametersraceIdrequired

Version history

5
  1. v0.4.4LatestOct 29, 2026
  2. v0.4.1Oct 21, 2026
  3. v0.3.4Oct 5, 2026
  4. v0.3.3Oct 2, 2026
  5. v0.3.1Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts