Skip to main content

MCP Tools

The @wellpipe/whoop package includes 21 MCP (Model Context Protocol) tools that enable AI assistants to query WHOOP data.

Tool Categories​

CategoryToolsDescription
Sleep4Sleep sessions, scores, stages
Recovery4Recovery scores, HRV, metrics
Workout4Workouts, strain, activities
Cycle4Physiological cycles, daily strain
Profile2User info, body measurements
Auth3OAuth flow management

Using Tools​

In MCP Server​

import { createMcpServer } from '@wellpipe/whoop';

const server = createMcpServer(tokenProvider);

// The server exposes all tools via MCP protocol
server.listen();

Tool Definitions​

Each tool is defined with:

interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: z.ZodSchema;
  handler: (input: unknown) => Promise<ToolResult>;
}

Sleep Tools​

get-sleep-data​

Fetch sleep sessions for a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Array of sleep sessions with scores, stages, and metrics.

get-last-sleep​

Get the most recent sleep session.

Input: None

Output: Single sleep session with full details.

get-sleep-score​

Get sleep performance score for a specific date.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Sleep score and performance metrics.

get-sleep-stages​

Get detailed sleep stage breakdown.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Light, deep, REM, and awake durations.

Recovery Tools​

get-recovery-data​

Fetch recovery data for a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Array of recovery scores with HRV, RHR, SpO2.

get-last-recovery​

Get the most recent recovery score.

Input: None

Output: Single recovery record with all metrics.

get-hrv​

Get HRV (heart rate variability) for a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: HRV values with timestamps.

get-resting-heart-rate​

Get resting heart rate for a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: RHR values with timestamps.

Workout Tools​

get-workout-data​

Fetch workouts for a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Array of workouts with strain, duration, metrics.

get-last-workout​

Get the most recent workout.

Input: None

Output: Single workout with full details.

get-workout-strain​

Get strain scores for workouts in a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Strain values per workout.

get-workout-summary​

Get aggregated workout statistics.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Total workouts, total strain, average duration.

Cycle Tools​

get-cycle-data​

Fetch physiological cycles (wake-to-wake periods).

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Array of cycles with strain, calories, HR.

get-last-cycle​

Get the most recent cycle.

Input: None

Output: Single cycle with full details.

get-daily-strain​

Get daily strain values.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Strain scores per day.

get-strain-summary​

Get aggregated strain statistics.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Average, max, total strain for period.

Profile Tools​

get-user-profile​

Get user profile information.

Input: None

Output:

{
  userId: string;
  email: string;
  firstName: string;
  lastName: string;
}

get-body-measurement​

Get body measurements.

Input: None

Output:

{
  heightMeter: number;
  weightKilogram: number;
  maxHeartRate: number;
}

Authentication Tools​

These tools are used for CLI OAuth flow:

authenticate-whoop​

Start OAuth flow.

Input:

{
  port?: number;  // Callback port (default: 3000)
}

Output: Authorization URL to open in browser.

complete-whoop-auth​

Complete OAuth flow after browser authorization.

Input:

{
  port?: number;    // Must match authenticate-whoop port
  timeout?: number; // Seconds to wait (default: 300)
}

Output: Success status with token info.

check-auth-status​

Check current authentication status.

Input: None

Output: Token validity and expiration info.

Creating Custom Tools​

You can create additional tools using the existing client:

import { WhoopClient } from '@wellpipe/whoop';
import { z } from 'zod';

const customTool = {
  name: 'get-weekly-summary',
  description: 'Get a summary of the past week',
  inputSchema: z.object({}),
  handler: async (input: unknown, client: WhoopClient) => {
    const endDate = new Date().toISOString().split('T')[0];
    const startDate = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
      .toISOString()
      .split('T')[0];

    const [sleep, recovery, workouts] = await Promise.all([
      client.getSleep(startDate, endDate),
      client.getRecovery(startDate, endDate),
      client.getWorkouts(startDate, endDate),
    ]);

    return {
      period: { start: startDate, end: endDate },
      sleep: {
        sessions: sleep.length,
        avgScore: average(sleep.map(s => s.score).filter(Boolean)),
      },
      recovery: {
        days: recovery.length,
        avgScore: average(recovery.map(r => r.score).filter(Boolean)),
      },
      workouts: {
        count: workouts.length,
        totalStrain: sum(workouts.map(w => w.strain).filter(Boolean)),
      },
    };
  },
};

Tool Registration​

Tools are automatically registered when creating an MCP server:

import { createMcpServer, getAllTools } from '@wellpipe/whoop';

// Get all tool definitions
const tools = getAllTools();
console.log(`Registered ${tools.length} tools`);

// Or create server with all tools
const server = createMcpServer(tokenProvider);