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"

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

First tool call checks for cached tokens at ~/.whoop/tokens.json
No tokens? Auto-authenticates from WHOOP_EMAIL/WHOOP_PASSWORD env vars if set
No env vars? Returns a clear error: "Run whoop-write-mcp login in your terminal"
Tokens cached (0600 permissions), auto-refresh on expiry
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

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