Skip to main content
Glama
benhursenabathi

whoop-mcp-server

by benhursenabathi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Whoop MCP Server

An MCP (Model Context Protocol) server that provides access to your Whoop health and fitness data, enabling Claude and other AI assistants to give you personalized health recommendations.

New here? Check out HOW_TO_USE.md for a step-by-step setup guide.

Features

  • Recovery Data: Get your recovery score, HRV, resting heart rate, SpO2, and skin temperature

  • Sleep Analysis: Detailed sleep stages (light, REM, deep), sleep performance, efficiency, and respiratory rate

  • Workout Tracking: Strain scores, calories burned, heart rate zones, distance, and elevation

  • Daily Strain: Cumulative daily strain and energy expenditure

  • Health Overview: Combined view of recovery, sleep, and strain with personalized recommendations

  • Profile & Body Measurements: User profile and body measurements data

Related MCP server: whoop-chatgpt-app

Prerequisites

  1. Whoop Device: You need an active Whoop membership

  2. Whoop Developer Account: Create an app at developer.whoop.com

  3. Node.js 18+: Required to run the server

Setup

1. Create a Whoop Developer App

  1. Go to developer-dashboard.whoop.com

  2. Create a new app

  3. Set the redirect URL to http://localhost:8080/callback

  4. Note your Client ID and Client Secret

  5. Request the following scopes:

    • read:recovery

    • read:cycles

    • read:workout

    • read:sleep

    • read:profile

    • read:body_measurement

    • offline (for refresh token)

2. Install the MCP Server

cd whoop-mcp-server
npm install
npm run build

3. Get Your Initial Tokens (One-Time)

Run the token helper script:

node get-tokens.mjs

Follow the prompts to:

  1. Enter your Client ID and Client Secret

  2. Open the authorization URL in your browser

  3. Authorize the app and copy the code from the redirect URL

  4. The script will output your initial tokens

4. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/path/to/whoop-mcp-server/dist/index.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret",
        "WHOOP_ACCESS_TOKEN": "your-initial-access-token",
        "WHOOP_REFRESH_TOKEN": "your-initial-refresh-token"
      }
    }
  }
}

5. First Use & Token Persistence

On first API call, the server will:

  1. Use your initial tokens from the config

  2. Save them to tokens.json in the server directory

  3. Automatically refresh when they expire

After initial setup, you can remove WHOOP_ACCESS_TOKEN and WHOOP_REFRESH_TOKEN from your config. The server only needs:

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/path/to/whoop-mcp-server/dist/index.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Token Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         STARTUP                                 │
├─────────────────────────────────────────────────────────────────┤
│  Claude Desktop starts → WHOOP MCP server launches              │
│                              │                                  │
│                              ▼                                  │
│                   Check for tokens.json                         │
│                        /          \                             │
│                    Found          Not Found                     │
│                      │                │                         │
│                      ▼                ▼                         │
│              Use persisted      Use env vars                    │
│                tokens          (initial setup)                  │
│                      \              /                           │
│                       ▼            ▼                            │
│                    Token loaded in memory                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                       ON API CALL                               │
├─────────────────────────────────────────────────────────────────┤
│  You ask "get my recovery" → check token expiry                 │
│                              │                                  │
│                     Token expired?                              │
│                        /          \                             │
│                      YES          NO                            │
│                       │            │                            │
│                       ▼            │                            │
│              Refresh via WHOOP     │                            │
│              API (uses client      │                            │
│              credentials +         │                            │
│              refresh token)        │                            │
│                       │            │                            │
│                       ▼            │                            │
│              Save new tokens       │                            │
│              to tokens.json        │                            │
│                       \           /                             │
│                        ▼         ▼                              │
│                   Make API call with valid token                │
└─────────────────────────────────────────────────────────────────┘

Key files:

  • tokens.json - Persisted tokens (auto-created, survives restarts)

  • dist/index.js - The MCP server

What's automatic:

  • Token refresh when expired

  • Saving new tokens to disk

  • Loading tokens on restart

What requires manual action:

  • Initial OAuth setup (one-time)

  • Re-authentication if unused for 30-90 days (refresh token expires)

Available Tools

whoop_get_profile

Get your Whoop user profile (name, email, user ID).

whoop_get_body_measurements

Get your body measurements (height, weight, max heart rate).

whoop_get_recovery

Get recovery data including recovery score, HRV, resting heart rate, SpO2.

Parameters:

  • limit (1-25, default 7): Number of records

  • start: Start date filter (ISO 8601)

  • end: End date filter (ISO 8601)

whoop_get_sleep

