RaceHooks

@racehooks/mcp

MCP server for RaceHooks — gives AI assistants (Claude, Cursor, Windsurf) direct access to RaceHooks motorsport analytics and data.

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 Formula 1.

Tools

Live

Tool	What it does	Key args	Plan
get_live_session	Current 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_events	Race weekends with session schedules and status.	year, upcoming, limit	All

Post-race insights

Tool	What it does	Key args	Plan
list_insight_races	Races with a completed post-race analytics bundle.	season	All
get_race_insights	Per-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.	raceId	All (Free gets tyre state only; strategic predictions need Developer+)
get_model_meta	Public model manifest: what each model predicts, model family, calibration tier, last trained.	—	All
get_session_analytics	Per-lap analytics snapshot for a session.	sessionId	Developer+
get_race_summary	Post-race analytics status and aggregate telemetry metrics.	raceId	All (aggregates need Developer+)

Races

Tool	What it does	Key args	Plan
get_race	Race details with results and qualifying grid.	raceId	All (timing fields need Developer+)
get_race_qualifying	Qualifying results.	raceId	All (Q1/Q2/Q3 times need Developer+)
get_race_pitstops	Pit stop records (driver, stop, lap, duration).	raceId	All
get_race_tyres	Tyre stints (compound, lap range, tyre age).	raceId	All
get_race_weather	Lap-by-lap weather.	raceId	All
get_race_laps	Per-lap times and positions.	raceId, driverId	Developer+
get_event_pace	Practice and qualifying pace summary per driver.	eventId	Developer+

History (drivers, constructors, circuits, seasons)

Tool	What it does	Key args	Plan
list_drivers	Drivers, searchable.	search, nationality, active, limit, offset	All (page size 25 on Free, 100 paid)
get_driver	Driver profile with career stats.	driverId	All
get_driver_results	Race-by-race results for a driver.	driverId, season	All (timing fields need Developer+)
get_driver_standings	Championship standings history for a driver.	driverId, season	All
list_constructors	Constructors.	lineage, active, limit, offset	All
get_constructor	Constructor profile with lineage history.	constructorId	All
get_constructor_results	Race-by-race results for a constructor.	constructorId, season	All (timing fields need Developer+)
get_constructor_standings	Championship standings history for a constructor.	constructorId, season	All
list_circuits	Circuits with location.	country, limit, offset	All
get_circuit	Circuit details and analytics.	circuitId	All
list_seasons	Seasons with race counts.	—	All
get_season_standings	Final driver and constructor standings for a season.	year	All
get_season_races	Races in a season.	year	All

Telemetry

Tool	What it does	Key args	Plan
get_telemetry_laps	Per-lap telemetry aggregates (speed, throttle, brake, DRS, aggression).	raceId, driverId, lapNumber	Developer+
get_telemetry_driver_laps	Per-lap telemetry for one driver.	raceId, driverId	Developer+
get_telemetry_lap_comparison	Every driver's telemetry for one lap.	raceId, lapNumber	Developer+
get_telemetry_race_summary	Race-level telemetry summary.	raceId	Developer+
get_race_telemetry_laps	Per-lap telemetry metrics from the race data API.	raceId, driverId	Developer+
get_race_telemetry_stints	Per-stint telemetry and degradation slopes.	raceId, driverId	Custom
get_race_telemetry_aggression	Driver aggression index rankings.	raceId	Custom

Fantasy

Tool	What it does	Key args	Plan
get_fantasy_scores	Estimated F1 Fantasy points per driver with full breakdown.	raceId	Developer+
get_fantasy_pit_times	Pit-stop time leaderboard (stationary time) for a session.	sessionId	Developer+

Account, usage and webhooks

Tool	What it does	Key args	Plan
list_feeds	Feed catalog with the plan each feed requires.	limit	All
list_webhooks	Webhook subscriptions on the account.	limit, offset	All
get_webhook	One webhook by ID.	webhookId	All
create_webhook	Create a webhook; returns the signing secret once.	feedId, webhookUrl, webhookMethod, filters	All
update_webhook	Change URL, method, or filters; pause/resume with active.	webhookId, webhookUrl, filters, active	All
delete_webhook	Delete a webhook.	webhookId	All
test_webhook	Send a test payload now.	webhookId	All
get_webhook_logs	Recent delivery logs.	webhookId, limit	All
get_webhook_secret	Current signing secret.	webhookId	All
rotate_webhook_secret	Rotate the signing secret (old one stops working immediately).	webhookId	All
get_subscription	Tier, plan limits, and usage snapshot.	—	All
get_usage	Deliveries and failures this period, remaining bucket.	—	All
get_usage_by_feed	Deliveries by feed this period.	—	All
get_usage_latency	Delivery latency percentiles by feed.	—	All
get_usage_hourly	Hourly deliveries for the last 24 hours.	—	All
get_usage_history	Delivery history across past periods.	—	All
get_billing_plan	Current plan, limits, usage this period, and billing period dates.	—	All

Session replay

Tool	What it does	Key args	Plan
list_replay_sessions	Recorded sessions that can be replayed.	year, type, limit, offset	All (Free and Developer: current season only)
get_demo_session	The curated demo session to replay.	—	All
get_replay_quota	Replay delivery quota (distinct-session slots) for your tier.	—	All
prepare_replay	Prepare a session's playback artifact.	sessionId	All
get_replay_status	Whether a session's playback artifact is ready.	sessionId	All

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

npm install -g @racehooks/mcp

Or run directly with npx:

npx @racehooks/mcp

Get your API credentials at racehooks.io.

Configuration

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

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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.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:

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:

{
  "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):

{
  "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:

{
  "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

• RaceHooks console — sign up and manage your account
• RaceHooks API documentation
• Webhook API reference
• Feed catalog
• GitHub
• npm
• Smithery listing
• MCP specification