Skip to main content
Glama
shivamshashikant

whoop-mcp

by shivamshashikant
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

whoop-mcp

What this is

A small server that runs on your own computer and lets Claude read your own WHOOP data: profile, recovery, sleep, workouts and daily cycles. It also includes a weekly_review prompt and a profile resource.

It follows the Model Context Protocol (MCP), the standard way Claude connects to outside tools.

This is a learning experiment. It is read-only, so it can't change anything in your WHOOP account. It is not affiliated with WHOOP or Anthropic.

Related MCP server: whoop-mcp

Privacy warning

This project handles personal health data.

  • Each person must use their own WHOOP developer app and their own WHOOP account.

  • Your credentials and tokens stay on your own machine.

  • Never commit or share .env or tokens.json. They give access to your WHOOP data. Both are already listed in .gitignore.

Requirements

  • Node.js 18 or higher

  • A WHOOP account

  • A WHOOP developer app (free, created at the WHOOP developer dashboard)

  • Claude Desktop

Setup

  1. Clone this repository and open a terminal in its folder.

  2. Run npm install.

  3. Create a WHOOP developer app in the WHOOP developer dashboard. Register this redirect URI exactly: http://localhost:3000/callback. Note the Client ID and Client Secret.

  4. Copy .env.example to .env and fill in the values:

    WHOOP_CLIENT_ID=your client id
WHOOP_CLIENT_SECRET=your client secret
WHOOP_REDIRECT_URI=http://localhost:3000/callback

  5. Run npm run auth. It prints a login link. Open it in your browser, approve access, and wait for "Login successful". This creates tokens.json.

  6. Run npm run build.

Connect to Claude Desktop

Open Claude Desktop's config file (Settings > Developer > Edit Config) and add this block. Replace the path with the full path to this project's dist/index.js on your machine:

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/full/path/to/whoop-mcp/dist/index.js"]
    }
  }
}

On Windows, backslashes in the path must be doubled, for example C:\\Users\\you\\whoop-mcp\\dist\\index.js.

