whoop-client

A Python wrapper for the WHOOP API.

Provides both synchronous and asynchronous clients with Pydantic models, automatic retries, OAuth2 token management, and an MCP server for AI assistants.

Installation

pip install whoop-client

Requires Python 3.10+.

Quick Start

With an access token

from whoop_client import WhoopClient

with WhoopClient("your-access-token") as client:
    profile = client.get_profile()
    print(f"Hello, {profile.first_name}!")

    for cycle in client.iter_cycles():
        if cycle.score:
            print(f"Strain: {cycle.score.strain}")

Async

import asyncio
from whoop_client import AsyncWhoopClient

async def main():
    async with AsyncWhoopClient("your-access-token") as client:
        profile = await client.get_profile()
        print(f"Hello, {profile.first_name}!")

        async for cycle in client.iter_cycles():
            if cycle.score:
                print(f"Strain: {cycle.score.strain}")

asyncio.run(main())

With OAuth2 token refresh

from whoop_client import WhoopClient, OAuthTokenProvider

token_provider = OAuthTokenProvider(
    client_id="your-client-id",
    client_secret="your-client-secret",
    refresh_token="your-refresh-token",
)

with WhoopClient(token_provider) as client:
    profile = client.get_profile()

The OAuthTokenProvider automatically refreshes expired tokens. An AsyncOAuthTokenProvider is available for the async client.

API

Clients

Both WhoopClient and AsyncWhoopClient accept the same constructor arguments:

WhoopClient(
    token_provider,           # Access token string or TokenProvider instance
    *,
    base_url="...",           # Override API base URL
    timeout=30.0,             # Request timeout in seconds
    retry_policy=None,        # Custom RetryPolicy, or None for defaults
    httpx_client=None,        # Bring your own httpx.Client
)

Endpoints

Paginated endpoints accept limit, start, end, and next_token parameters. They return a PaginatedResponse[T] with records and next_token fields.

Auto-Pagination

Use the iter_* methods to automatically paginate through all results:

• iter_cycles(...)
• iter_recoveries(...)
• iter_sleeps(...)
• iter_workouts(...)

These return Iterator[T] (sync) or AsyncIterator[T] (async).

Retry Policy

Requests are retried automatically on transient failures (429, 5xx, timeouts, connection errors) with exponential backoff and jitter. Customize with RetryPolicy:

from whoop_client import WhoopClient, RetryPolicy

policy = RetryPolicy(
    max_retries=5,
    backoff_factor=1.0,
    max_backoff_seconds=120.0,
)

client = WhoopClient("token", retry_policy=policy)

Exceptions

All exceptions inherit from WhoopError:

API errors carry status_code and response attributes for full introspection.

Obtaining Tokens (whoop-client auth)

The whoop-client auth command runs the OAuth2 Authorization Code flow to obtain access and refresh tokens from WHOOP.

Prerequisites

Set your OAuth2 credentials as environment variables (or pass them as flags):

export WHOOP_CLIENT_ID="your-client-id"
export WHOOP_CLIENT_SECRET="your-client-secret"

Usage

whoop-client auth

This opens your browser, waits for the OAuth2 callback, and saves the tokens to ~/.config/whoop-client/tokens.json.

Options

Example

# Use env vars, save to custom file
whoop-client auth --token-file my-tokens.json

# Pass credentials directly
whoop-client auth --client-id ID --client-secret SECRET

# Headless (e.g. SSH session) — prints the URL to visit manually
whoop-client auth --no-open

MCP Server

whoop-client includes an MCP server that exposes WHOOP data as tools for AI assistants like Claude.

Installation

pip install "whoop-client[mcp]"

Configuration

The server requires WHOOP API credentials via environment variables:

Option 1: OAuth2 with auto-refresh (recommended)

Option 2: Static access token

Usage

Run the server directly:

whoop-client mcp

Available Tools

Development

uv sync              # Install dependencies
uv run pre-commit install  # Install pre-commit hooks
uv run pytest        # Run tests
uv run ruff check    # Lint
uv run ruff format   # Format
uv run ty check      # Type check

License

MIT