WHOOP MCP Server

Instructions

Implementation Reference

• src/mcp-server.ts:485-495 (handler)

  MCP tool handler for 'whoop-get-authorization-url': calls WhoopApiClient.getAuthorizationUrl() and formats response as text content.
  case 'whoop-get-authorization-url': { const url = this.whoopClient.getAuthorizationUrl(); return { content: [ { type: 'text', text: `Authorization URL: ${url}`, }, ], }; }
• src/mcp-server.ts:240-248 (schema)

  Tool schema definition: name, description, and empty input schema (no parameters required).
  { name: 'whoop-get-authorization-url', description: 'Get the authorization URL for OAuth flow', inputSchema: { type: 'object', properties: {}, required: [], }, },
• src/mcp-server.ts:30-292 (registration)

  Registers the tool in the ListTools handler by including it in the tools array returned.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ // User tools { name: 'whoop-get-user-profile', description: 'Get basic user profile information (name, email) for the authenticated user', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'whoop-get-user-body-measurements', description: 'Get body measurements (height, weight, max heart rate) for the authenticated user', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'whoop-revoke-user-access', description: 'Revoke the access token granted by the user', inputSchema: { type: 'object', properties: {}, required: [], }, }, // Cycle tools { name: 'whoop-get-cycle-by-id', description: 'Get the cycle for the specified ID', inputSchema: { type: 'object', properties: { cycleId: { type: 'number', description: 'ID of the cycle to retrieve', }, }, required: ['cycleId'], }, }, { name: 'whoop-get-cycle-collection', description: 'Get all physiological cycles for a user, paginated', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Limit on the number of cycles returned (max 25)', }, start: { type: 'string', description: 'Return cycles that occurred after or during this time (ISO 8601)', }, end: { type: 'string', description: 'Return cycles that intersect this time or ended before this time (ISO 8601)', }, nextToken: { type: 'string', description: 'Next token from the previous response to get the next page', }, }, required: [], }, }, { name: 'whoop-get-sleep-for-cycle', description: 'Get sleep data for a specific cycle', inputSchema: { type: 'object', properties: { cycleId: { type: 'number', description: 'ID of the cycle to get sleep data for', }, }, required: ['cycleId'], }, }, // Recovery tools { name: 'whoop-get-recovery-collection', description: 'Get all recovery data for a user, paginated', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Limit on the number of recovery records returned (max 25)', }, start: { type: 'string', description: 'Return recovery records that occurred after or during this time (ISO 8601)', }, end: { type: 'string', description: 'Return recovery records that intersect this time or ended before this time (ISO 8601)', }, nextToken: { type: 'string', description: 'Next token from the previous response to get the next page', }, }, required: [], }, }, { name: 'whoop-get-recovery-for-cycle', description: 'Get recovery data for a specific cycle', inputSchema: { type: 'object', properties: { cycleId: { type: 'number', description: 'ID of the cycle to get recovery data for', }, }, required: ['cycleId'], }, }, // Sleep tools { name: 'whoop-get-sleep-by-id', description: 'Get the sleep record for the specified ID', inputSchema: { type: 'object', properties: { sleepId: { type: 'string', description: 'ID of the sleep record to retrieve', }, }, required: ['sleepId'], }, }, { name: 'whoop-get-sleep-collection', description: 'Get all sleep records for a user, paginated', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Limit on the number of sleep records returned (max 25)', }, start: { type: 'string', description: 'Return sleep records that occurred after or during this time (ISO 8601)', }, end: { type: 'string', description: 'Return sleep records that intersect this time or ended before this time (ISO 8601)', }, nextToken: { type: 'string', description: 'Next token from the previous response to get the next page', }, }, required: [], }, }, // Workout tools { name: 'whoop-get-workout-by-id', description: 'Get the workout record for the specified ID', inputSchema: { type: 'object', properties: { workoutId: { type: 'string', description: 'ID of the workout record to retrieve', }, }, required: ['workoutId'], }, }, { name: 'whoop-get-workout-collection', description: 'Get all workout records for a user, paginated', inputSchema: { type: 'object', properties: { limit: { type: 'number', description: 'Limit on the number of workout records returned (max 25)', }, start: { type: 'string', description: 'Return workout records that occurred after or during this time (ISO 8601)', }, end: { type: 'string', description: 'Return workout records that intersect this time or ended before this time (ISO 8601)', }, nextToken: { type: 'string', description: 'Next token from the previous response to get the next page', }, }, required: [], }, }, // OAuth tools { name: 'whoop-get-authorization-url', description: 'Get the authorization URL for OAuth flow', inputSchema: { type: 'object', properties: {}, required: [], }, }, { name: 'whoop-exchange-code-for-token', description: 'Exchange authorization code for access token', inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'Authorization code from OAuth callback', }, }, required: ['code'], }, }, { name: 'whoop-refresh-token', description: 'Refresh access token using refresh token', inputSchema: { type: 'object', properties: { refreshToken: { type: 'string', description: 'Refresh token to use for getting new access token', }, }, required: ['refreshToken'], }, }, { name: 'whoop-set-access-token', description: 'Set the access token for API calls', inputSchema: { type: 'object', properties: { accessToken: { type: 'string', description: 'Access token to use for API calls', }, }, required: ['accessToken'], }, }, ] as Tool[], };
• src/whoop-api.ts:140-153 (helper)

  Core implementation: builds OAuth authorization URL with client_id, redirect_uri, response_type='code', and specific scopes.
  getAuthorizationUrl(state?: string): string { const params = new URLSearchParams({ client_id: this.config.clientId, redirect_uri: this.config.redirectUri, response_type: 'code', scope: 'read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement' }); if (state) { params.append('state', state); } return `https://api.prod.whoop.com/oauth/oauth2/auth?${params.toString()}`; }