WHOOP MCP Server

Instructions

Implementation Reference

• src/tools/get-recent-cycles.ts:24-102 (handler)

  Main handler function 'getRecentCycles' that executes the tool logic. Fetches recent physiological cycles from WHOOP API, calculates date ranges, formats cycle data with strain, heart rate, and calorie information, and returns a summary with formatted results.

  export default async function getRecentCycles({ limit, days }: InferSchema<typeof schema>) {
    try {
      const client = WhoopAPIClient.getInstance();
      
      // Calculate date range if days specified
      let params: any = { limit };
      if (days) {
        const endDate = new Date();
        const startDate = new Date();
        startDate.setDate(startDate.getDate() - days);
        
        params.start = startDate.toISOString();
        params.end = endDate.toISOString();
      }
      
      const response = await client.getCycleCollection(params);
      
      // Format the cycles for better readability
      const formattedCycles = response.records.map(cycle => {
        const startDate = new Date(cycle.start);
        const endDate = cycle.end ? new Date(cycle.end) : null;
        
        return {
          id: cycle.id,
          date: startDate.toLocaleDateString(),
          start_time: startDate.toLocaleString(),
          end_time: endDate ? endDate.toLocaleString() : 'Ongoing',
          is_current: !cycle.end,
          duration_hours: endDate ? 
            ((endDate.getTime() - startDate.getTime()) / (1000 * 60 * 60)).toFixed(1) : 
            'Ongoing',
          score_state: cycle.score_state,
          ...(cycle.score && {
            strain: cycle.score.strain.toFixed(2),
            calories: `${(cycle.score.kilojoule / 4.184).toFixed(0)} kcal`, // Convert kJ to kcal
            kilojoules: cycle.score.kilojoule.toFixed(0),
            avg_heart_rate: `${cycle.score.average_heart_rate} bpm`,
            max_heart_rate: `${cycle.score.max_heart_rate} bpm`,
          }),
        };
      });
      
      const summary = {
        total_cycles: formattedCycles.length,
        date_range: {
          from: formattedCycles[formattedCycles.length - 1]?.date || 'N/A',
          to: formattedCycles[0]?.date || 'N/A',
        },
        ...(formattedCycles.some(c => c.score_state === 'SCORED') && {
          average_strain: (
            formattedCycles
              .filter(c => c.strain)
              .reduce((sum, c) => sum + parseFloat(c.strain!), 0) / 
            formattedCycles.filter(c => c.strain).length
          ).toFixed(2),
        }),
      };
      
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            summary,
            cycles: formattedCycles,
            has_more: !!response.next_token,
            next_token: response.next_token,
          }, null, 2),
        }],
      };
    } catch (error) {
      return {
        content: [{
          type: 'text',
          text: `Error: ${error instanceof Error ? error.message : 'Unknown error occurred'}`,
        }],
        isError: true,
      };
    }
  }

• src/tools/get-recent-cycles.ts:6-9 (schema)

  Zod schema defining input parameters: 'limit' (number 1-25, default 10) for number of cycles to retrieve, and 'days' (optional number 1-30) for date range filtering.

  export const schema = {
    limit: z.number().min(1).max(25).default(10).describe('Number of cycles to retrieve (max 25)'),
    days: z.number().min(1).max(30).optional().describe('Number of days to look back (optional, default gets most recent)'),
  };

• src/tools/get-recent-cycles.ts:12-21 (registration)

  Tool metadata registration including name 'get-recent-cycles', description, and annotations (title, readOnlyHint, destructiveHint, idempotentHint) for MCP tool registration.

  export const metadata: ToolMetadata = {
    name: 'get-recent-cycles',
    description: 'Get recent physiological cycles (days) from WHOOP, including strain and heart rate data',
    annotations: {
      title: 'Get Recent WHOOP Cycles',
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
    },
  };

• src/api/whoop-client.ts:96-113 (helper)

  WhoopAPIClient.getCycleCollection method used by the handler to fetch cycle data from WHOOP API. Constructs query parameters for pagination and date filtering.

  async getCycleCollection(params?: {
    limit?: number;
    start?: string;
    end?: string;
    nextToken?: string;
  }): Promise<PaginatedResponse<Cycle>> {
    const queryParams = new URLSearchParams();
    
    if (params?.limit) queryParams.append('limit', params.limit.toString());
    if (params?.start) queryParams.append('start', params.start);
    if (params?.end) queryParams.append('end', params.end);
    if (params?.nextToken) queryParams.append('nextToken', params.nextToken);
    
    const queryString = queryParams.toString();
    const endpoint = `/v2/cycle${queryString ? `?${queryString}` : ''}`;
    
    return this.request<PaginatedResponse<Cycle>>(endpoint);
  }

• src/api/types.ts:49-66 (helper)

  TypeScript type definitions for Cycle and CycleScore interfaces that define the structure of cycle data including strain, kilojoule, heart rate metrics, and score state.

  export interface CycleScore {
    strain: number;
    kilojoule: number;
    average_heart_rate: number;
    max_heart_rate: number;
  }
  
  export interface Cycle {
    id: number;
    user_id: number;
    created_at: string;
    updated_at: string;
    start: string;
    end?: string; // Optional - if not present, user is currently in this cycle
    timezone_offset: string;
    score_state: 'SCORED' | 'PENDING_SCORE' | 'UNSCORABLE';
    score?: CycleScore;
  }