Get detailed sleep data including sleep stages, performance, and efficiency.

Parameters:

  • limit (1-25, default 7): Number of records

  • start: Start date filter (ISO 8601)

  • end: End date filter (ISO 8601)

whoop_get_workouts

Get workout data including strain, calories, heart rate zones.

Parameters:

  • limit (1-25, default 10): Number of records

  • start: Start date filter (ISO 8601)

  • end: End date filter (ISO 8601)

whoop_get_cycles

Get daily physiological cycle data (strain, calories, heart rate).

Parameters:

  • limit (1-25, default 7): Number of records

  • start: Start date filter (ISO 8601)

  • end: End date filter (ISO 8601)

whoop_get_health_overview

Get a comprehensive health overview combining recovery, sleep, and strain data with personalized recommendations.

Example Usage with Claude

Once configured, you can ask Claude things like:

  • "How's my recovery today?"

  • "Show me my sleep from last week"

  • "What workouts have I done recently?"

  • "Give me a health overview"

  • "Based on my Whoop data, should I train hard today?"

  • "How has my HRV trended this week?"

  • "What was my sleep quality like last night?"

Troubleshooting

"No tokens available" error

Run node get-tokens.mjs to get initial tokens, or check that tokens.json exists.

"Missing WHOOP_CLIENT_ID or WHOOP_CLIENT_SECRET" error

These must always be in your Claude Desktop config - they never expire.

"Failed to refresh token" error

Your refresh token has expired (typically after 30-90 days of non-use). Run node get-tokens.mjs to re-authenticate.

No data returned

  • Ensure you've worn your Whoop device and data has synced

  • Check that your app has the required scopes authorized

View current persisted tokens

cat tokens.json

Force re-authentication

rm tokens.json
# Then run get-tokens.mjs or add tokens back to Claude config

Security Considerations

Token Storage

  • Tokens are stored in tokens.json with restricted permissions (mode 0600 - owner read/write only)

  • Windows users: File permissions work differently on Windows and may not provide equivalent protection. Consider additional access controls.

  • Tokens are stored unencrypted; ensure your system has appropriate access controls

Configuration Security

  • Your claude_desktop_config.json contains your client secret in plain text

  • Do not commit this config file to version control

  • Consider restricting file permissions on the config file:

    • macOS/Linux: chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

