@racehooks/mcp
Official# @racehooks/mcp
MCP server for [RaceHooks](https://racehooks.io) — gives AI assistants (Claude, Cursor, Windsurf) direct access to RaceHooks predictive models and analytics for motorsport — race intelligence delivered to your endpoint.
[](https://www.npmjs.com/package/@racehooks/mcp)
[](LICENSE)
> 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](https://racehooks.io) 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**
| 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: each model's id, label, feed and status. | — | 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](https://racehooks.io/docs/feeds)
- `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](https://racehooks.io).
Use of RaceHooks through this MCP server is subject to the [RaceHooks Terms of Service](https://racehooks.io/legal/terms) and [Privacy Policy](https://racehooks.io/legal/privacy). 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.io
export 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
- [RaceHooks console](https://racehooks.io/console) — sign up and manage your account
- [RaceHooks API documentation](https://racehooks.io/docs)
- [Webhook API reference](https://racehooks.io/docs/webhooks)
- [Feed catalog](https://racehooks.io/docs/feeds)
- [GitHub](https://github.com/racehooks/racehooks-mcp)
- [npm](https://www.npmjs.com/package/@racehooks/mcp)
- [Smithery listing](https://smithery.ai/server/racehooks-mcp)
- [MCP specification](https://modelcontextprotocol.io)
- [Terms of Service](https://racehooks.io/legal/terms)
- [Privacy Policy](https://racehooks.io/legal/privacy)
TDQS
Scored across 58 tools
Core resources such as webhooks, drivers, races, and usage are mostly distinct, but the telemetry/analytics area has several overlapping tools: get_telemetry_laps, get_race_telemetry_laps, get_telemetry_driver_laps, and get_telemetry_lap_comparison are easy to confuse. Similarly, get_race_summary, get_telemetry_race_summary, get_session_analytics, and get_race_insights require careful reading to select correctly.
Tool names consistently use snake_case with a verb-first pattern such as list_, get_, create_, update_, delete_, prepare_, and rotate_. Despite the large surface, there is no mixing of camelCase or vague standalone names.
With 58 tools, the surface is far beyond a well-scoped set and includes many plan-gated variants and overlapping telemetry/analytics endpoints. This volume creates a large selection burden even though the underlying domain is broad.
Coverage is broad and lifecycle-oriented: webhook CRUD, testing, logs, secrets, rotation, usage, billing, replays, F1 data, telemetry, analytics, live sessions, and fantasy outputs are all represented. Minor gaps remain around account/subscription management and webhook delivery retry/resend operations.