whoop-write-mcp

MCP server for Whoop — read biometrics, log activities, and manage your Whoop band from Claude.

Built on whoop-write-api and the Model Context Protocol.

Tools

Read

Tool	Description
get_recovery	Recovery score, HRV, resting HR (supports date range)
get_sleep	Sleep score, hours, respiratory rate
get_strain	Daily strain and heart rate from cycles
get_body_measurement	Height, weight, max HR
get_sport_types	List all Whoop sport/activity type IDs
search_exercises	Search exercise catalog by name, equipment, muscle group
get_journal_behaviors	Available journal questions for a date

Write

Tool	Description
create_activity	Log sauna, meditation, yoga, running, etc.
delete_activity	Remove an activity by ID
list_activities	List recent activities with IDs
update_weight	Update body weight (lbs, converted to kg)
set_alarm	Set or disable Whoop alarm
log_workout	Full workout with optional exercise detail
link_exercises	Attach per-set exercise data to an activity
log_journal	Log caffeine, alcohol, supplements, notes

Connect to Claude Code

Step 1: Add the server

claude mcp add -s user whoop -- uvx whoop-write-mcp

Step 2: Authenticate

whoop-write-mcp login

Enter your Whoop email and password when prompted. Credentials are used once to get tokens, then discarded. Tokens are cached at ~/.whoop/tokens.json and auto-refresh — you shouldn't need to login again.

Step 3: Use it

Ask Claude things like:

• "What's my recovery today?"
• "Log a 20-minute sauna session"
• "Set my alarm for 7:30 AM"
• "How did I sleep last night?"
• "Update my weight to 255 lbs"
• "Delete my last activity"

Alternative: env vars (skip the login step)

claude mcp add -e WHOOP_EMAIL=you@example.com -e WHOOP_PASSWORD=yourpass -s user whoop -- uvx whoop-write-mcp

Server auto-authenticates on first tool call. Useful for automation.

From source

git clone https://github.com/jd1207/whoop-write-mcp.git
cd whoop-write-mcp && pip install -e .
claude mcp add -s user whoop -- whoop-write-mcp
whoop-write-mcp login

Managing

claude mcp list            # see registered servers
claude mcp remove whoop    # unregister
whoop-write-mcp status           # check auth state
whoop-write-mcp logout           # remove cached tokens

Or type /mcp inside Claude Code to manage connected servers.

How Auth Works

1. First tool call checks for cached tokens at ~/.whoop/tokens.json
2. No tokens? Auto-authenticates from WHOOP_EMAIL/WHOOP_PASSWORD env vars if set
3. No env vars? Returns a clear error: "Run whoop-write-mcp login in your terminal"
4. Tokens cached (0600 permissions), auto-refresh on expiry
5. Password never stored on disk — only refresh tokens

Architecture

Claude Code  <--stdio-->  whoop-write-mcp  <--https-->  Whoop API
                              |
                        ~/.whoop/tokens.json

Claude Code Skill

The skill/ directory contains a coaching intelligence skill that teaches Claude how to interpret Whoop data and make training decisions — not just call tools, but use them like a coach.

Install it to make any Claude Code agent smarter with Whoop data:

cp -r skill/ ~/.claude/skills/whoop-mcp/

What the skill provides:

• Decision frameworks — when to train heavy, when to deload, when to stay quiet
• Signal priority — sleep > HRV trend > recovery score > strain
• Verbosity rules — only surface data when it changes the recommendation
• Multi-step workflows — morning check-in, pre-workout assessment, post-workout sync
• Biometric interpretation — recovery zones, HRV trends, sleep thresholds, strain budgets

Related Projects

• whoop-write-api — the underlying Python library for Whoop's reverse-engineered API
• SpotMe — self-hosted AI workout coach PWA that uses this MCP server

Development

git clone https://github.com/jd1207/whoop-write-mcp.git
cd whoop-write-mcp
pip install -e ".[dev]"
pytest

License

MIT