How to connect a WHOOP MCP with Claude Code (4 steps)

Developers building personalized training apps, corporate wellness platforms, or AI health agents need WHOOP data, but accessing it means managing OAuth 2.0 authorization flows, handling per-user token refresh, and writing WHOOP-specific API clients before any agent logic can be built.

To help your developers pull recovery, sleep, and workout data from WHOOP within their terminal, we'll show you how to connect it with Merge Agent Handler's WHOOP MCP server.

How it works

Merge Agent Handler connects Claude Code to the WHOOP API through a single CLI setup.

You install the Merge CLI, authenticate once with your Merge Agent Handler account, and register the connection with one command.

Merge manages WHOOP's OAuth credentials and handles token refresh on your behalf, so you never store access tokens locally or write code to handle expiration.

Here's the command that registers the connection:

claude mcp add 
--transport http agent-handler https://ah-api.merge.dev/mcp

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Claude Code installed (run claude --version to confirm)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A WHOOP account with API access (register your app at developer-dashboard.whoop.com)

If you want to connect Merge Agent Handler's WHOOP MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Run the following to install the Merge CLI: pipx install merge-api

Then verify the installation: merge --version

2. Configure the CLI and log in

Run the interactive setup: merge configure

This prompts you for your Merge API key and links the CLI to your Merge Agent Handler account, setting your default workspace preferences.

Login with merge login. This authenticates your session so the CLI can make authorized requests on your behalf going forward.

3. Add Agent Handler to Claude Code

Register the Agent Handler MCP server with Claude Code:

claude mcp add 
--transport http agent-handler https://ah-api.merge.dev/mcp

Open Claude Code and run: /mcp

agent-handler should appear under Local MCPs with a connected status.

4. Authenticate WHOOP

Select agent-handler from the MCP list.

This opens a browser window where you select which integrations to authenticate. Choose WHOOP and complete the OAuth flow. Merge stores and manages the credentials going forward, including handling token refresh so your connection stays live without maintenance on your end.

The first time you use a WHOOP tool in a Claude Code session, a Magic Link may appear to complete connector authentication.

Once authenticated, you won't need to re-authenticate unless you revoke access.

To confirm the connector is accessible, open a Claude Code session and run a command like "Pull my recovery score, HRV, and resting heart rate from the last 7 days and summarize any trends."

You should see an output like the following:

{{this-blog-only-cta}}

WHOOP MCP FAQ

In case you have more questions on setting up and using the WHOOP MCP in Claude Code, we've addressed several more commonly-asked questions below.

What can you do once the WHOOP MCP is connected to Claude Code?

With WHOOP connected, Claude Code can:

• Retrieve recovery data: pull daily recovery scores including HRV, resting heart rate, and SpO2 readings, giving agents the physiological context needed to make training or readiness recommendations

• Access sleep breakdowns: fetch sleep sessions with full stage data including time in REM, slow-wave sleep, and light sleep, along with respiratory rate metrics for each session

• Query workout history: retrieve past workouts with strain scores, duration, and heart rate data, enabling agents to track cumulative training load and flag overreach patterns

• Fetch physiological cycles: read daily cycle records that contextualize recovery and strain within WHOOP's full activity model, useful for multi-day trend analysis

• Cross-reference sleep and cycle data: pull sleep records linked to specific cycles to analyze how individual sleep sessions contribute to daily recovery scores

• Get user and body profile: access baseline profile data including height, weight, and max heart rate, which anchors relative metrics like strain calculations to individual physiology

Why use Merge Agent Handler vs. building directly on the WHOOP API?

You can build directly on WHOOP's developer API. The OAuth 2.0 flow is documented at developer.whoop.com, the endpoints cover the same physiological data, and for a single-user prototype the setup is straightforward.

The challenge is scale.

WHOOP's API uses user-level OAuth tokens. Every user in your application needs their own authorization flow, their own token pair, and their own refresh cycle. At a few dozen users, writing the refresh logic and storing tokens securely is manageable. At hundreds, a failed refresh silently breaks data access for that user, and you're tracking a token lifecycle for every active account with no centralized view of which connections are healthy.

A self-hosted MCP server on top of WHOOP's API doesn't solve this.

You still own the OAuth plumbing, and you add the operational responsibility of keeping the MCP server itself running, versioned, and secure. WHOOP doesn't offer an official MCP server, so any alternative is a community implementation with no guaranteed maintenance or enterprise support.

Merge Agent Handler handles the OAuth credential layer for all connected users and manages token refresh automatically.

You can scope exactly which WHOOP tools a given agent can call: an agent built for daily readiness, for example, can invoke list_recoveries and list_sleep_activities, but never reach get_body_measurements unless that tool is explicitly included. Every call is also logged with the timestamp, tool name, and inputs.

Why connect WHOOP to Claude Code?

WHOOP produces a category of data that's otherwise unavailable without a wearable integration: resting heart rate, HRV, sleep stage percentages, daily strain scores, and more. These inputs make personalized health recommendations genuinely personalized rather than generic.

Developers who need this data today either build and maintain their own WHOOP OAuth integration or prompt users to manually enter metrics the device is already tracking automatically. Neither scales.

With the WHOOP MCP connected, Claude Code can query recovery trends, pull sleep breakdowns, and cross-reference workout load without leaving the terminal. This matters most when an agent needs physiological context before taking action, whether that's generating a training plan, surfacing a recovery alert, or building a weekly health summary that reflects real data rather than self-reported estimates.