How do I use WHOOP MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WHOOP MCP Server what's my recovery score and strain for today?" 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

by izqui

Overview Schema Related Servers Score Discussions

TypeScript

Remote

WHOOP MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the WHOOP API. This server enables LLMs to retrieve sleep, recovery, and physiological cycle data from WHOOP.

Features

🔐 OAuth 2.0 Authentication with automatic token refresh
😴 Sleep Data: Retrieve detailed sleep metrics by ID or cycle
🔄 Cycle Data: Access physiological cycles with strain and heart rate data
💪 Recovery Data: Get recovery scores, HRV, and readiness metrics
🚀 Built with xmcp: Fast, type-safe MCP implementation

Related MCP server: whoop-mcp-server

Prerequisites

Node.js 20 or higher
A WHOOP account
WHOOP API credentials (Client ID and Secret)

Getting WHOOP API Credentials

Visit the WHOOP Developer Dashboard
Create a new OAuth application
Set the redirect URI to: http://localhost:3000/auth/whoop/callback
Note your Client ID and Client Secret

Installation

# Clone the repository
git clone https://github.com/yourusername/whoop-mcp.git
cd whoop-mcp

# Install dependencies
pnpm install
# or npm install

# Build the project
pnpm build
# or npm run build

Configuration

Copy the environment template:

cp .env.example .env

Add your WHOOP credentials to .env:

WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here

Authentication

Before using the MCP server, you need to authenticate with WHOOP:

pnpm auth

This will:

Open a browser window for WHOOP OAuth login
Save your access and refresh tokens locally
Automatically refresh tokens when they expire

Usage

Using with Claude Desktop - STDIO Mode (Recommended)

STDIO mode is recommended for better performance and reliability.

Get the full path to your installation:

pwd  # Copy this path, e.g., /Users/yourname/projects/whoop-mcp

Add the server to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/Users/yourname/projects/whoop-mcp/dist/stdio.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Replace /Users/yourname/projects/whoop-mcp with your actual installation path.

Using via HTTP Mode

For HTTP mode, start the server:

pnpm start
# or
node dist/http.js

The server will run on http://localhost:3002/mcp

For Claude Desktop HTTP configuration:

{
  "mcpServers": {
    "whoop": {
      "url": "http://localhost:3002/mcp"
    }
  }
}

Important: When using STDIO mode with Claude Desktop, you MUST include the env section with your WHOOP credentials, as shown above. The server cannot read your .env file when launched by Claude Desktop.

See xmcp HTTP transport documentation for more details.

Development Mode

pnpm dev

Available Tools

`get-recent-cycles`

Retrieves recent physiological cycles (days) with strain and heart rate data.

Parameters:

limit (number, optional): Number of cycles to retrieve (1-25, default: 10)
days (number, optional): Number of days to look back (1-30)

Example:

Get my last 7 days of WHOOP cycles

`get-sleep-by-id`

Gets detailed sleep data for a specific sleep ID.

Parameters:

sleepId (string): UUID of the sleep activity

Example:

Get sleep data for ID ecfc6a15-4661-442f-a9a4-f160dd7afae8

`get-sleep-for-cycle`

Retrieves sleep data associated with a specific cycle.

Parameters:

cycleId (number): ID of the cycle

Example:

Get sleep data for cycle 12345

`get-recovery-for-cycle`

Gets recovery metrics for a specific cycle, including HRV and readiness scores.

Parameters:

cycleId (number): ID of the cycle

Example:

Get recovery data for cycle 12345

Data Interpretation

Recovery Scores

Green (67-100%): Ready for high strain
Yellow (34-66%): Moderate readiness
Red (0-33%): Focus on recovery

Strain Scale

WHOOP Strain is measured on a scale from 0 to 21
Higher values indicate greater cardiovascular load

Project Structure

whoop-mcp/
├── src/
│   ├── api/           # WHOOP API client and types
│   ├── auth/          # Authentication and token management
│   └── tools/         # MCP tool implementations
├── scripts/
│   ├── auth.ts        # OAuth authentication script
│   └── refresh-token.ts # Manual token refresh
└── dist/              # Compiled output

Token Management

Tokens are stored in .whoop-tokens.json in the project root
Access tokens expire after 1 hour
Refresh tokens are automatically used to obtain new access tokens
Run pnpm refresh-token to manually refresh tokens

Troubleshooting

"Not authenticated" error

Run pnpm auth to authenticate with WHOOP.

"Resource not found" error

Ensure your WHOOP app has the required scopes:

read:cycles
read:sleep
read:recovery
read:profile
offline (for refresh tokens)

Rate limiting

WHOOP API has rate limits. If you encounter 429 errors, wait before making more requests.

Development

# Build the project
pnpm build

# Run in development mode
pnpm dev

# Manually refresh tokens
pnpm refresh-token

Security Notes

Never commit .env or .whoop-tokens.json files
Keep your Client Secret secure
Tokens are stored in the project root as .whoop-tokens.json
Tokens are never transmitted except to WHOOP

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT - See LICENSE file for details

Acknowledgments

Built with xmcp - Fast MCP implementation
Uses the WHOOP API v2

