whoop-mcp

whoop-mcp

A Model Context Protocol (MCP) server that gives Claude access to your WHOOP biometric data — recovery, sleep, strain, and workouts.

Ask Claude things like:

• "How's my recovery today?"
• "How did I sleep last night?"
• "How has my HRV trended this week?"
• "What was my strain from yesterday's workout?"

---

Privacy

This app accesses your WHOOP data locally on your device. No data is sent to any third-party server.

---

Tools

Tool	What it returns
get_recovery	Recovery score, HRV, resting HR, SpO2
get_sleep	Sleep duration, stages (light/deep/REM), efficiency, respiratory rate
get_strain	Day strain score, avg/max HR, calories
get_latest_workout	Most recent workout — sport, duration, strain, HR zones
get_recovery_trend	Recovery scores over N days (default 7)
get_sleep_trend	Sleep data over N days (default 7)
get_workout_history	Recent workout history (default 5)
get_profile	Profile + body measurements

---

Setup

1. Create a WHOOP developer app

1. Go to developer-dashboard.whoop.com
2. Sign in with your WHOOP account
3. Create a new App:
   • Name: whoop-mcp (or anything)
   • Redirect URI: http://localhost:8080/callback
   • Scopes: select all read scopes + offline
4. Copy your Client ID and Client Secret

2. Install

npm install -g @souravpn/whoop-mcp

3. Run one-time auth setup

This opens your browser, you log into WHOOP, and your tokens are saved to ~/.whoop-mcp-tokens.json:

WHOOP_CLIENT_ID=your_id WHOOP_CLIENT_SECRET=your_secret whoop-mcp-auth-setup

You only need to do this once. The server will auto-refresh tokens after that.

4. Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "whoop": {
      "command": "@souravpn/whoop-mcp",
      "env": {
        "WHOOP_CLIENT_ID": "your_client_id",
        "WHOOP_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Restart Claude Desktop. You should see a green "running" badge in Settings → Developer.

5. Test it

Open a new chat and ask:

How's my recovery today?

---

Example queries

Daily check-in:

What's my recovery, sleep, and strain for today?

Trend analysis:

How has my HRV trended over the past 7 days?

Workout correlation:

Look at my workouts this week and my recovery scores
the day after each one. Is there a pattern?

Full briefing:

Give me a complete health briefing — recovery, last
night's sleep breakdown, and any workouts from yesterday

---

Pairing with Oura

If you also use Oura Ring, you can run both MCP servers together and ask Claude to cross-reference:

{
  "mcpServers": {
    "whoop": {
      "command": "/path/to/whoop-mcp",
      "env": { "WHOOP_ACCESS_TOKEN": "your_whoop_token" }
    },
    "oura": {
      "command": "/path/to/oura-mcp",
      "env": { "OURA_ACCESS_TOKEN": "your_oura_token" }
    }
  }
}

Then ask:

Compare my WHOOP and Oura HRV readings for this week.
Do they agree? Which is trending higher?

---

Development

git clone https://github.com/yourusername/whoop-mcp
cd whoop-mcp
npm install
npm run build

# Test locally
WHOOP_ACCESS_TOKEN=your_token node dist/index.js

Project structure

whoop-mcp/
├── src/
│   ├── index.ts   # MCP server + tool definitions
│   └── whoop.ts   # WHOOP API client + formatters
├── package.json
├── tsconfig.json
└── README.md

---

Contributing

PRs welcome. Some ideas for extension:

• Heart rate time series data
• Sleep stage timeline (light/deep/REM per hour)
• Strain goal recommendations
• Weekly summary tool

---

License

MIT

---

Acknowledgements

Built with the MCP TypeScript SDK and the WHOOP Developer API.