Best Practices

  • Regularly rotate your Whoop developer app credentials

  • Monitor your Whoop account for unauthorized access

  • Run npm audit periodically to check for dependency vulnerabilities

  • After initial setup, remove WHOOP_ACCESS_TOKEN and WHOOP_REFRESH_TOKEN from your config (they're persisted in tokens.json)

Optional: Custom Token Location

Set WHOOP_TOKEN_PATH environment variable to store tokens in a specific location:

"env": {
  "WHOOP_TOKEN_PATH": "/path/to/secure/tokens.json",
  "WHOOP_CLIENT_ID": "your-client-id",
  "WHOOP_CLIENT_SECRET": "your-client-secret"
}

API Reference

This server uses the Whoop API v2. For more details on the data model and endpoints, see the official documentation.

License

MIT

Available Tools

7 tools
whoop_get_body_measurementsGet Body MeasurementsA
Read-onlyIdempotent

Retrieves body measurements for the authenticated Whoop user.

Returns:

  • height_meter: Height in meters

  • weight_kilogram: Weight in kilograms

  • max_heart_rate: Maximum heart rate

Useful for calculating calories burned and personalizing workout recommendations.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the returned field names and authentication context, but no additional behavioral traits like rate limits or pagination. This is adequate but not rich, consistent with the reduced burden when annotations are present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the core action, and structured with a bulleted list for return fields. The final sentence on use cases earns its place. No redundant or extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool with strong annotations, the description fully covers what is needed: the resource retrieved, the exact return fields, and practical applications. There is no output schema, so the description appropriately explains the return values. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and an empty input schema, so there are no parameter details to document. The baseline for no parameters is 4, and the description correctly omits any irrelevant parameter information.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Retrieves body measurements for the authenticated Whoop user.' It clearly differentiates from sibling tools by naming the resource (body measurements) and listing the exact fields returned, which are distinct from profile, recovery, sleep, workouts, cycles, and health overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Useful for calculating calories burned and personalizing workout recommendations' conveys clear intended use cases. However, it does not explicitly mention when not to use this tool or point to alternative sibling tools, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_get_cyclesGet Daily Strain CyclesA
Read-onlyIdempotent

Retrieves physiological cycle (day) data from Whoop including daily strain, calories, and heart rate.

A cycle represents a physiological day (wake to wake), not a calendar day.

Day Strain is cumulative and measured on a 0-21 scale:

  • 0-10: Light day

  • 10-14: Moderate day

  • 14-18: Strenuous day

  • 18-21: All out day

Parameters:

  • limit: Number of records (1-25, default: 7)

  • start: Filter cycles after this date (ISO 8601)

  • end: Filter cycles before this date (ISO 8601)

Returns for each cycle:

  • strain: Daily strain score (0-21)

  • kilojoule: Total energy expenditure

  • average/max_heart_rate: Heart rate summary

ParametersJSON Schema
NameRequiredDescriptionDefault
endNoEnd date filter (ISO 8601 format)
limitNoNumber of cycle records to fetch (1-25, default: 7)
startNoStart date filter (ISO 8601 format)

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the physiological-day definition, the 0-21 strain scale interpretation, and the expected return fields. This goes beyond the annotations to help the agent understand data semantics, though it omits details like pagination or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a concise main statement, a clarifying definition, a strain scale breakdown, and bullet lists for parameters and return fields. It contains substantial useful detail without fluff, though it is longer than minimal; the organized sections earn their place for readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully compensates by explicitly listing return fields (strain, kilojoule, average/max_heart_rate). It also covers the conceptual cycle definition, parameter ranges, and the strain scale, making it self-contained for a read-only tool with strong annotations. This is a complete, well-rounded description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for all three parameters (limit, start, end). The description essentially repeats the same parameter semantics (limit 1-25 default 7; ISO 8601 filters) without adding new meaning beyond the schema. It does list return fields, which indirectly clarifies parameter effects, but the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Retrieves') and names the resource ('physiological cycle (day) data' including daily strain, calories, and heart rate). It clearly distinguishes from sibling tools by focusing on daily cycles and strain, and explicitly clarifies that a cycle is wake-to-wake, not a calendar day.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for daily strain and cycle data with detailed semantics (cycle definition, strain scale), but it does not explicitly mention when to use this tool versus siblings like whoop_get_recovery or whoop_get_sleep. There are no exclusions or alternative tool references, leaving usage guidance only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_get_health_overviewGet Health OverviewA
Read-onlyIdempotent

Gets a comprehensive health overview combining your latest recovery, sleep, and strain data.

This is the best tool to use when you want a quick summary of current health status.

Returns:

  • Latest recovery score and metrics (HRV, RHR, SpO2)

  • Last night's sleep data and performance

  • Today's/yesterday's strain

  • Personalized recommendations based on recovery status

Use this for:

  • Morning check-ins on readiness

  • Quick health status updates

  • Deciding workout intensity

  • Understanding overall health trends

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about what data is included (recovery score, HRV, RHR, SpO2, sleep, strain) and the time ranges (latest, last night, today/yesterday), plus personalized recommendations. This is meaningful beyond annotation hints, though no mention of auth or rate limits is needed for a read-only overview.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear opening sentence, a best-use note, and bullet-point lists for returns and use cases. Every sentence adds value, and it is front-loaded with the core purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description compensates by enumerating the key return categories and providing use-case guidance. Sibling tools exist for specific data details, and this tool is clearly positioned as an aggregate overview. The description is complete for an agent to decide when and how to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema is fully descriptive (empty object). The description does not need to add parameter details. Since there are no parameters, the baseline is 4, and the description appropriately focuses on return values rather than input semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('Gets'), resource ('comprehensive health overview'), and scope ('combining your latest recovery, sleep, and strain data'). It distinguishes itself from sibling tools that focus on individual data types, making it the go-to for an aggregated summary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly identifies when to use this tool ('This is the best tool to use when you want a quick summary of current health status') and lists concrete use cases. It does not explicitly name alternatives or provide exclusions, but the context clearly implies detailed data tools should be used when specific metrics are needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_get_profileGet Whoop User ProfileA
Read-onlyIdempotent

Retrieves basic profile information for the authenticated Whoop user.

Returns:

  • user_id: Whoop user ID

  • email: User's email address

  • first_name: User's first name

  • last_name: User's last name

Use this to identify the user and personalize responses.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context by specifying that it operates on the authenticated user and lists the returned fields. No contradictions exist, and the extra detail about return values is valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and efficiently structured, with a clear opening sentence, a bulleted list of return fields, and a brief usage note. Every sentence adds value without redundancy, making it easy for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description enumerates all return fields, clarifying what 'basic profile information' means. Combined with a clear purpose, usage hint, and good sibling differentiators, the description is complete for a simple zero-parameter read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, the schema fully covers all inputs (100% coverage). The baseline for 0 parameters is 4, and the description does not need to elaborate on parameter mechanics. It appropriately focuses on outputs rather than inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the specific action ('Retrieves basic profile information') and the resource ('authenticated Whoop user'). It clearly differentiates from sibling tools, which all target different data types (recovery, sleep, workouts, etc.), by focusing on profile identity fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for use: 'Use this to identify the user and personalize responses.' It does not explicitly mention when not to use it or name alternatives, but the implied contrast with sibling tools is evident. This meets the 'clear context, no exclusions' level.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_get_recoveryGet Recovery DataA
Read-onlyIdempotent

Retrieves recovery data from Whoop including recovery score, HRV, resting heart rate, and SpO2.

Recovery score indicates how ready your body is for strain:

  • 67-100% (Green): Optimal recovery, ready for high strain

  • 34-66% (Yellow): Moderate recovery, be mindful of strain

  • 0-33% (Red): Low recovery, prioritize rest

Parameters:

  • limit: Number of records (1-25, default: 7)

  • start: Filter recoveries after this date (ISO 8601)

  • end: Filter recoveries before this date (ISO 8601)

Returns for each recovery:

  • recovery_score: Overall recovery percentage

  • hrv_rmssd_milli: Heart rate variability (ms)

  • resting_heart_rate: Resting heart rate (bpm)

  • spo2_percentage: Blood oxygen saturation

  • skin_temp_celsius: Skin temperature

ParametersJSON Schema
NameRequiredDescriptionDefault
endNoEnd date filter (ISO 8601 format)
limitNoNumber of recovery records to fetch (1-25, default: 7)
startNoStart date filter (ISO 8601 format, e.g., 2024-01-01T00:00:00Z)

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the read-only, idempotent, non-destructive nature, so the description adds value by specifying exactly what fields are returned (recovery_score, hrv_rmssd_milli, etc.) and how to interpret recovery scores. This goes beyond the structured annotations by providing semantic meaning of the data, though it omits details like timezone handling or pagination beyond the limit parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections for the main purpose, recovery score interpretation, parameters, and return fields. It is longer than necessary because the parameter list echoes the schema, but the bullet point format and front-loaded summary make it easy to scan. Every section contributes to understanding the tool's output and usage, so there is no wasted content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description appropriately explains return values and even provides interpretation guidance for recovery scores. All three parameters are documented, and the response fields are enumerated with units. The only missing completeness element is explicit alternative tool recommendations, but for a read-only data retrieval tool, the description gives sufficient information for an agent to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description's parameters section largely repeats the schema's descriptions, but it adds slightly more semantic clarity by stating 'Filter recoveries after this date' for start and 'before this date' for end, which is more explicit than the schema's generic 'Start date filter' and 'End date filter'. This is a minor enhancement, not a significant compensation gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Retrieves recovery data from Whoop' and lists specific metrics (recovery score, HRV, resting heart rate, SpO2). This specific verb+resource combination distinguishes it from sibling tools like whoop_get_sleep and whoop_get_workouts, which focus on other data types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by explaining the recovery score bands (Green/Yellow/Red) and how they relate to strain readiness, but it does not explicitly say when to use this tool over others or provide exclusion criteria. There is no mention of alternatives like whoop_get_health_overview for broader health metrics, so usage context is only implied, not fully articulated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_get_sleepGet Sleep DataA
Read-onlyIdempotent

Retrieves detailed sleep data from Whoop including sleep stages, performance, and respiratory rate.

Parameters:

  • limit: Number of records (1-25, default: 7)

  • start: Filter sleeps after this date (ISO 8601)

  • end: Filter sleeps before this date (ISO 8601)

Returns for each sleep:

  • Sleep stages: Light, REM, Deep (SWS), Awake time

  • sleep_performance_percentage: How well you met your sleep need

  • sleep_efficiency_percentage: Time asleep vs time in bed

  • sleep_consistency_percentage: Regularity of sleep schedule

  • respiratory_rate: Breaths per minute

  • sleep_needed: Baseline need plus adjustments for strain/debt

ParametersJSON Schema
NameRequiredDescriptionDefault
endNoEnd date filter (ISO 8601 format)
limitNoNumber of sleep records to fetch (1-25, default: 7)
startNoStart date filter (ISO 8601 format)

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about returned data fields (e.g., sleep stages, respiratory rate), but does not disclose potential behavioral nuances like pagination behavior, rate limits, or authentication requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose sentence, labeled parameter list, and return-field bullets. It is slightly verbose but every section earns its place, and the formatting aids scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description compensates by detailing expected return fields and parameter behavior. It covers key aspects for invocation, though it omits minor details like sorting order or error handling, which are not critical for this simple read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with each parameter already described in the schema. The description adds slight clarification (e.g., 'Filter sleeps after this date' vs 'End date filter') but does not significantly add beyond the schema. Baseline of 3 is appropriate given the schema carries the full parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves detailed sleep data from Whoop, listing specific fields like sleep stages, performance, and respiratory rate. This distinguishes it from sibling tools focused on other data types (workouts, recovery, etc.) with a specific verb and resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (use when you need sleep data) but does not explicitly mention when not to use it or alternatives among sibling tools. It provides no exclusionary guidance or comparison to other Whoop endpoints, leaving the agent to infer appropriateness.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_get_workoutsGet Workout DataA
Read-onlyIdempotent

Retrieves workout data from Whoop including strain, heart rate zones, calories, and distance.

Strain is measured on a 0-21 scale:

  • 0-10: Light activity

  • 10-14: Moderate activity

  • 14-18: High strain (strenuous)

  • 18-21: All out (maximal effort)

Parameters:

  • limit: Number of records (1-25, default: 10)

  • start: Filter workouts after this date (ISO 8601)

  • end: Filter workouts before this date (ISO 8601)

Returns for each workout:

  • sport_name: Type of activity

  • strain: Workout strain score (0-21)

  • kilojoule: Energy burned

  • average/max_heart_rate: Heart rate data

  • distance_meter: Distance covered (if applicable)

  • zone_durations: Time spent in each HR zone

ParametersJSON Schema
NameRequiredDescriptionDefault
endNoEnd date filter (ISO 8601 format)
limitNoNumber of workout records to fetch (1-25, default: 10)
startNoStart date filter (ISO 8601 format)

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read operation. The description adds valuable behavioral context by explaining the strain scale (0-21) and enumerating return fields, going beyond the schema and annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: it opens with the purpose, then the strain scale, then parameters, then return fields. Every sentence contributes useful information without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by listing return fields and explaining strain interpretation. It omits details like pagination or error handling, but these are not critical for this simple read-only tool, making it sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes all three parameters with details (limit range/default, start/end ISO format). The description repeats this information without adding new semantic nuances beyond a minor clarification of filter direction. With 100% schema coverage, the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves workout data including specific fields (strain, heart rate zones, calories, distance), using a specific verb and resource. It distinguishes from sibling tools like whoop_get_recovery or whoop_get_sleep through the workout-specific content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly conveys when to use the tool by listing workout-specific fields and the strain scale, making it appropriate for workout data retrieval. It does not explicitly mention alternatives, but the context and sibling tool names provide enough differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.2.0
    • First observedwhoop_get_body_measurements
    • First observedwhoop_get_cycles
    • First observedwhoop_get_health_overview
    • First observedwhoop_get_profile
    • First observedwhoop_get_recovery
    • First observedwhoop_get_sleep
    • First observedwhoop_get_workouts
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 7 tools

Disambiguation5/5

Each tool targets a distinct Whoop data domain: profile, body measurements, recovery, sleep, workouts, cycles, and a combined health overview. The health overview is clearly complementary rather than overlapping, and the parameterized filters on date/limit further distinguish the data-retrieval tools.

Naming Consistency5/5

All tools follow the exact same 'whoop_get_<resource>' pattern, with clear and consistent resource names. This uniform verb_noun structure makes it easy to predict tool behavior and select the right one.

Tool Count5/5

Seven tools is well-scoped for a Whoop data retrieval server. Each tool covers a meaningful health data category without redundancy, and the count feels appropriately balanced—not too sparse, not overwhelming.

Completeness5/5

The tool set provides comprehensive read coverage of Whoop's main health data types: profile, body metrics, recovery, sleep, workouts, daily cycles, and a combined overview. Since the server's purpose is data retrieval, the absence of write operations is not a gap; all core data categories are represented, and the health overview tool nicely ties everything together.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • whoop-chatgpt-app

    colesmcintosh
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that connects WHOOP health tracker data to ChatGPT, enabling read-only search, fetch, summary, and a React dashboard widget for recovery, sleep, strain, and workouts.
    1
    MIT

  • WHOOP MCP Server

    Tavaresiqueira
    A
    license
    A
    quality
    D
    maintenance
    Exposes WHOOP recovery, sleep, strain, and workout metrics to MCP-compatible AI assistants using OAuth 2.0 authentication, enabling daily wellbeing snapshots, trend analysis, and workload recommendations.
    6
    458 npm
    MIT