WHOOP MCP Server
A Model Context Protocol (MCP) server that provides access to all WHOOP API endpoints. This server allows you to integrate WHOOP fitness and health data into your applications through the MCP standard.
Features
- Complete WHOOP API Coverage: Access to all WHOOP v2 API endpoints
- OAuth 2.0 Authentication: Secure authentication flow
- User Data: Profile information and body measurements
- Cycles: Physiological cycle data with strain and heart rate metrics
- Recovery: Recovery scores, HRV, and resting heart rate data
- Sleep: Detailed sleep analysis including stages and performance metrics
- Workouts: Exercise data with strain, heart rate zones, and activity metrics
- Pagination Support: Handle large datasets with pagination
- TypeScript: Full type safety and IntelliSense support
Prerequisites
- Node.js 18+
- WHOOP Developer Account
- WHOOP API credentials
Setup
1. Install Dependencies
2. WHOOP API Setup
- Go to the WHOOP Developer Platform
- Create a new application
- Note your
Client ID
andClient Secret
- Set your redirect URI (e.g.,
http://localhost:3000/callback
)
3. Environment Configuration
Copy the example environment file and configure your WHOOP credentials:
Edit .env
with your WHOOP API credentials:
4. Build and Run
Authentication Flow
The MCP server supports OAuth 2.0 authentication with WHOOP. Here's how to authenticate:
- Get Authorization URL: Use the
whoop-get-authorization-url
tool to get the OAuth URL - User Authorization: Direct users to the authorization URL
- Copy Authorization Code: When WHOOP redirects you back, copy the authorization code from the URL
- Share Code with Claude: IMPORTANT - You must copy and paste the authorization code directly to Claude in the chat
- Exchange Code: Claude will use the
whoop-exchange-code-for-token
tool with the authorization code - Set Access Token: Claude will use the
whoop-set-access-token
tool to set the access token for API calls
⚠️ Important Note About Authorization Codes
When you complete the WHOOP authorization in your browser, you'll be redirected to a URL that contains an authorization code. You must copy this code and paste it directly into your chat with Claude. The code will look something like this in the URL:
Copy the code
parameter value (e.g., ABC123XYZ789
) and paste it in your chat with Claude. Claude will then use this code to exchange it for an access token and set up the connection to your WHOOP data.
Available Tools
User Tools
whoop-get-user-profile
- Get basic user profile informationwhoop-get-user-body-measurements
- Get body measurements (height, weight, max heart rate)whoop-revoke-user-access
- Revoke user access token
Cycle Tools
whoop-get-cycle-by-id
- Get specific cycle data by IDwhoop-get-cycle-collection
- Get paginated list of cycleswhoop-get-sleep-for-cycle
- Get sleep data for a specific cycle
Recovery Tools
whoop-get-recovery-collection
- Get paginated recovery datawhoop-get-recovery-for-cycle
- Get recovery data for a specific cycle
Sleep Tools
whoop-get-sleep-by-id
- Get specific sleep record by IDwhoop-get-sleep-collection
- Get paginated sleep records
Workout Tools
whoop-get-workout-by-id
- Get specific workout record by IDwhoop-get-workout-collection
- Get paginated workout records
OAuth Tools
whoop-get-authorization-url
- Get OAuth authorization URLwhoop-exchange-code-for-token
- Exchange authorization code for access tokenwhoop-refresh-token
- Refresh access tokenwhoop-set-access-token
- Set access token for API calls
Usage Examples
Getting User Profile
Getting Recent Cycles
Getting Sleep Data
Getting Workout Data
Data Types
The server provides comprehensive TypeScript types for all WHOOP API responses:
- User Data: Profile information, body measurements
- Cycles: Strain scores, heart rate data, kilojoule expenditure
- Recovery: Recovery scores, HRV, resting heart rate, SpO2, skin temperature
- Sleep: Sleep stages, performance metrics, respiratory rate, efficiency
- Workouts: Activity strain, heart rate zones, distance, altitude data
Pagination
Most collection endpoints support pagination with the following parameters:
limit
: Number of records to return (max 25)start
: Start time filter (ISO 8601)end
: End time filter (ISO 8601)nextToken
: Token for next page
Error Handling
The MCP server includes comprehensive error handling:
- Invalid credentials
- Rate limiting
- Network errors
- Invalid parameters
- Missing required fields
Development
Project Structure
Available Scripts
npm run build
- Build the TypeScript projectnpm start
- Run the built servernpm run dev
- Run in development mode with hot reloadnpm run watch
- Watch for changes and rebuild
Adding New Endpoints
To add new WHOOP API endpoints:
- Add the endpoint method to
WhoopApiClient
inwhoop-api.ts
- Add corresponding types to
types.ts
- Add the tool definition and handler to
mcp-server.ts
WHOOP API Documentation
For detailed information about the WHOOP API, visit:
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
- Check the WHOOP API documentation
- Review the error messages from the MCP server
- Ensure your OAuth credentials are correctly configured
- Verify your access token is valid and not expired
Migration Notice
IMPORTANT: WHOOP v2 API is now available and migration is required by October 1, 2025. The current v1 API and webhooks will be removed after this date. This MCP server uses the v2 API.
This server cannot be installed
Enables access to WHOOP fitness and health data through all WHOOP v2 API endpoints. Supports OAuth 2.0 authentication and provides comprehensive access to user profiles, physiological cycles, recovery metrics, sleep analysis, and workout data.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that provides language models with access to personal Whoop fitness data, allowing queries for cycles, recovery, strain, and workout information from the Whoop API.Last updated -10Python
- -securityAlicense-qualityA server that connects to the Health Planet API to fetch and provide weight measurement data through any MCP-compatible client, allowing for retrieval and analysis of personal weight records.Last updated -TypeScriptMIT License
- -securityAlicense-qualityA comprehensive AI-powered fitness tracking application that enables AI tools to interact intelligently with user fitness data, providing personalized workout plans, nutrition tracking, and progress analysis through natural language.Last updated -1TypeScriptMIT License
- -securityAlicense-qualityA secure server that allows Claude Desktop application to access and process Whoop fitness data locally, using OAuth2 authentication to protect user privacy.Last updated -1JavaScriptMIT License