Additional Resources

Support

For WHOOP API issues, visit the WHOOP Developer Documentation.

For MCP-related questions, see the Model Context Protocol documentation.

Available Tools

4 tools

get-recent-cyclesB

Read-onlyIdempotent

Get recent physiological cycles (days) from WHOOP, including strain and heart rate data

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	Number of cycles to retrieve (max 25)
`days`	No	Number of days to look back (optional, default gets most recent)

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds context about retrieving 'recent' cycles and including 'strain and heart rate data', which provides useful behavioral insight beyond annotations, but doesn't detail rate limits or authentication needs.

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 a single, efficient sentence that front-loads the purpose and key details ('including strain and heart rate data'). It avoids redundancy and wastes no words, making it highly concise and well-structured.

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

Completeness3/5

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

Given the tool's moderate complexity (2 parameters, no output schema), annotations cover safety and idempotency, and schema fully documents parameters. The description adds value by specifying data types included, but lacks output format details or error handling, making it adequate but with gaps for a read operation.

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 both parameters ('limit' and 'days') fully documented in the schema. The description mentions 'recent' cycles, which aligns with the 'days' parameter, but adds no additional semantic meaning beyond what the schema provides, meeting the baseline for high coverage.

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

Purpose4/5

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

The description clearly states the action ('Get recent physiological cycles') and resource ('from WHOOP'), specifying it includes 'strain and heart rate data'. It distinguishes from siblings by focusing on cycles rather than recovery or sleep data, though it doesn't explicitly contrast with them.

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

Usage Guidelines2/5

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 alternatives like 'get-recovery-for-cycle' or 'get-sleep-for-cycle'. The description implies it's for retrieving recent cycles with specific data types, but lacks explicit context or exclusions for usage.

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

get-recovery-for-cycleA

Read-onlyIdempotent

Get recovery data for a specific cycle from WHOOP, including recovery score, HRV, and resting heart rate

ParametersJSON Schema

Name	Required	Description	Default
`cycleId`	Yes	The ID of the cycle to retrieve recovery data for

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, indicating safe, repeatable read operations. The description adds valuable context by specifying the data types returned (recovery score, HRV, resting heart rate), which enhances understanding beyond annotations. No contradictions exist.

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 a single, efficient sentence that front-loads the core purpose and includes key data points. Every word adds value without redundancy, making it appropriately sized and well-structured for quick comprehension.

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?

Given the tool's low complexity (1 parameter), rich annotations covering safety and idempotency, and no output schema, the description is mostly complete. It specifies the data returned, but could benefit from mentioning error cases or response format to fully compensate for the missing output schema.

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 the parameter 'cycleId' fully documented in the schema as 'The ID of the cycle to retrieve recovery data for'. The description does not add further details about parameter meaning or usage, so it meets the baseline for high schema coverage.

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 specific action ('Get recovery data'), resource ('for a specific cycle from WHOOP'), and scope ('including recovery score, HRV, and resting heart rate'). It distinguishes from sibling tools like 'get-recent-cycles' (list vs. specific) and 'get-sleep-for-cycle' (recovery vs. sleep data).

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 retrieving recovery metrics for a known cycle ID, but lacks explicit guidance on when to use this tool versus alternatives like 'get-recent-cycles' for listing cycles first. No exclusions or prerequisites are mentioned, leaving usage context partially inferred.

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

get-sleep-by-idB

Read-onlyIdempotent

Get sleep data for a specific sleep ID from WHOOP

ParametersJSON Schema

Name	Required	Description	Default
`sleepId`	Yes	The UUID of the sleep activity to retrieve

TDQS

B3.3/5.0

Behavior3/5

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, repeatable read operation. The description adds no behavioral context beyond this, such as rate limits, authentication needs, or what happens if the sleep ID is invalid, but it doesn't contradict the 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 a single, efficient sentence that directly states the tool's purpose without any fluff or redundancy. It's appropriately sized and front-loaded, making it easy to understand at a glance.

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

Completeness3/5

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

Given the tool's low complexity (single parameter, no output schema) and rich annotations, the description is minimally adequate. However, it lacks details on output format or error handling, which could be helpful for an AI agent, though annotations cover safety aspects.

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 has 100% description coverage, with the parameter 'sleepId' documented as a UUID for the sleep activity. The description doesn't add any semantic details beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high schema coverage without extra value.

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

Purpose4/5

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

The description clearly states the verb 'Get' and resource 'sleep data for a specific sleep ID from WHOOP', making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get-sleep-for-cycle', which might retrieve sleep data in a different context, leaving room for slight ambiguity.

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

Usage Guidelines2/5

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, such as the sibling tools 'get-recent-cycles', 'get-recovery-for-cycle', or 'get-sleep-for-cycle'. It lacks context on prerequisites, like needing a specific sleep ID, or exclusions, such as not being suitable for bulk retrieval.

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

get-sleep-for-cycleB

Read-onlyIdempotent

Get sleep data for a specific cycle from WHOOP

ParametersJSON Schema

Name	Required	Description	Default
`cycleId`	Yes	The ID of the cycle to retrieve sleep data for

