Skip to main content
Glama
Yadheedhya06

mcp-server-whoop

by Yadheedhya06
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

mcp-server-whoop

npm version CI CodeQL and secrets OpenSSF Scorecard license: MIT

A local-first, read-only Model Context Protocol server for WHOOP. It gives MCP-compatible AI clients compact recovery, sleep, strain, HRV, heart-rate, workout, and body-measurement signals without sending your WHOOP credentials through a hosted third party.

Why this server

  • Standard MCP over stdio, usable by any client that supports local MCP servers

  • Local WHOOP OAuth flow with each user's own WHOOP developer application

  • Access and rotating refresh tokens remain on the user's machine

  • Five focused read-only tools instead of a noisy API dump

  • Per-record local timestamps, so travel does not shift sleep or workout dates

  • Explicit processing status, with no older recovery substituted while a new sleep is pending

  • Score-derived metrics appear only for SCORED records; live current-cycle strain is labeled provisional_strain

  • Human-scale hours, minutes, calories, and heart-rate-zone minutes

  • No raw identifiers, OAuth secrets, or raw continuous heart-rate claims in tool output

  • No hosted relay, telemetry, database, generic HTTP tool, raw SQL, or install lifecycle scripts

  • Reproducible tarball security audit, CycloneDX SBOM, CodeQL, Gitleaks, dependency review, and OpenSSF Scorecard

This is an independent community project. It is not affiliated with or endorsed by WHOOP. WHOOP data is useful coaching context, not medical advice.

Related MCP server: whoop-mcp

Requirements

Quick start

  1. Create a WHOOP developer application and register http://127.0.0.1:8765/callback.

  2. Enable the five read scopes and offline listed below.

  3. Run npx -y mcp-server-whoop@0.2.2 auth in a terminal and approve WHOOP access.

  4. Run npx -y mcp-server-whoop@0.2.2 status to confirm the local grant exists.

  5. Add the stdio command npx -y mcp-server-whoop@0.2.2 to your AI client's MCP configuration.

  6. Restart or reload the client, then ask: Use WHOOP to summarize my recovery and sleep from the last 7 days.

The authorization command and the AI client must run as the same operating-system user, or both must set WHOOP_CREDENTIALS_FILE to the same private file. The package never asks you to paste WHOOP tokens into an AI conversation.

The documentation pins an exact reviewed version by default. Use @latest only if you explicitly want your client to follow future releases without reviewing them first.

1. Create your WHOOP application

Create an application in the WHOOP Developer Dashboard and register this exact redirect URL:

http://127.0.0.1:8765/callback

Enable these scopes:

offline
read:recovery
read:cycles
read:sleep
read:workout
read:body_measurement

offline is required because WHOOP access tokens expire and WHOOP rotates refresh tokens.

2. Authorize locally

Run:

npx -y mcp-server-whoop@0.2.2 auth

The command prompts for your WHOOP client ID and masks the client secret, opens WHOOP consent in your browser, validates the OAuth state, and saves the resulting grant locally.

Credentials are stored at:

~/.config/mcp-server-whoop/credentials.json

On Linux and macOS, every path ancestor is checked before use, the direct directory is current-user-owned with mode 0700, and the file is a single-link current-user-owned regular file with mode 0600. Override the path with WHOOP_CREDENTIALS_FILE only when every ancestor is trusted and is not a symlink.

Persistent OAuth credentials intentionally fail closed on native Windows. Node.js file modes do not enforce private Windows ACLs, and its standard file APIs cannot guarantee reparse-safe credential writes. Native Windows users can provide a short-lived WHOOP_ACCESS_TOKEN through the MCP process environment, but automatic authorization and refresh-token persistence require WSL, Linux, or macOS until a native credential backend is available.

For headless environments, provide WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET, and optionally WHOOP_REDIRECT_URI as environment variables before running auth.

The OAuth callback still needs to reach the machine running auth. When authorizing over SSH, create a loopback tunnel from your workstation first:

ssh -L 8765:127.0.0.1:8765 user@your-server

Then run auth in that SSH session and open its printed WHOOP URL in your workstation browser. Do not pass the client secret as a command-line argument because shell history and process listings may expose it.

Check setup without displaying secrets:

npx -y mcp-server-whoop@0.2.2 status

Remove the local grant:

npx -y mcp-server-whoop@0.2.2 logout

Revoking access in WHOOP account settings is also recommended when you no longer use an integration.

3. Add it to an AI client

Claude Desktop

