whoop-sync

A Python library to sync WHOOP health data locally and expose it via MCP (Model Context Protocol) for AI assistants. Inspired by Garmy.

Overview

whoop-sync pulls your WHOOP data via the official API, stores it in a local SQLite database, and provides an MCP server for AI assistants like Claude Code or OpenCode to query your health metrics.

Features

• OAuth 2.0 Authentication - Seamless browser-based login with automatic callback capture
• Local SQLite Storage - Your health data stays on your machine
• Multi-Profile Support - Manage multiple WHOOP accounts
• MCP Server - Query your health data from Claude Code, OpenCode, or other MCP-compatible tools
• CLI Tools - Simple commands for syncing and managing data

Installation

Clone the repository and install locally:

git clone https://github.com/yourusername/whoop-sync.git
cd whoop-sync
pip install -e ".[mcp]"

Prerequisites

1. Register a WHOOP Developer App

1. Go to the WHOOP Developer Portal
2. Create a new application
3. Set the redirect URI to: http://localhost:8338/callback
4. Enable all required scopes: read:profile, read:body_measurement, read:cycles, read:recovery, read:sleep, read:workout, offline
5. Note your Client ID and Client Secret

2. Create a Profile Directory

Create a directory to store your configuration and data:

mkdir -p ~/.whoop-sync

Or for a custom location:

mkdir -p ~/profiles/my-whoop-profile

3. Configure Credentials

You can provide credentials in three ways:

Option A: Config file (recommended for profiles)

Create a config.json in your profile directory:

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "http://localhost:8338/callback"
}

Option B: Environment variables

export WHOOP_CLIENT_ID="YOUR_CLIENT_ID"
export WHOOP_CLIENT_SECRET="YOUR_CLIENT_SECRET"

Option C: CLI flags

Pass credentials directly when logging in (they will be saved to the profile):

whoop-sync login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

Quick Start

Authentication

# Using default profile (~/.whoop-sync/)
whoop-sync login

# Using a custom profile
whoop-sync --profile-path ~/profiles/my-whoop-profile login

This opens a browser for WHOOP authorization. After logging in, the token is saved to your profile.

Sync Data

# Sync last 7 days (default)
whoop-sync sync

# Sync last 30 days
whoop-sync sync --last-days 30

# Sync specific date range
whoop-sync sync --start-date 2025-01-01 --end-date 2025-06-30

# Sync specific metrics only
whoop-sync sync --last-days 30 --metrics sleep,recovery

# With custom profile
whoop-sync --profile-path ~/profiles/my-whoop-profile sync --last-days 7

Check Status

whoop-sync status

MCP Server Integration

The MCP server exposes your health data to AI coding assistants like Claude Code and OpenCode.

Claude Code

Add to your project's .mcp.json or global MCP config:

{
  "mcpServers": {
    "whoop": {
      "command": "/path/to/your/venv/bin/whoop-mcp",
      "args": ["--profile-path", "/path/to/your/profile", "server"]
    }
  }
}

OpenCode

Add to your opencode.json:

{
  "mcp": {
    "whoop": {
      "enabled": true,
      "type": "local",
      "command": [
        "/path/to/your/venv/bin/whoop-mcp",
        "--profile-path",
        "/path/to/your/profile",
        "server"
      ]
    }
  }
}

Manual Testing

Start the MCP server directly:

whoop-mcp --profile-path ~/profiles/my-whoop-profile server

Available MCP Tools

Tool	Description
query_health_data	Execute read-only SQL queries on your health database
get_recovery_summary	Get recovery scores and HRV for a date range
get_sleep_analysis	Analyze sleep stages, efficiency, and performance
get_workout_summary	Summarize workouts with optional sport filtering
get_strain_trends	View daily strain trends
get_hrv_trends	Track HRV trends over time
get_database_schema	Get database schema information

Data Types

• Cycles - Daily physiological cycles with strain scores
• Recovery - Recovery scores, HRV, resting heart rate, SpO2, skin temp
• Sleep - Sleep stages, efficiency, performance, respiratory rate
• Workouts - Strain, heart rate zones, distance, altitude
• Profile - User information
• Body Measurements - Height, weight, max heart rate

Environment Variables

Variable	Description	Default
WHOOP_SYNC_PROFILE_PATH	Profile directory path	~/.whoop-sync/
WHOOP_CLIENT_ID	WHOOP OAuth client ID	-
WHOOP_CLIENT_SECRET	WHOOP OAuth client secret	-

Multi-Profile Usage

Manage multiple WHOOP accounts by using separate profile directories:

# Create profile directories
mkdir -p ~/whoop-profiles/user1
mkdir -p ~/whoop-profiles/user2

# Add config.json to each with respective credentials
# Then login and sync each profile separately

whoop-sync --profile-path ~/whoop-profiles/user1 login
whoop-sync --profile-path ~/whoop-profiles/user1 sync --last-days 30

whoop-sync --profile-path ~/whoop-profiles/user2 login
whoop-sync --profile-path ~/whoop-profiles/user2 sync --last-days 30

# Start MCP server for a specific profile
whoop-mcp --profile-path ~/whoop-profiles/user1 server

Development

# Install development dependencies
make install-dev

# Run tests
make test

# Lint and format
make lint
make format

License

Apache-2.0

Acknowledgments

• Built on top of whoopy - unofficial WHOOP API client
• Inspired by garmy - Garmin data sync library