The WHOOP MCP Server gives MCP-compatible AI assistants access to personal WHOOP health and fitness data for recovery-aware planning and workload management. Key capabilities include:
Wellbeing Snapshot: Fetch a daily summary of recovery score, sleep data, cycle strain, workouts, and a workload recommendation for any given date.
Sleep Summary: Get detailed sleep metrics including sleep stages, sleep performance, HRV, resting heart rate, recovery score, and personalized recommendations.
Training Load Trend: Compare short-window (3–14 days) vs. long-window (7–56 days) trends across sleep, recovery, HRV, resting heart rate, and day strain.
Baseline Profile: Compute personal baseline ranges over a historical window (14–90 days) for sleep, recovery, HRV, resting heart rate, and day strain.
Change Alerts: Identify meaningful changes versus yesterday and your historical baseline, such as sleep drops, recovery dips, HRV dips, and resting heart rate spikes.
Workload Guard: Evaluate a proposed workload against current recovery signals and receive a safer daily scope suggestion when signals are weak.
Authentication is handled securely via OAuth 2.0 with local token caching and automatic refresh.
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 Server show me my latest recovery score and sleep summary"
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 is a TypeScript Model Context Protocol (MCP) server that gives MCP-compatible assistants access to personal WHOOP recovery, sleep, strain, and workout data.
The server runs locally over stdio. It authenticates with WHOOP through OAuth 2.0, stores reusable tokens on disk, refreshes tokens when needed, and exposes structured tools that assistants can use for workload planning and recovery-aware context.
Daily WHOOP recovery, sleep, cycle strain, and workout snapshots
Sleep-stage and sleep-performance summaries
Recovery score, HRV, resting heart rate, SpO2, and skin temperature summaries
Short-window versus long-window trend analysis
Historical baseline profiles
Change alerts versus yesterday and personal baseline
Workload guardrails based on recovery signals
Local OAuth token cache with refresh-token support
Related MCP server: Whoop MCP Server
Node.js 20 or newer
npm
A WHOOP account
A WHOOP Developer Dashboard app
Create the WHOOP app at:
https://developer-dashboard.whoop.comThe app must have a redirect URI registered. The default used by this project is:
whoop://mcp/callbackInstall dependencies:
npm installRun the setup wizard:
npm run setupThe wizard asks for:
WHOOP Client ID
WHOOP Client Secret
Redirect URI
Token cache folder
OAuth scopes
It then opens the WHOOP authorization page in your browser, exchanges the authorization code for tokens, writes the token cache, and offers to create a local .env file.
Build the MCP server:
npm run buildWHOOP uses OAuth 2.0 Authorization Code flow for API access. This project does not collect or store your WHOOP username or password.
The setup wizard stores API tokens in:
.whoop-tokens/tokens.jsonBy default it also offers to write local MCP settings to:
.envBoth .env and .whoop-tokens/ are ignored by git.
The default OAuth scopes are:
read:profile read:body_measurement read:recovery read:cycles read:sleep read:workout offlineThe offline scope is required for refresh-token support. Without it, the server may require a new browser login when the access token expires.
WHOOP supports redirect URLs such as https://... and custom schemes such as whoop://....
With the default whoop://mcp/callback redirect, the setup wizard asks you to paste the final redirected URL from the browser after approving access. If your WHOOP app is configured with a loopback redirect such as http://127.0.0.1:8787/callback, the wizard can capture the callback automatically with a temporary local HTTP server.
Tool | Description |
| Returns recovery, sleep, cycle strain, workouts, and a workload recommendation for a date. |
| Returns sleep-stage, sleep-performance, recovery, HRV, and resting-heart-rate context. |
| Compares short-window and long-window trends for sleep, recovery, HRV, resting heart rate, and day strain. |
| Computes baseline ranges over a historical window. |
| Highlights meaningful changes versus yesterday and baseline. |
| Evaluates a proposed workload against current recovery signals. |
Resource | Description |
| Today's WHOOP wellbeing snapshot as JSON. |
Prompt | Description |
| Guidance for using WHOOP data during workload planning without treating it as medical advice. |
The setup wizard can create .env automatically. You can also create it manually:
Copy-Item .env.example .envSupported environment variables:
Variable | Required | Description |
| Yes | OAuth Client ID from the WHOOP Developer Dashboard. |
| Yes | OAuth Client Secret from the WHOOP Developer Dashboard. |
| Yes | Registered OAuth redirect URI. Defaults to |
| Yes | Directory used to read and write WHOOP OAuth tokens. Defaults to |
| No | Space- or comma-separated OAuth scopes. Defaults to the scopes listed above. |
Use an absolute WHOOP_TOKEN_DIR when configuring an MCP client. MCP clients often start servers from a different working directory, and an absolute path avoids token-cache lookup problems.
Validate the project:
npm run typecheck
npm run buildStart the MCP server:
npm run startThe server communicates over stdio, so it will appear idle in a normal terminal until an MCP client connects.
Example Codex MCP configuration:
[mcp_servers.whoop]
command = "node"
args = ["C:\\path\\to\\whoop-mcp-server\\dist\\index.js"]
[mcp_servers.whoop.env]
WHOOP_CLIENT_ID = "your-client-id"
WHOOP_CLIENT_SECRET = "your-client-secret"
WHOOP_REDIRECT_URI = "whoop://mcp/callback"
WHOOP_TOKEN_DIR = "C:\\path\\to\\whoop-mcp-server\\.whoop-tokens"Restart Codex after updating the configuration.
Example Claude Desktop MCP configuration:
{
"mcpServers": {
"whoop": {
"command": "node",
"args": ["C:\\path\\to\\whoop-mcp-server\\dist\\index.js"],
"env": {
"WHOOP_CLIENT_ID": "your-client-id",
"WHOOP_CLIENT_SECRET": "your-client-secret",
"WHOOP_REDIRECT_URI": "whoop://mcp/callback",
"WHOOP_TOKEN_DIR": "C:\\path\\to\\whoop-mcp-server\\.whoop-tokens"
}
}
}
}Restart Claude Desktop after updating the configuration.
If setup fails:
Confirm the Client ID and Client Secret are copied from the WHOOP Developer Dashboard.
Confirm the redirect URI entered in the terminal exactly matches a redirect URI registered on the WHOOP app.
Confirm the app has access to the requested scopes.
Delete .whoop-tokens/ and run npm run setup again if tokens are stale.
If the MCP client cannot fetch WHOOP data:
Confirm npm run build completed successfully.
Confirm dist/index.js exists.
Use an absolute WHOOP_TOKEN_DIR in the MCP client configuration.
Include WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET in the MCP client environment so token refresh can work.
Restart the MCP client after changing configuration.
If token refresh fails:
Confirm WHOOP_SCOPES includes offline.
Run npm run setup again to create a fresh token cache.
Avoid running multiple server instances against the same token cache at the same time. WHOOP refresh tokens can rotate, and concurrent refreshes may invalidate one instance's cached token.
Do not commit .env or .whoop-tokens/.
Treat WHOOP data as private health-related information.
Keep the WHOOP Client Secret local to trusted machines.
Revoke the WHOOP app or delete the token cache if a machine is lost or no longer trusted.
npm run dev
npm run setup
npm run typecheck
npm run buildCompute personal baseline ranges over a historical window for sleep, recovery, HRV, resting heart rate, and day strain.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | End date in YYYY-MM-DD format. Defaults to today. | |
| windowDays | No | Historical baseline window. Defaults to 42. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of behavioral disclosure. It only states a computation task but omits any behavioral traits such as whether it is read-only, requires authentication, or has rate limits. The agent cannot infer safety or side effects from the description alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's action and scope. Every word contributes to understanding, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description should hint at the return format or structure. It does not, leaving the agent uninformed about what the baseline ranges look like. The description covers the input and purpose adequately but is incomplete regarding output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds no meaning beyond what the schema already provides for 'date' and 'windowDays'. While the schema includes defaults and constraints, the description does not elaborate on their significance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'compute' and clearly states the resource 'personal baseline ranges' for five metrics (sleep, recovery, HRV, resting heart rate, day strain). It effectively differentiates from sibling tools like whoop_sleep_summary or whoop_training_load_trend by focusing on baseline computation rather than summaries or alerts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no conditions for use. For example, it does not clarify whether this should be used for a specific window or if other tools are better for individual metric details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Highlight meaningful changes versus yesterday and baseline, such as sleep drops, recovery dips, HRV dips, and resting heart rate spikes.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format. Defaults to today. | |
| baselineWindowDays | No | Historical window used for baseline comparisons. Defaults to 28. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It does not state whether the operation is read-only, what triggers an alert, or any side effects. Only vague hints (e.g., 'highlight') imply a non-destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the core purpose and lists specific examples. Every word contributes meaning without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two optional parameters and no output schema, the description provides reasonable understanding of purpose but omits details on output format or behavior. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal context by linking 'yesterday and baseline' to the parameters, but does not explain how baselineWindowDays affects comparisons or how date is used relative to the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool highlights meaningful changes in metrics like sleep drops, recovery dips, HRV dips, and resting heart rate spikes. It uses a specific verb ('highlight') and resource ('changes versus yesterday and baseline'), and distinguishes well from sibling tools focused on profiles, summaries, or trends.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings (e.g., whoop_baseline_profile for baselines) or when it might be inappropriate. The description only states what it does, not when to choose it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch WHOOP sleep performance, sleep stages, recovery score, HRV, resting heart rate, and recommendation.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format. Defaults to today. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only says 'fetch', implying a read operation but lacks details on authentication, rate limits, or behavior when data is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence listing the fetched fields; it is concise and front-loaded with the action verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description somewhat covers returned fields but is not fully comprehensive; for a simple tool, it is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter, which is already well-documented. The description adds no extra parameter context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches a WHOOP sleep summary, listing specific data fields. However, it does not explicitly differentiate from sibling tools like whoop_baseline_profile or whoop_wellbeing_snapshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any context about prerequisites or recommended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return short and long window trends for sleep, sleep performance, recovery, HRV, resting heart rate, and day strain.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | End date in YYYY-MM-DD format. Defaults to today. | |
| shortWindowDays | No | Short trend window. Defaults to 7. | |
| longWindowDays | No | Long trend window. Defaults to 28. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description only states it returns trends, but does not disclose that this is a read-only operation, does not mention authentication requirements, rate limits, or what the return format looks like. Minimal behavioral information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the action ('Return') and resource ('trends') and succinctly lists the metrics. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should explain what the returned trend data contains (e.g., averages, slopes, time spans). It does not define the windows or how date interacts. Given 3 optional parameters and no output schema, the description leaves significant gaps in understanding the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for all three parameters (date, shortWindowDays, longWindowDays). The description does not add extra meaning beyond listing the metrics; it does not elaborate on parameter usage or constraints. Baseline 3 is appropriate since schema already describes params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns short and long window trends for multiple specific metrics (sleep, sleep performance, recovery, HRV, resting heart rate, day strain). It distinguishes from sibling tools like whoop_sleep_summary (which provides a single point summary) and whoop_baseline_profile (which provides baseline values).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies it is for trend analysis, but does not state when not to use it or mention sibling tools for different use cases (e.g., snapshot vs trend).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a concise WHOOP snapshot for a date: recovery, sleep, cycle strain, workouts, and a workload recommendation.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format. Defaults to today. | |
| includeRaw | No | Include raw WHOOP responses for debugging. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It indicates a read fetch (no destructive actions implied), but does not mention authentication, rate limits, data freshness, or side effects. The description is straightforward but lacks depth typical for a snapshot tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, lists components clearly. No filler or redundancy; every part serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch tool with no output schema, the description adequately lists return components. It could mention error handling or data availability, but the core output is covered. Minor gaps: no mention of how date is interpreted or whether all components are always present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3 applies. The description adds context for the date parameter ('for a date') but does not mention the includeRaw parameter or provide syntax details beyond the schema. No added meaning beyond schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'WHOOP snapshot', listing specific components (recovery, sleep, cycle strain, workouts, workload recommendation). This distinguishes it from siblings like whoop_sleep_summary (only sleep) or whoop_training_load_trend (only training load), making the composite nature explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With siblings like whoop_sleep_summary or whoop_training_load_trend, explicit when/why would help. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check WHOOP recovery metrics before committing to a workload and suggest a safer daily scope when signals are weak.
| Name | Required | Description | Default |
|---|---|---|---|
| workload | Yes | The work the user wants to take on. | |
| ticketCount | No | Number of tickets/tasks being considered. | |
| date | No | Date in YYYY-MM-DD format. Defaults to today. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions checking metrics and suggesting a scope but does not disclose whether the tool is read-only, if authentication is needed, or any side effects. Minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that effectively conveys the tool's function without unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three simple parameters and no output schema, the description provides the core idea but lacks details on return format and how the tool integrates with WHOOP data. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with adequate descriptions for each parameter. The description adds no extra meaning beyond the schema, so it meets the baseline but does not improve parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it checks WHOOP recovery metrics and suggests a safer workload scope. It distinguishes from sibling tools by focusing on workload commitment guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use ('before committing to a workload') but does not explicitly state when not to use or mention alternatives. Usage context is implied but not fully specified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0whoop_baseline_profilewhoop_change_alertswhoop_sleep_summarywhoop_training_load_trendwhoop_wellbeing_snapshotwhoop_workload_guardScored across 6 tools
Most tools have distinct purposes (baseline, alerts, sleep, trends, snapshot, guard), but 'wellbeing_snapshot' overlaps with 'sleep_summary' and 'training_load_trend' as it includes similar metrics, causing potential ambiguity.
All tools follow a consistent 'whoop_<domain>_<aspect>' snake_case pattern with no mixing of conventions, making them predictable and easy to interpret.
With 6 tools covering key areas of WHOOP health metrics, the count is well-scoped for an API wrapper—neither too sparse nor overwhelming.
The tool set covers essential read operations (sleep, recovery, HRV, strain, trends, alerts), but lacks explicit tools for detailed workout breakdown or historical data export, though snapshot partially fills gaps.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Your WHOOP data in the assistant, read-only: recovery, sleep, strain, workouts, cycles and body meas
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