TDQS

B3.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 agent knows this is a safe, repeatable read operation. The description adds no additional behavioral context beyond what annotations provide, such as rate limits, authentication needs, or response format details, but it does not contradict the 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 a single, clear sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and efficiently communicates the core functionality, making it easy for an agent to parse and understand quickly.

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

Completeness3/5

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

Given the tool's simplicity (one required parameter, no output schema) and rich annotations covering safety and idempotency, the description is minimally adequate. However, it lacks details on output format, error handling, or integration with sibling tools, which could help the agent use it more effectively in context.

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 the parameter 'cycleId' fully documented in the input schema as 'The ID of the cycle to retrieve sleep data for'. The description adds no extra meaning or context about the parameter beyond what the schema provides, adhering to the baseline score when schema coverage is high.

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

Purpose4/5

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

The description clearly states the verb 'Get' and the resource 'sleep data for a specific cycle from WHOOP', making the purpose immediately understandable. However, it does not explicitly differentiate this tool from its sibling 'get-sleep-by-id', which likely serves a similar purpose with a different identifier, leaving some ambiguity about when to use one over the other.

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

Usage Guidelines2/5

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, such as the sibling tools 'get-recent-cycles', 'get-recovery-for-cycle', or 'get-sleep-by-id'. It lacks context about prerequisites, timing, or specific scenarios where this tool is preferred, leaving the agent to infer usage based on tool names alone.

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

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Disambiguation3/5

The tools have some overlap in purpose, particularly between 'get-sleep-by-id' and 'get-sleep-for-cycle', which both retrieve sleep data and could be confused. However, the descriptions clarify the distinction (by ID vs. by cycle), and the other tools target distinct data types (cycles, recovery), so agents can differentiate them with careful reading.

Naming Consistency5/5

All tool names follow a consistent verb-noun pattern with hyphens ('get-recent-cycles', 'get-recovery-for-cycle', 'get-sleep-by-id', 'get-sleep-for-cycle'), using 'get' as the verb throughout. This predictability makes the set easy to navigate and understand.

Tool Count4/5

With 4 tools, the count is slightly low but reasonable for a focused WHOOP data retrieval server. It covers key physiological aspects (cycles, recovery, sleep), though it might benefit from additional tools for broader health metrics or write operations, but it's not overly thin.

Completeness3/5

The tool set provides read-only access to core WHOOP data (cycles, recovery, sleep), which is appropriate for a retrieval-focused server. However, there are notable gaps: no tools for creating, updating, or deleting data, and missing operations like listing all sleeps or getting user profile info, which could limit agent workflows in a broader health context.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Reddit Discussion

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

WHOOP — MissingMCP
com.missingmcp
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Health & Wellness Fitness Tracking
24
WHOOP A
io.github.mcp-dir
Your WHOOP data in the assistant, read-only: recovery, sleep, strain, workouts, cycles and body meas
Fitness Tracking Health & Wellness
131
Pace COAuth
app.run.europe-west1.pace-mcp-820971109121
Pace is a remote MCP server that exposes wearable and fitness data to Claude via the Model Context Protocol. It connects to Garmin, Oura, Whoop, Polar, Fitbit and 20+ devices and provides 15 tools for querying sleep, activity, recovery, and training data. Hosted on Google Cloud Run, OAuth 2.1 authentication, Streamable HTTP transport. Instructions: First you need to create an account at: https://pacetraining.co and connect your wearables. After that you can connect the remote Server via Custom Connector in Claude and OAuth 2.1 Flow startet.
Customer Data Platforms Fitness Tracking Health & Wellness
3
eliu243-oura-mcp-server-eliu
ai.smithery
Connect your Oura Ring account securely in minutes. Enable authorized access to your sleep, activi…
Health & Wellness Data Platforms
2

Related MCP Servers

Oura MCP
Health & Wellness Fitness Tracking
ai-niki
A
license
Not graded
quality
D
maintenance
Provides LLMs with access to Oura Ring health data including sleep metrics, activity tracking, heart rate, readiness scores, and other wellness insights through the Oura API v2.
Updated 9 months ago (2025-11-23 18:16 UTC)
MIT
whoop-mcp-server
Health & Wellness Fitness Tracking
khushishelat
F
license
Not graded
quality
D
maintenance
Enables language models to query cycles, recovery, strain, and workout data from the Whoop API.
Updated a year ago (2025-05-13 22:30 UTC)
whoop-fitness
Health & Wellness Fitness Tracking
shashwatchandra
F
license
Not graded
quality
D
maintenance
Enables users to query WHOOP health data including recovery, sleep, workouts, and cycles through Claude Desktop using MCP tools.
Updated 4 months ago (2026-05-10 00:50 UTC)
whoop-tracker-mcp-server
Health & Wellness Fitness Tracking
alacore
A
license
B
quality
D
maintenance
Integrates with Whoop API v2 to access user profile, sleep, recovery, cycles, and workout data via natural language, with OAuth2 authentication and automatic token refresh.
Updated a year ago (2025-10-09 09:30 UTC)
14
19
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/izqui/whoop-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server