Add this under mcpServers in Claude Desktop's configuration, then fully restart Claude Desktop:

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "mcp-server-whoop@0.2.2"]
    }
  }
}

Claude Code

claude mcp add --transport stdio whoop -- npx -y mcp-server-whoop@0.2.2

Cursor, Windsurf, Gemini Code Assist, and other mcpServers clients

Add the server to the client's MCP JSON. Gemini Code Assist uses ~/.gemini/settings.json; other clients choose their own settings path.

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "mcp-server-whoop@0.2.2"]
    }
  }
}

VS Code

Create .vscode/mcp.json for a project, or use VS Code's MCP: Add Server command:

{
  "servers": {
    "whoop": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-whoop@0.2.2"]
    }
  }
}

Codex

Either run:

codex mcp add whoop -- npx -y mcp-server-whoop@0.2.2

Or add this to ~/.codex/config.toml:

[mcp_servers.whoop]
command = "npx"
args = ["-y", "mcp-server-whoop@0.2.2"]

ChatGPT

Local Codex and ChatGPT desktop clients that support stdio can use the Codex configuration above. ChatGPT web does not launch a command on your computer; it requires a separately secured remote bridge or tunnel and a workspace plugin. This repository intentionally does not ship or operate a public health-data relay.

Client menus and configuration paths change over time. If a client supports standard local stdio MCP, the portable values are always:

command: npx
arguments: -y mcp-server-whoop@0.2.2

Confirm the connection

After restarting the client, confirm that it discovers exactly these five tools:

whoop_latest_overview
whoop_recovery_history
whoop_sleep_history
whoop_cycle_strain_history
whoop_workout_history

Useful prompts:

  • Use WHOOP to review today's recovery, latest sleep, current strain, and latest workout.

  • Compare my recovery, HRV, and resting heart rate over the last 14 days.

  • Show my last 7 days of sleep, including naps, and flag anything still processing.

  • Summarize my workout strain and heart-rate zones for the last 30 days.

  • Use WHOOP as context for today's training, but do not treat it as medical advice.

The model decides when to call tools, so explicitly say Use WHOOP when you want live data rather than a general answer.

Tools

Tool

Purpose

whoop_latest_overview

Current coaching snapshot with pending-data safeguards

whoop_recovery_history

Recovery, HRV, resting HR, SpO2, and skin-temperature trends

whoop_sleep_history

Primary sleep and optional naps, stages, need, quality, and timing

whoop_cycle_strain_history

Daily strain, calories, and average/max heart rate

whoop_workout_history

Sport, duration, strain, HR, calories, distance, and zone minutes

All tools are marked read-only, non-destructive, and idempotent.

Why deliberately only five tools?

For a health-data MCP, a larger tool count also means a larger capability surface. This server keeps authentication outside the agent and gives the model only the five health-reading capabilities it needs.

It intentionally has:

  • no WHOOP write, revoke, token-management, or authorization-code tools

  • no profile/email/name scope

  • no raw-record, raw-ID, arbitrary endpoint, SQL, file, or shell tool

  • no hosted OAuth relay, telemetry service, health-data cache, or database

  • no stale-recovery fallback when the newest sleep is still processing

The goal is not maximum WHOOP API coverage. It is the smallest practical authority boundary for recovery-aware AI.

Data semantics

WHOOP returns absolute timestamps plus a timezone_offset on sleep, cycle, and workout records. This server applies each record's own offset and returns only already-converted local timestamps such as:

2026-07-07 18:02:22 +04:00

It does not apply the machine's current timezone to historical records.

WHOOP exposes activity type and workout sport, but its public API does not indicate whether a workout was auto-detected or manually started. This server does not guess.

When the newest primary sleep is still PENDING_SCORE, the latest overview returns:

{
  "status": {
    "state": "waiting_for_whoop",
    "current_recovery_available": false
  },
  "recovery": null
}

An older recovery is never presented as current.

Environment variables

Variable

Purpose

WHOOP_CLIENT_ID

WHOOP OAuth client ID

WHOOP_CLIENT_SECRET

WHOOP OAuth client secret

WHOOP_REDIRECT_URI

OAuth callback, defaults to http://127.0.0.1:8765/callback

WHOOP_CREDENTIALS_FILE

Override local credential-file path

WHOOP_ACCESS_TOKEN

Optional short-lived access-token override

WHOOP_REFRESH_TOKEN

Optional refresh-token override

WHOOP_TOKEN_EXPIRES_AT

Optional ISO token-expiry override

