Whoop MCP Server

Your WHOOP data in whichever AI you use, or, soon, in your own code. Self-hosted, private, and open source.

Ask Claude, ChatGPT or another MCP app "How did I sleep this week?" and get the answer from your own recovery, sleep, strain and workouts. You run the server yourself: it fetches your data from WHOOP when you ask and keeps no copy, and only the apps you've allowed can reach it.

This is an independent open-source project. It uses the WHOOP API to access data from WHOOP products, and is not affiliated with, endorsed by, or sponsored by WHOOP.

Two ways in

• Talk to your data. Deploy the server, connect it to your AI, and ask. Start with Setup, then Add to your AI, which also lists the apps tested so far.
• Build with it. The WHOOP client inside this server (typed, tested, and careful with WHOOP's single-use refresh tokens) is being split out as a library for your own code. It isn't published yet: watch this repository's releases to hear when it is.

Built on the Whoop Developer API v2, and the Model Context Protocol (MCP), the open standard AI apps use to call tools like these.

Features

• Recovery: daily recovery score, HRV, resting heart rate, SpO2, skin temperature
• Sleep: duration, stages, efficiency, performance, respiratory rate
• Strain: daily strain score and calories burned
• Workouts: activity, local start time, duration, strain, heart rate, calories, and time in heart-rate zones 4–5
• Live data: every answer is fetched from Whoop when you ask, so it's always current. The server stores only its sign-ins and your encrypted Whoop tokens, never your health data
• Private by default: each app signs in with a password you choose (OAuth 2.1), and only after you tick a box allowing it, so nobody else can read your data
• Your choice of AI: tested live with Claude and ChatGPT; other apps that sign in with OAuth should work the same way (see compatibility)

MCP Tools

Setup

1. Create a Whoop Developer App

1. In the Whoop Developer Dashboard, create an app and fill in:
   • Contacts: your email. Only Whoop sees it.
   • Privacy Policy: this project's PRIVACY.md, https://github.com/yuridivonis/whoop-mcp-server/blob/main/PRIVACY.md, or your own adapted copy if you run the server for someone else. People see this link when they approve the app.
   • Redirect URL: your server's callback, e.g. https://your-app.up.railway.app/callback. If you don't have the address yet, fill this in after step 2 creates it.
   • Scopes: read:recovery, read:cycles, read:sleep, and read:workout. The server doesn't use the others. The login also asks for offline, which lets the server renew its Whoop access without you logging in again; the dashboard doesn't list it.
   • Webhooks: leave empty.
2. Note your Client ID and Client Secret.

2. Deploy

Every release is published as a ready-made image, ghcr.io/yuridivonis/whoop-mcp-server. Deploy that: there's no need to fork this repository unless you want to change the code (see Changing the code). The steps below use Railway; to run it anywhere else, see Docker.

1. In a Railway project, click New, choose Docker Image, and enter ghcr.io/yuridivonis/whoop-mcp-server:1.4.1. Then, in the service's Settings → Networking → Public Networking, choose Generate Domain: that's your server's address, your-app.up.railway.app below.
2. Add environment variables:
   • WHOOP_CLIENT_ID: Your Whoop app client ID
   • WHOOP_CLIENT_SECRET: Your Whoop app client secret
   • WHOOP_REDIRECT_URI: https://your-app.up.railway.app/callback
   • MCP_AUTH_PASSWORD: the password each AI app asks for when you connect it. Generate one with openssl rand -base64 24 and keep it in your password manager. The server refuses to start without it (at least 16 characters).
   • ENCRYPTION_SECRET (optional, recommended): generate one with openssl rand -base64 32. It encrypts your stored Whoop tokens, so rotating the Whoop client secret later won't disconnect your account.
3. Add a volume mounted at /data. It holds the sign-ins and your encrypted Whoop tokens; without it, every redeploy signs your apps out and disconnects Whoop.
4. Turn on updates: in the service's Settings, under Source, choose Configure Auto Updates, pick minor updates and patches, and a maintenance window (for example Night). Railway then moves the service to each new 1.x release by itself, and on the Pro plan backs up the volume first.
5. Deploy, then open https://your-app.up.railway.app/health to check it's running.

Already running a fork on Railway? Switch it to the image: open the service's Settings, change Service Source to ghcr.io/yuridivonis/whoop-mcp-server:1.4.1, and turn on auto updates as in step 4. Keep the same variables and volume, so Whoop stays connected. If your fork is older than 1.3.0, read Upgrading to 1.3.0 first: every app signs in once more. Your fork is then no longer used.

3. Connect your AI

Add your server's address, https://your-app.up.railway.app/mcp, to your AI app as a custom connector. It opens your server's sign-in page: check it names the app you're connecting, enter your MCP_AUTH_PASSWORD, and tick the box allowing it to read your Whoop data. For example, in Claude.ai: Customize → Connectors → + → Add custom connector.

Add to your AI has the steps for Claude, ChatGPT, Claude Code, Cursor, VS Code and Windsurf, and which have been tested. Apps stay signed in across redeploys; anyone without the password gets 401 Unauthorized from /mcp.

4. Connect your Whoop account

1. In a chat, ask your AI to connect Whoop. It calls get_auth_url and gives you a link.
2. Open the link, log in to Whoop, and authorize the app. You're redirected back, and your AI can answer right away.
3. Ask away: "How did I sleep last night?"

Upgrading to 1.3.0

1.3.0 stops keeping a copy of your Whoop data, and asks you before each app receives it. To upgrade:

1. Get the new version: with the image, Railway's auto updates do it for you, or change the tag under Service Source to the new version (Docker with :1: pull it again and restart). With a fork, use GitHub's Sync fork button, then redeploy, or switch to the image as described in Deploy.
2. On its first start, the server deletes the recovery, sleep, strain and workout data earlier versions stored, and rewrites the database file so none of it is left on disk. Your Whoop connection is kept. The log says Deleted the WHOOP data stored by an earlier version.
3. Every app is signed out once. The next time you use one, it opens the sign-in page: enter your password and tick the box allowing it to read your Whoop data.
4. sync_data is gone. If your app still lists it, remove the connector and add it again.
5. If your host keeps backups or snapshots of the volume, delete the ones from before the upgrade. They still hold the old copy.

There's no going back to 1.2.x on the upgraded database: it can't sign apps in with the new sign-in tables.

Upgrading from 1.0.0

1.1.0 puts a sign-in in front of /mcp. Version 1.0.0 had no authentication there, so any 1.0.0 server that worked with Claude over HTTP served its data to anyone who knew the URL. (Unmodified 1.0.0 also had a request-parsing bug that stopped Claude from connecting over HTTP at all; 1.1.0 fixes both.) To upgrade:

1. Update your fork (GitHub's Sync fork button, or merge the upstream main branch), or switch the service to the image as described in Deploy.
2. Set MCP_AUTH_PASSWORD in your Railway variables (see Setup, step 2). Without it, the new version won't start. That's deliberate.
3. Redeploy.
4. In Claude.ai → Settings → Connectors, remove the Whoop connector and add it again with the same URL. Claude shows the sign-in page once.
5. If a tool says your Whoop authorization expired, run get_auth_url once to reconnect.
6. Optional: in your Whoop app, untick read:profile and read:body_measurement. 1.1.0 no longer uses them.