Skip to main content

MCP Tools

The @wellpipe/whoop package includes 18 MCP (Model Context Protocol) tools that enable AI assistants to query WHOOP data. All tools are prefixed with whoop- to distinguish them from other providers.

Tool Categories​

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

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;  // e.g., "whoop-get-sleep-collection"
  description: string;
  inputSchema: z.ZodSchema;
  handler: (input: unknown) => Promise<ToolResult>;
}

Sleep Tools​

whoop-get-sleep-collection​

Fetch paginated sleep sessions with optional date filtering.

Input:

{
  start_date?: string;  // ISO 8601 format
  end_date?: string;    // ISO 8601 format
  limit?: number;       // Max 25 (default: 25)
}

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

whoop-get-sleep-by-id​

Get detailed information about a specific sleep session.

Input:

{
  sleep_id: string;  // UUID of the sleep activity (required)
}

Output: Single sleep session with full details.

whoop-get-recent-sleep​

Convenience tool to get sleep sessions from the last N days.

Input:

{
  days?: number;  // Days to look back (default: 7)
}

Output: Array of recent sleep sessions.

whoop-get-sleep-summary​

Get aggregated sleep metrics for a date range.

Input:

{
  start_date: string;  // ISO 8601 format (required)
  end_date: string;    // ISO 8601 format (required)
}

Output: Aggregated sleep stats including averages and stage breakdown.

Recovery Tools​

whoop-get-recovery-collection​

Fetch paginated recovery records with optional date filtering.

Input:

{
  start_date?: string;  // ISO 8601 format
  end_date?: string;    // ISO 8601 format
  limit?: number;       // Max 25 (default: 25)
}

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

whoop-get-recovery-by-cycle-id​

Get recovery data for a specific physiological cycle.

Input:

{
  cycle_id: number;  // The cycle ID (required)
}

Output: Single recovery record with all metrics.

whoop-get-recent-recovery​

Convenience tool to get recovery records from the last N days.

Input:

{
  days?: number;  // Days to look back (default: 7)
}

Output: Array of recent recovery records.

whoop-get-recovery-summary​

Get aggregated recovery metrics for a date range.

Input:

{
  start_date: string;  // ISO 8601 format (required)
  end_date: string;    // ISO 8601 format (required)
}

Output: Average recovery score, HRV trends, RHR stats.

Workout Tools​

whoop-get-workout-collection​

Fetch paginated workouts with optional date filtering.

Input:

{
  start_date?: string;  // ISO 8601 format
  end_date?: string;    // ISO 8601 format
  limit?: number;       // Max 25 (default: 25)
}

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

whoop-get-workout-by-id​

Get detailed information about a specific workout.

Input:

{
  workout_id: string;  // UUID of the workout (required)
}

Output: Single workout with full details.

whoop-get-recent-workouts​

Convenience tool to get workouts from the last N days.

Input:

{
  days?: number;  // Days to look back (default: 7)
}

Output: Array of recent workouts.

whoop-get-workout-summary​

Get aggregated workout statistics for a date range.

Input:

{
  start_date: string;  // ISO 8601 format (required)
  end_date: string;    // ISO 8601 format (required)
}

Output: Total workouts, total strain, average duration, sport breakdown.

Cycle Tools​

whoop-get-cycle-collection​

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

Input:

{
  start_date?: string;  // ISO 8601 format
  end_date?: string;    // ISO 8601 format
  limit?: number;       // Max 25 (default: 25)
}

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

whoop-get-cycle-by-id​

Get detailed information about a specific cycle.

Input:

{
  cycle_id: number;  // The cycle ID (required)
}

Output: Single cycle with full details.

whoop-get-recent-cycles​

Convenience tool to get cycles from the last N days.

Input:

{
  days?: number;  // Days to look back (default: 7)
}

Output: Array of recent cycles.

whoop-get-cycle-summary​

Get aggregated daily strain statistics for a date range.

Input:

{
  start_date: string;  // ISO 8601 format (required)
  end_date: string;    // ISO 8601 format (required)
}

Output: Average daily strain, total strain, energy expenditure.

Profile Tools​

whoop-get-user-profile​

Get user profile information.

Input: None

Output:

{
  user_id: string;
  email: string;
  first_name: string;
  last_name: string;
}

whoop-get-body-measurement​

Get body measurements.

Input: None

Output:

{
  height_meter: number;
  weight_kilogram: number;
  max_heart_rate: number;
}

Creating Custom Tools​

You can create additional tools using the existing client:

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

const customTool = {
  name: 'whoop-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);