Client configuration from WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET, and WHOOP_REDIRECT_URI overrides file values. Token environment variables can bootstrap a headless setup, but once a refresh token rotates, the newer token persisted in the credential file takes precedence. Do not put secrets directly in command-line arguments or commit them to source control.

Troubleshooting

Missing WHOOP ...

Run npx -y mcp-server-whoop@0.2.2 status as the same OS user that launches the AI client. If the credentials are elsewhere, set WHOOP_CREDENTIALS_FILE in the client's MCP environment.

WHOOP reports a redirect mismatch

The redirect in the Developer Dashboard and the value used by this package must match exactly. The default is http://127.0.0.1:8765/callback, including scheme, host, port, and path.

The browser does not open

Copy the authorization URL printed in the terminal and open it manually. The callback listener expires after five minutes; rerun auth if needed.

Port 8765 is already in use

Register another loopback URL such as http://127.0.0.1:9876/callback, set WHOOP_REDIRECT_URI to that exact value, and rerun auth.

Recovery is null

Check the returned status.state. If it is waiting_for_whoop or waiting_for_recovery, WHOOP has not finished scoring the newest sleep. The server intentionally refuses to label an older recovery as current; retry after WHOOP finishes processing.

The client shows no tools

Run npx -y mcp-server-whoop@0.2.2 --help in a terminal to verify Node.js and npm can launch the package, then restart the AI client and inspect its MCP logs. Do not run the bare server interactively to inspect output: stdio is reserved for MCP protocol messages.

Development

git clone git@github.com:Yadheedhya06/mcp-server-whoop.git
cd mcp-server-whoop
npm ci --ignore-scripts
npm run check

Run the local source server:

npm run dev

Build and inspect the exact npm artifact:

npm pack --dry-run

Privacy and security

This project publishes evidence rather than claiming that any package is perfectly safe. See the full security policy and reproducible security evidence.

  • Every user owns their WHOOP developer app and OAuth grant.

  • Credentials stay local and are never returned through MCP tools.

  • The package provides no WHOOP write, generic network, shell, filesystem, or raw API passthrough tool.

  • On supported POSIX storage, the credential file and every ancestor are checked against symlinks, unsafe ownership or permissions, oversized input, and unexpected fields. Refresh rotation uses a heartbeat lease that does not trust PIDs, an exclusive temporary file, atomic replacement, post-write verification, and disk sync. Native Windows persistence fails closed.

  • WHOOP and OAuth responses are size-bounded and structurally validated; provider response bodies are never copied into MCP errors.

  • Direct dependencies use exact versions. There are only two direct runtime dependencies and no package install lifecycle scripts.

  • CI runs the full test suite on Node 18, 20, 22, and 24, adds macOS and Windows platform-security jobs, audits both source and the exact compiled npm runtime, verifies npm registry signatures, and generates a CycloneDX SBOM.

  • Independent workflows run CodeQL, Gitleaks, dependency review, and OpenSSF Scorecard.

  • The publish workflow packs once and publishes that exact tarball through npm Trusted Publishing with Sigstore provenance. GitHub separately attests that tarball against its CycloneDX SBOM; no long-lived npm token is used.

These controls reduce risk, but they are not a paid penetration test or a guarantee. The limitations are documented explicitly in SECURITY-EVIDENCE.md.

License

MIT

Available Tools

4 tools
whoop_cycle_strain_historyGet WHOOP cycle strain historyA
Read-onlyIdempotent

Recent local physiological-cycle processing state and finalized metrics for SCORED records; a PENDING_SCORE current cycle may expose only provisional_strain.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoNumber of recent days to fetch, from 1 to 180

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
recordsYes
window_daysYes

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context about scoring states (SCORED vs PENDING_SCORE) and provisional data, which goes beyond the annotations to inform the agent about data completeness and reliability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that conveys the core purpose without redundancy. It is concise and front-loaded, using technical terms efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema and a single simple parameter, the description adequately covers the tool's context. It mentions recent data and scoring status, though the phrase 'processing state' could be slightly more explicit. Overall, sufficient for a read-only tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the days parameter fully described (type, range, default). The description does not add additional parameter semantics, but the baseline of 3 is appropriate since the schema already provides sufficient detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as providing cycle strain history with specifics about scored records and provisional strain for pending cycles. It distinguishes from sibling tools (overview, sleep, workout) by focusing on physiological cycle processing state and strain metrics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus siblings like whoop_latest_overview, whoop_sleep_history, or whoop_workout_history. The description lacks explicit context for selecting this tool over alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_latest_overviewGet latest WHOOP overviewA
Read-onlyIdempotent

