How to connect a WHOOP MCP to Cursor (4 steps)

When you're writing a recovery scoring system, implementing strain thresholds, or modeling sleep stage transitions, you need to know what WHOOP's API actually returns: exact field names, value ranges, data types, and the shape of nested objects.

That information is only available by running API calls outside Cursor, copying results back in, and hoping the response structure you captured matches what production traffic delivers.

To help your developers easily access WHOOP's physiological data without leaving Cursor, we'll show you how to connect WHOOP with Merge Agent Handler's WHOOP MCP server.

How it works

Merge Agent Handler connects Cursor to the WHOOP API through the Merge CLI.

Install the CLI, authenticate once, and run a single setup command from your project root. That command writes a ## Merge CLI section to the project's .cursorrules file, which tells Cursor's agent when to call merge search-tools and merge execute-tool to reach WHOOP.

Once authenticated, Merge handles WHOOP OAuth credentials and token refresh so you never store access tokens locally or manage authorization state in the project.

The registration command:

merge setup cursor

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Cursor installed
• 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

Install with pipx and verify: pipx install merge-api


Verify your installation: merge --version

Related: How to use a WHOOP MCP in Claude Code

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your account so it can make authorized requests to WHOOP on your behalf.

3. Connect the CLI to Cursor

Run the following from the root of the project where you want to use Merge tools:

merge setup cursor

This writes a ## Merge CLI section to .cursorrules so Cursor knows to use the CLI for third-party services. The command is idempotent, so it's safe to re-run if you need to reset.

4. Authenticate WHOOP

Open a Cursor chat in your project and run a query that reflects real development work. For example, you can ask something like "Fetch my most recent WHOOP recovery record and show me the full JSON response, including all field names and their value types, so I can write an accurate TypeScript interface for the data model."

The first time you invoke a WHOOP tool, a Magic Link will appear to complete connector authentication.

{{this-blog-only-cta}}

WHOOP MCP FAQ

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

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

With WHOOP connected, Cursor can:

• Inspect recovery record schemas while writing data models: fetch a live recovery response to see the exact field structure before writing TypeScript interfaces or Pydantic schemas, so your type definitions match what the API actually returns rather than what documentation describes

• Pull real sleep session data while coding parsers: retrieve actual sleep records with stage breakdowns and respiratory rate fields to verify your parser logic against real response shapes before writing unit tests against synthetic fixtures

• Check strain score ranges while implementing recommendation thresholds: query recent workout records to see what strain values look like across a real training history, informing the constants and boundary values you code into recommendation logic

• Fetch physiological cycle data while building aggregation functions: pull multi-day cycle records to validate the time-series structure your aggregation or windowing functions need to handle correctly

• Retrieve body measurements to anchor relative calculations: access baseline profile data including max heart rate mid-session to write and test normalization logic against real values before deploying against user data

• Verify nested object shapes before modeling linked records: query endpoints that return linked objects (sleep linked to cycle, for example) to understand the actual nesting depth before you define it in code

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

Building directly on WHOOP's API is the right starting point for a single-developer prototype. WHOOP's developer portal at developer.whoop.com documents the OAuth 2.0 flow, the endpoints are well-scoped, and for a personal project or proof of concept the setup takes under an hour.

The challenge arrives when the application supports multiple users.

WHOOP issues per-user access tokens with expiration dates. Every connected user needs their own authorization flow, their own refresh cycle, and their own error handling for revoked or expired credentials. A failed token refresh silently breaks data access for that user, and tracking token health across dozens of accounts with no central view of which connections are active becomes operational work that compounds as users grow.

A self-hosted MCP server doesn't solve this. You still own the OAuth plumbing for every connected user, and now you're also maintaining the server itself.

WHOOP also doesn't publish an official MCP server, so any community implementation comes with no guarantees on maintenance cadence, API coverage, or enterprise support.

Merge Agent Handler solves this by centralizing credential management and handling token refresh for all connected users.

You can scope exactly which WHOOP tools each agent can call. An agent that generates daily readiness summaries, for instance, gets access to recovery and sleep tools, not body measurement endpoints, unless those are explicitly included. Every tool call is also logged.

For applications where users share sensitive physiological data with an agent, the combination of scoped access and audit logging is the baseline for a responsible deployment.

Why connect WHOOP to Cursor?

WHOOP's API returns structured physiological data that health and fitness integrations depend on: recovery scores with HRV and resting heart rate, sleep sessions with stage breakdowns, workout records with strain calculations.

For developers building against that API in Cursor, the reference data you need to write correct code sits outside the editor.

Connecting WHOOP to Cursor means you can query real API responses from within a chat session while writing the code that consumes them.

You're not working from documentation that may lag the actual API behavior. And you're not switching to Postman, running a test call, copying the JSON, and switching back.