whoop-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@whoop-mcp What was my recovery score this morning?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WHOOP MCP Server
A Model Context Protocol (MCP) server for the WHOOP API. Gives any MCP-compatible client (Claude Code, Claude Desktop, etc.) read access to your WHOOP biometric data -- recovery, sleep, strain, workouts, and more.
Features
Full coverage of the WHOOP Developer API v2
OAuth 2.0 authentication with token refresh
Sleep analysis (stages, efficiency, respiratory rate)
Recovery scores (HRV, resting heart rate, SpO2, skin temp)
Strain and cycle data
Workout tracking with heart rate zones
Pagination support for all collection endpoints
TypeScript with full type definitions
Related MCP server: whoop-mcp-server
Prerequisites
Node.js 18+
WHOOP account with an active membership
WHOOP Developer App -- register at developer.whoop.com
Quick Start
1. Clone and install
git clone https://github.com/AaronRoeF/whoop-mcp-server.git
cd whoop-mcp-server
npm install2. Register a WHOOP Developer App
Go to developer.whoop.com
Create a new application
Set the redirect URI to
http://localhost:3000/callbackNote your Client ID and Client Secret
3. Configure environment
cp env.example .envEdit .env with your credentials:
WHOOP_CLIENT_ID=your_client_id
WHOOP_CLIENT_SECRET=your_client_secret
WHOOP_REDIRECT_URI=http://localhost:3000/callback4. Build
npm run build5. Authenticate with WHOOP
npm run authThis starts a local web server, opens your browser, and walks you through the WHOOP OAuth flow. On success, tokens are saved to whoop-tokens.json (gitignored).
6. Add to Claude Code
Add to your ~/.claude.json:
{
"mcpServers": {
"whoop": {
"command": "node",
"args": ["/absolute/path/to/whoop-mcp-server/start-mcp-server.js"],
"cwd": "/absolute/path/to/whoop-mcp-server"
}
}
}Or for Claude Desktop, add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"whoop": {
"command": "node",
"args": ["/absolute/path/to/whoop-mcp-server/start-mcp-server.js"],
"cwd": "/absolute/path/to/whoop-mcp-server"
}
}
}The start-mcp-server.js script automatically loads saved tokens, refreshes them if expired, and starts the MCP server.
Available Tools
User
Tool | Description |
| Get profile info (name, email) for the authenticated user |
| Get height, weight, and max heart rate |
| Revoke the current access token |
Cycles
Tool | Description |
| Get a specific physiological cycle by ID |
| Get all cycles (paginated, with date filters) |
| Get sleep data associated with a specific cycle |
Recovery
Tool | Description |
| Get recovery records (paginated, with date filters) |
| Get recovery data for a specific cycle |
Sleep
Tool | Description |
| Get a specific sleep record by ID |
| Get sleep records (paginated, with date filters) |
Workouts
Tool | Description |
| Get a specific workout record by ID |
| Get workout records (paginated, with date filters) |
OAuth
Tool | Description |
| Get the OAuth authorization URL |
| Exchange an authorization code for an access token |
| Refresh the access token using a refresh token |
| Manually set the access token for API calls |
OAuth Setup Details
WHOOP uses OAuth 2.0. The flow works like this:
Register your app at developer.whoop.com and set the redirect URI to
http://localhost:3000/callbackRun
npm run auth-- this starts a local server and opens the WHOOP authorization pageAuthorize the app -- log in to your WHOOP account and grant access
Tokens are saved automatically to
whoop-tokens.json
Access tokens expire after ~1 hour. The start-mcp-server.js script handles automatic refresh on startup. If refresh fails, re-run npm run auth.
Required OAuth Scopes
The server requests these scopes:
read:recoveryread:cyclesread:workoutread:sleepread:profileread:body_measurement
Pagination
Collection endpoints accept these optional parameters:
Parameter | Type | Description |
| number | Max records to return (up to 25) |
| string | Return records after this time (ISO 8601) |
| string | Return records before this time (ISO 8601) |
| string | Pagination token from previous response |
Project Structure
src/
index.ts Entry point
mcp-server.ts MCP server with tool definitions and handlers
whoop-api.ts WHOOP API client (OAuth + all endpoints)
types.ts TypeScript type definitions
auth-app.js Local OAuth web server for initial authentication
start-mcp-server.js MCP server launcher with auto token refresh
env.example Environment variable templateDevelopment
npm run build # Compile TypeScript
npm start # Run the compiled server
npm run dev # Run with tsx (hot reload)
npm run auth # Run the OAuth authentication flow
npm run start-mcp # Start MCP server with saved tokensLicense
MIT -- see LICENSE for details.
Acknowledgments
WHOOP Developer Platform for the API
Model Context Protocol for the MCP specification
Available Tools
16 toolswhoop-exchange-code-for-tokenB
Exchange authorization code for access token
Inputs: code (required).
whoop-get-authorization-urlB
Get the authorization URL for OAuth flow
Inputs: no named parameters.
whoop-get-cycle-by-idC
Get the cycle for the specified ID
Inputs: cycleId (required).
whoop-get-cycle-collectionA
Get all physiological cycles for a user, paginated
Inputs: limit, start, end, nextToken.
whoop-get-recovery-collectionB
Get all recovery data for a user, paginated
Inputs: limit, start, end, nextToken.
whoop-get-recovery-for-cycleB
Get recovery data for a specific cycle
Inputs: cycleId (required).
whoop-get-sleep-by-idC
Get the sleep record for the specified ID
Inputs: sleepId (required).
whoop-get-sleep-collectionB
Get all sleep records for a user, paginated
Inputs: limit, start, end, nextToken.
whoop-get-sleep-for-cycleB
Get sleep data for a specific cycle
Inputs: cycleId (required).
whoop-get-user-body-measurementsA
Get body measurements (height, weight, max heart rate) for the authenticated user
Inputs: no named parameters.
whoop-get-user-profileA
Get basic user profile information (name, email) for the authenticated user
Inputs: no named parameters.
whoop-get-workout-by-idB
Get the workout record for the specified ID
Inputs: workoutId (required).
whoop-get-workout-collectionA
Get all workout records for a user, paginated
Inputs: limit, start, end, nextToken.
whoop-refresh-tokenB
Refresh access token using refresh token
Inputs: refreshToken (required).
whoop-revoke-user-accessB
Revoke the access token granted by the user
Inputs: no named parameters.
whoop-set-access-tokenC
Set the access token for API calls
Inputs: accessToken (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct resource or action: OAuth tokens, user profile, and various physiological data (cycles, recovery, sleep, workouts). There is no ambiguity between tools like get-cycle-collection and get-cycle-by-id, as they serve different purposes (list vs. single item).
All tools follow a consistent verb_noun pattern starting with 'whoop-', e.g., whoop-get-cycle-by-id, whoop-get-cycle-collection, whoop-refresh-token. Verbs are clear (get, exchange, refresh, revoke, set) and nouns are specific, making the naming predictable and easy to navigate.
With 16 tools, the set covers the core WHOOP API surface: OAuth authentication, user information, and paginated retrieval of physiological data. The number is appropriate for the domain, providing comprehensive access without being excessive.
The tool set covers all essential operations for the WHOOP API: OAuth flow, user profile, body measurements, and retrieval of cycles, recovery, sleep, and workouts (both collections and by-id or by-cycle). No obvious gaps are present for a read-focused API with token management.
Related MCP Connectors
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Unofficial, not affiliated with Woop. Read-only Open Finance MCP by MCP.AI.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local MCP server providing read-only access to WHOOP fitness data via direct OAuth, with a local SQLite cache for offline queries.97 PyPIMIT
- AlicenseAqualityDmaintenanceMCP server that enables AI assistants to access Whoop health data including recovery, sleep, workouts, and daily strain for personalized health recommendations.7MIT
- AlicenseAqualityCmaintenanceA local-first, read-only MCP server that provides compact recovery, sleep, strain, HRV, heart-rate, workout, and body-measurement data from WHOOP without sending credentials to a third party.587 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server providing full read/write access to Whoop wearable data, including recovery, sleep, workouts, journal, and more, via Whoop's private iOS API.MIT