Compact local-time coaching overview with newest sleep status, matching current recovery only when ready, finalized strain or explicitly provisional live current-cycle strain, latest workout, recent activity types, and body measurement.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
sleepYes
statusYes
recoveryYes
current_cycleYes
latest_workoutYes
body_measurementYes
recent_activitiesYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds that the overview is 'compact local-time' and includes provisional live data, but does not disclose additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense sentence that could be more readable. While concise, it packs many details without breaks, reducing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, rich annotations, and an output schema, the description lists all included components (sleep, recovery, strain, workout, activity types, body measurement). It adequately covers the overview context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and schema coverage is 100%. Baseline is 4; description does not need to compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides a compact coaching overview including sleep status, recovery, strain, workout, activity types, and body measurement. It differentiates from sibling tools that focus on specific history (sleep, cycle strain, workout).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The title 'latest overview' implies use for current latest info, contrasting with sibling history tools. However, there is no explicit when-to-use or when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_sleep_historyGet WHOOP sleep historyA
Read-onlyIdempotent

Recent local bedtime/wake time, sleep or nap type, processing state, and finalized sleep metrics only when WHOOP marks a record SCORED.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoNumber of recent days to fetch, from 1 to 180
include_napsNoInclude naps as well as primary sleep

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
recordsYes
window_daysYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds a key behavioral constraint: finalized metrics are only returned when WHOOP marks the record as SCORED. This goes beyond annotations and clarifies data availability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence (22 words) that front-loads core information. Every part is meaningful with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple parameters, presence of an output schema, and rich annotations, the description adequately covers the tool's behavior. It mentions the scored condition, which is critical. Minor omissions like processing state details are likely covered by the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully describes both parameters (days range, include_naps boolean) with 100% coverage. The tool description does not add parameter-level information, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves WHOOP sleep history with specific fields (bedtime, wake time, type, state, metrics) and distinguishes from sibling tools like cycle strain or workout history by focusing on sleep. The title reinforces the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is provided. However, the purpose and sibling names imply this is for sleep history queries. The description does not mention alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

whoop_workout_historyGet WHOOP workout historyA
Read-onlyIdempotent

Recent workout sport, local time, duration, and processing state, with score-derived metrics only when WHOOP marks a record SCORED.

ParametersJSON Schema
NameRequiredDescriptionDefault
daysNoNumber of recent days to fetch, from 1 to 180

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
recordsYes
window_daysYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint true and destructiveHint false. The description adds value by noting that score-derived metrics are only present when WHOOP marks a record as SCORED, which is a behavioral detail beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that conveys all necessary information without redundancy. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (not shown but present) and describes the returned fields adequately, the description is complete. It covers the key aspects for an agent to understand what the tool returns and its conditional behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter 'days' already has a clear description in the schema. The tool description does not add additional semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it returns recent workout history with specific fields (sport, local time, duration, processing state, conditional score metrics). This distinctly sets it apart from sibling tools like whoop_sleep_history or whoop_cycle_strain_history.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for retrieving workout history but does not explicitly specify when to choose this over siblings (e.g., whoop_latest_overview for overview or whoop_sleep_history for sleep data). No when-not or alternative guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.2.2
    • Removedwhoop_recovery_history
  2. 5 tool updatesv0.1.0
    • First observedwhoop_cycle_strain_history
    • First observedwhoop_latest_overview
    • First observedwhoop_recovery_history
    • First observedwhoop_sleep_history
    • First observedwhoop_workout_history
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool targets a distinct WHOOP data domain: overall overview, sleep history, cycle strain history, and workout history. There is no overlap in purpose, making it easy for an agent to select the correct tool.

Naming Consistency5/5

All tool names follow a consistent pattern: 'whoop_' followed by a descriptive noun phrase (e.g., latest_overview, sleep_history). The naming is uniform and predictable.

Tool Count5/5

With 4 tools, the server covers the core WHOOP data categories (overview, sleep, cycle strain, workouts) without unnecessary bloat. The count is well-scoped for a focused integration.

Completeness4/5

The tool set covers the most commonly accessed WHOOP data types. However, it lacks dedicated tools for specific metrics like HRV or recovery details, though the overview tool may subsume some of these. Minor gap for a comprehensive read-only surface.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Yadheedhya06/mcp-server-whoop'

If you have feedback or need assistance with the MCP directory API, please join our Discord server