Then fully quit Claude Desktop (right-click its icon in the system tray and choose Quit, since closing the window isn't enough) and open it again.

Available tools, prompts and resources

Tools

  • ping: replies "pong"; use it to check the connection.

  • get_profile: your basic WHOOP profile.

  • get_recovery: daily recovery score, HRV and resting heart rate.

  • get_sleep: sleep performance, duration, efficiency and time in each stage.

  • get_workouts: sport, duration, strain and heart rate for each workout.

  • get_cycles: daily strain and average heart rate.

The four data tools take an optional days value (1 to 30, default 7).

Prompts

  • weekly_review: asks Claude to fetch your recent data and write a short review with one suggested change for next week. Optional days (default 7).

Resources

  • whoop://profile/summary: your WHOOP user ID and name, fetched live. It doesn't include your email.

Troubleshooting

  • Server doesn't show up in Claude: fully quit Claude Desktop from the tray and reopen it. Also check that the path in the config is correct.

  • 401 or "unauthorized" errors: your login has expired or was revoked. Run npm run auth again.

  • dist folder missing or "cannot find module": run npm run build.

  • Port 3000 already in use during npm run auth: close whatever is using port 3000 and try again. If you'd rather use another port, change it in the redirect URI in both .env and the WHOOP developer dashboard.

Notes

  • WHOOP rotates refresh tokens: each one works only once. The app rewrites tokens.json after every refresh, so don't delete or edit that file while it's running.

  • The offline scope, which allows refreshing, is requested in the login link that npm run auth generates. You don't need to set it in the WHOOP dashboard.

Available Tools

6 tools
get_cyclesA

Returns daily physiological cycles (day strain and average heart rate) for the last N days. Use it to see overall daily strain. strain is 0-21 on Whoop's logarithmic scale (0-9 light, 10-13 moderate, 14-17 high, 18-21 all-out); the latest cycle may still be in progress.

NameRequiredDescriptionDefault
daysNoHow many days back to fetch, from 1 to 30 (default 7).

TDQS

A3.6/5.0
Behavior3/5

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

With no annotations, the description carries full behavioral burden. It usefully discloses domain semantics (the 0–21 strain scale) and that the latest cycle may still be in progress, but it does not state read-only behavior, permissions, or return shape beyond the two fields.

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?

Two sentences, front-loaded with the core return value before the usage note and domain scale. Every sentence adds useful information without repetition.

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?

For a single-parameter read tool with no output schema and no annotations, the description covers the essential purpose, domain interpretation, and an in-progress caveat. Only minor gaps remain, such as not distinguishing it from sibling physiological tools.

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%, so the days parameter is already fully documented with min/max/default. The description's 'last N days' adds no new syntax or format detail beyond the schema.

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

Purpose4/5

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

States a specific verb and resource: returns daily physiological cycles with day strain and average heart rate for the last N days. This clearly identifies the tool's function, but it does not explicitly distinguish it from siblings like get_recovery or get_sleep, which also return physiological data.

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 sentence 'Use it to see overall daily strain' gives an implied use case, but there is no explicit guidance on when to choose this over get_recovery/get_workouts or when not to use it.

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

get_profileA

Returns the user's basic Whoop profile (user id, name, email). Use it to identify whose data is being read.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

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

No annotations are provided, so the description must carry the full behavioral burden. 'Returns' implies a read, and the description names three fields, but it does not disclose authentication requirements, whether the call is rate-limited, or what happens on failure. For a simple zero-parameter getter this is adequate but shallow.

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?

It is two short sentences with no wasted words. The purpose comes first, then the usage note, so the key information is front-loaded.

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?

Because there is no output schema, the description must sketch the return value, and naming user id, name, and email does that. It is complete enough to call the tool correctly, though it does not say whether more fields might come back or how the call behaves without auth.

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?

The tool accepts no parameters, so there is nothing for the description to disambiguate. That puts it at the baseline of 4, and no parameter text is missing.

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

Purpose4/5

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

The description uses a specific verb ('Returns') plus a specific resource ('the user's basic Whoop profile') and enumerates the fields returned (user id, name, email). This clearly distinguishes it from the sibling data tools (get_recovery, get_sleep, get_workouts, get_cycles), though it does not name a sibling explicitly.

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 sentence 'Use it to identify whose data is being read' gives a concrete situation in which to call the tool, which is exactly the agent's decision point. It does not state when not to call it or name an alternative, which keeps it short of a 5.

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

get_recoveryA

Returns daily recovery records (recovery score, HRV, resting heart rate, SpO2, skin temperature) for the last N days. Use it to see how recovered the user is. recovery_score_pct is 0-100% (0-33 red/low, 34-66 yellow/medium, 67-100 green/high).

NameRequiredDescriptionDefault
daysNoHow many days back to fetch, from 1 to 30 (default 7).

TDQS

A3.6/5.0
Behavior3/5

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

No annotations are provided, so the description carries the full burden. It implies a read-only retrieval operation and usefully explains the recovery score bands, but it does not disclose permissions, rate limits, ordering, or other behavioral traits beyond the returned fields.

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?

Two front-loaded sentences with no waste. The first sentence states what is returned; the second gives a practical interpretation for the recovery score, and both earn their place.

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?

For a simple one-parameter read tool with no output schema, the description is nearly complete: it lists the returned metrics and explains the score scale. Minor gaps remain around record ordering and date-boundary behavior, but nothing essential is missing.

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 description coverage is 100%: the single `days` parameter is already documented with range and default. The description adds only the "last N days" framing, which is consistent with the schema but not materially beyond it.

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

Purpose4/5

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

The description states a specific verb and resource: returns daily recovery records, and names the key metrics included. It is clear what the tool does, though it does not explicitly differentiate itself from siblings such as get_sleep or get_workouts.

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 phrase "Use it to see how recovered the user is" implies the intended use case, but there is no explicit guidance on when not to use it or which sibling tool to choose instead. The usage context is adequate but not operationalized.

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

get_sleepA

Returns sleep records (performance, duration, efficiency, time in each stage) for the last N days, including naps. Use it to analyze sleep quality and habits. sleep_performance_pct is 0-100% (actual sleep vs. sleep needed); efficiency is the share of time in bed spent asleep. Summary stats exclude naps.

NameRequiredDescriptionDefault
daysNoHow many days back to fetch, from 1 to 30 (default 7).

TDQS

A4/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does disclose meaningful data semantics: naps are included in the records but excluded from summary stats, and it defines sleep_performance_pct and efficiency. It omits whether aggregation/summary fields appear at all and any permission or scope constraints, but the exclusion rule is genuinely useful context beyond structured fields.

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?

Two sentences, front-loaded with what is returned, then metric definitions and the nap-exclusion caveat. Every sentence adds information an agent cannot get from the schema.

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?

No output schema exists, so the description must characterize returns, and it lists the metric families and the nap rule. It stops short of describing record-level shape (per-night vs aggregate, units, timezone), which leaves a modest gap for an agent composing downstream logic.

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 'days' parameter is already documented with range and default. The description only restates 'last N days' and adds that naps are included; baseline 3 is appropriate since the schema does the work.

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?

States a specific verb and resource ('Returns sleep records') and enumerates exactly what is included: performance, duration, efficiency, time in each stage, plus naps. Against siblings like get_recovery and get_workouts, the domain is unambiguous from the first clause.

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?

'Use it to analyze sleep quality and habits' gives an implied use case but does not say when to prefer it over get_recovery or get_workouts, nor any exclusions. Usage is inferred rather than directed.

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

get_workoutsA

Returns workout records (sport, duration, strain, average and max heart rate) for the last N days. Use it to review training activity. strain is 0-21 on Whoop's logarithmic scale (0-9 light, 10-13 moderate, 14-17 high, 18-21 all-out).

NameRequiredDescriptionDefault
daysNoHow many days back to fetch, from 1 to 30 (default 7).

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description carries the behavioral burden. It helpfully lists returned fields and explains the 0-21 strain scale, but it does not explicitly state read-only behavior, permissions, empty-result behavior, or rate limits. It is adequate but has clear gaps.

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 front-loaded with purpose and return fields, then adds only relevant interpretation guidance for strain. Every sentence contributes useful information with no waste.

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?

For a simple one-parameter read tool with no output schema, the description enumerates the returned fields and explains the strain scale. Minor operational details are missing, but an agent has enough context to call it correctly.

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 'days' parameter is fully documented in the schema with default and min/max. The description only mentions 'last N days' and adds no syntax or constraints beyond the schema, so the baseline of 3 applies.

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

Purpose4/5

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

The description states a specific verb and resource: returns workout records, and lists the key fields (sport, duration, strain, heart rate). It is clearly distinct from siblings like get_recovery and get_sleep, though it does not explicitly name those alternatives.

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 sentence 'Use it to review training activity' gives a clear usage context. It does not provide exclusions or explicitly compare against sibling tools, so it falls short of the top score.

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

pingA

Returns pong

NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

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

No annotations provided, so description carries full burden. It states it returns a fixed string but does not clarify side effects (none expected) or internal behavior. Acceptable for a trivial tool but minimal.

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?

Two words, no waste. Every word earns its place. Perfectly concise for a simple health-check tool.

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?

For a trivial tool with no parameters and no output schema, the description is complete. It tells the agent exactly what to expect: a return of 'pong'.

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?

No parameters exist, so baseline is 4. Description need not add any parameter info. Schema coverage is 100% (empty).

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

Purpose4/5

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

The description clearly states the tool returns 'pong', which is the expected response for a ping. It is a specific verb ('returns') and resource ('pong'), distinguishing it from sibling 'echo' which likely returns input.

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 on when to use ping vs sibling tool 'echo' or any other context. Missing explicit when-to-use or when-not-to-use information.

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.

  1. 6 tool updatesv1.0.0
    • First observedget_cycles
    • First observedget_profile
    • First observedget_recovery
    • First observedget_sleep
    • First observedget_workouts
    • First observedping
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 6 tools

Disambiguation5/5

Each data tool targets a clearly distinct Whoop resource: profile, recovery, sleep, workouts, and daily cycles. The only potential overlap—strain in get_workouts vs. day strain in get_cycles—is well separated by descriptions as workout-level vs. daily physiological cycle data.

Naming Consistency4/5

Five of six tools follow a clean get_noun snake_case pattern: get_profile, get_recovery, get_sleep, get_workouts, get_cycles. The lone ping tool is a conventional health-check exception, but it is a minor deviation from the otherwise consistent naming scheme.

Tool Count5/5

Six tools are well-scoped for a focused Whoop data retrieval server. Each data tool maps to a distinct core resource, and ping is a lightweight utility that does not bloat the surface.

Completeness5/5

The tool set covers the main Whoop data domains: profile, recovery, sleep, workouts, and daily cycles. For a read-only health-data integration, this provides complete core coverage with no obvious dead ends.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers