Domestique

A TypeScript MCP (Model Context Protocol) server that integrates with Intervals.icu, Whoop, and TrainerRoad to provide unified access to fitness data across all activities and sports.

Features

• Query completed workouts from Intervals.icu

• Access recovery metrics (HRV, sleep, recovery score) from Whoop

• View planned workouts from TrainerRoad and Intervals.icu calendars

• Analyze fitness trends (CTL/ATL/TSB)

• Cross-platform activity matching

Available Tools

Current/Recent Data

• get_todays_recovery - Today's Whoop recovery, sleep, and HRV data

• get_recent_workouts - Completed workouts from Intervals.icu with matched Whoop strain data. Returns expanded metrics including speed, cadence, efficiency, power data, and per-activity fitness snapshot

• get_recent_strain - Whoop strain scores and activities for the specified number of days

• get_todays_planned_workouts - Today's scheduled workouts from both TrainerRoad and Intervals.icu calendars

• get_athlete_profile - Athlete profile from Intervals.icu including power zones, heart rate zones, pace zones, and current threshold values (FTP, LTHR, max HR, W', Pmax) for each configured sport

Historical/Trends

• get_workout_history - Historical workouts with flexible date ranges. Supports ISO dates or natural language (e.g., "30 days ago")

• get_recovery_trends - HRV, sleep, and recovery patterns over time with summary statistics

• get_fitness_progression - CTL/ATL/TSB (fitness/fatigue/form) trends from Intervals.icu with summary statistics

• get_power_curve - Power curve showing best power outputs at various durations (5s, 1min, 5min, 20min, 60min, etc.). Essential for identifying athlete strengths, tracking FTP progression, and setting appropriate workout intensities

• get_pace_curve - Pace curve showing best running paces at various durations. Useful for setting appropriate run paces for workouts, tracking running fitness progression, and identifying race potential at various distances

• get_training_load_trends - Training load trends including CTL (fitness), ATL (fatigue), TSB (form), ramp rate, and Acute:Chronic Workload Ratio (ACWR) for injury risk assessment. ACWR between 0.8-1.3 is optimal; above 1.5 indicates high injury risk

Planning

• get_upcoming_workouts - Planned workouts for a future date range from both TrainerRoad and Intervals.icu calendars

• get_planned_workout_details - Detailed information about a specific planned workout by ID or date

Setup

Prerequisites

• Node.js 20+

• Intervals.icu account with API key

• Whoop account with OAuth credentials

• TrainerRoad account with calendar feed URL

Environment Variables

Copy .env.example to .env and fill in your credentials:

Required variables:

• MCP_AUTH_TOKEN - Secret token for MCP authentication

For Intervals.icu integration:

• INTERVALS_API_KEY - Your Intervals.icu API key

• INTERVALS_ATHLETE_ID - Your Intervals.icu athlete ID

For Whoop integration:

• WHOOP_CLIENT_ID

• WHOOP_CLIENT_SECRET

• WHOOP_REDIRECT_URI - Defaults to http://localhost:3000/callback

• REDIS_URL - Required for token storage (e.g., redis://localhost:6379)

For TrainerRoad integration:

• TRAINERROAD_CALENDAR_URL - Private iCal feed URL

Whoop OAuth Setup

Whoop uses OAuth 2.0, which requires a one-time authorization flow to obtain refresh tokens. The refresh tokens are single-use, so each time the server refreshes the access token, it receives a new refresh token that gets stored in Redis.

First-time setup:

1. Create a Whoop developer app at https://developer.whoop.com to get your WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET

2. Make sure Redis is running and REDIS_URL is set in your .env

3. Start the Docker environment:

   docker compose up -d

4. Run the OAuth setup script:

   docker compose exec domestique npm run whoop:auth

5. The script will display an authorization URL. Open it in your browser and log in to Whoop

6. After authorizing, you'll be redirected to a URL like:

   http://localhost:3000/callback?code=AUTHORIZATION_CODE

7. Copy the code parameter value and paste it into the script

8. The script exchanges the code for tokens and stores them in Redis. You're done!

The server will automatically refresh tokens as needed and store new refresh tokens in Redis.

Common Commands

Docker Commands

All commands should be run in the Docker container:

Testing with MCP Inspector

The MCP Inspector is a useful tool for testing and debugging your MCP server:

The inspector will open a web interface where you can:

• Browse available tools

• Test tool calls with different parameters

• View request/response payloads

• Debug connection issues

Local Development

Using Docker Compose (recommended)

Using Node.js directly

Deployment to Fly.io

1. Install Fly CLI and Login

2. Deploy Redis

Redis is required for Whoop token storage. Deploy it first:

3. Deploy Domestique

4. Set Up Whoop Tokens (if using Whoop)

After deploying, run the OAuth setup to get initial Whoop tokens:

Follow the prompts to authorize with Whoop and store the tokens in Redis.

Connecting to Claude

Add this MCP server to your Claude configuration. The server supports two authentication methods:

Method 1: Authorization Header (Recommended)

Method 2: Query Parameter (For Claude UI)

If you're using Claude's custom connector UI (which doesn't support custom headers), use the query parameter method:

Note: Replace YOUR_SECRET_TOKEN with your actual MCP_AUTH_TOKEN value.

Example Queries

Once connected, you can ask Claude:

• "How did my workout go today?"

• "What's my recovery like this morning?"

• "Show me my fitness trends for the last month"

• "What workouts do I have planned this week?"

• "How has my HRV trended compared to my training load?"