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

Prerequisites

• Node.js 20 or higher

• A WHOOP account

• WHOOP API credentials (Client ID and Secret)

Getting WHOOP API Credentials

1. Visit the WHOOP Developer Dashboard

2. Create a new OAuth application

3. Set the redirect URI to: http://localhost:3000/auth/whoop/callback

4. Note your Client ID and Client Secret

Installation

Configuration

1. Copy the environment template:

2. Add your WHOOP credentials to .env:

Authentication

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

This will:

1. Open a browser window for WHOOP OAuth login

2. Save your access and refresh tokens locally

3. Automatically refresh tokens when they expire

Usage

Using with Claude Desktop - STDIO Mode (Recommended)

STDIO mode is recommended for better performance and reliability.

1. Get the full path to your installation:

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

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

Using via HTTP Mode

For HTTP mode, start the server:

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

For Claude Desktop HTTP configuration:

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

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-sleep-by-id

Gets detailed sleep data for a specific sleep ID.

Parameters:

• sleepId (string): UUID of the sleep activity

Example:

get-sleep-for-cycle

Retrieves sleep data associated with a specific cycle.

Parameters:

• cycleId (number): ID of the cycle

Example:

get-recovery-for-cycle

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

Parameters:

• cycleId (number): ID of the cycle

Example:

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

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

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

• xmcp Documentation - Using Tools

• xmcp Documentation

• Model Context Protocol Specification

Support

For WHOOP API issues, visit the WHOOP Developer Documentation.

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