English Français العربية

io.github.souravpn/whoop-mcp

Official registry Health

MCP server for WHOOP — gives Claude access to your recovery, sleep, strain, and workout data

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @souravpn/whoop-mcp
Claude Code 
claude mcp add whoop-mcp -e 'WHOOP_CLIENT_ID=<WHOOP_CLIENT_ID>' -e 'WHOOP_CLIENT_SECRET=<your whoop_client_secret>' -- npx -y @souravpn/whoop-mcp@1.0.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "whoop-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@souravpn/whoop-mcp@1.0.1"
            ],
            "env": {
                "WHOOP_CLIENT_ID": "<WHOOP_CLIENT_ID>",
                "WHOOP_CLIENT_SECRET": "<your whoop_client_secret>"
            }
        }
    }
}

Environment variables

  • WHOOP_CLIENT_ID required OAuth2 Client ID from your WHOOP developer app at developer-dashboard.whoop.com
  • WHOOP_CLIENT_SECRET required secret OAuth2 Client Secret from your WHOOP developer app. Run whoop-mcp-auth-setup once to complete OAuth flow.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. whoop-mcp
  2. Privacy
  3. Tools
  4. Setup
  5. Example queries
  6. Pairing with Oura
  7. Development
  8. Contributing
  9. License
  10. Acknowledgements

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

ToolWhat it returns
get_recoveryRecovery score, HRV, resting HR, SpO2
get_sleepSleep duration, stages (light/deep/REM), efficiency, respiratory rate
get_strainDay strain score, avg/max HR, calories
get_latest_workoutMost recent workout — sport, duration, strain, HR zones
get_recovery_trendRecovery scores over N days (default 7)
get_sleep_trendSleep data over N days (default 7)
get_workout_historyRecent workout history (default 5)
get_profileProfile + 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.

Frequently asked questions

What is io.github.souravpn/whoop-mcp?

MCP server for WHOOP — gives Claude access to your recovery, sleep, strain, and workout data

How do I install io.github.souravpn/whoop-mcp?

It runs on your machine. In Claude Code: claude mcp add whoop-mcp -e 'WHOOP_CLIENT_ID=<WHOOP_CLIENT_ID>' -e 'WHOOP_CLIENT_SECRET=<your whoop_client_secret>' -- npx -y @souravpn/whoop-mcp@1.0.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.souravpn/whoop-mcp need an API key?

Yes. It expects WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET, which you set in its configuration.

Is io.github.souravpn/whoop-mcp open source?

Its code is public on GitHub, but the repository does not declare a standard license.

Who maintains io.github.souravpn/whoop-mcp?

It is published by souravpn. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.