Whoop Mcp Unofficial

本地服务

wellness.delx.ai开发工具142 周前更新

代码仓库访问官网

关于 Whoop Mcp Unofficial

WHOOP MCP Unofficial 是面向使用 WHOOP 恢复、睡眠、负荷和 HRV 数据的 AI Agent 的本地优先服务。它提供隐私模式、SQLite 缓存和设置诊断；OAuth 令牌保留在本机。

主要功能

01读取恢复、睡眠、负荷和 HRV 数据
02提供每日和每周摘要
03选择摘要、结构化或原始输出
04使用 SQLite 缓存数据
05检查设置和隐私配置
06提供提示词、资源和合成演示数据

适用场景

01训练前查看准备状态和睡眠
02比较每周恢复情况并规划训练
03在 OAuth 设置前了解数据格式
04将 WHOOP 数据接入个人 AI 工作流

MCP 相关

通过官方 WHOOP OAuth API，向兼容 MCP 的 Agent 提供 WHOOP 数据、摘要、提示词和资源。默认使用 stdio，也可选无状态 HTTP；令牌保留在用户本机。

#mcp #whoop #health-data #recovery #hrv #sleep #typescript #ai-agents #quantified-self #wearables #claude-mcp

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "whoop-mcp-davidmosiah": {
      "command": "npx",
      "args": [
        "-y",
        "whoop-mcp-unofficial"
      ],
      "env": {
        "WHOOP_CLIENT_ID": "<WHOOP_CLIENT_ID>",
        "WHOOP_CLIENT_SECRET": "<WHOOP_CLIENT_SECRET>",
        "WHOOP_REDIRECT_URI": "<WHOOP_REDIRECT_URI>",
        "WHOOP_TOKEN_PATH": "<WHOOP_TOKEN_PATH>",
        "WHOOP_PRIVACY_MODE": "<WHOOP_PRIVACY_MODE>",
        "WHOOP_CACHE": "<WHOOP_CACHE>",
        "WHOOP_CACHE_PATH": "<WHOOP_CACHE_PATH>",
        "WHOOP_NO_CACHE": "<WHOOP_NO_CACHE>"
      }
    }
  }
}

启动命令npx -y whoop-mcp-unofficial

需要配置的环境变量

WHOOP_CLIENT_IDWHOOP OAuth client ID. Optional when configured with whoop-mcp-server setup.

WHOOP_CLIENT_SECRET密钥WHOOP OAuth client secret. Prefer whoop-mcp-server setup so this secret is stored in ~/.whoop-mcp/config.json instead of MCP client config.

WHOOP_REDIRECT_URIRedirect URI configured in the WHOOP Developer Dashboard. Optional when configured with whoop-mcp-server setup.

WHOOP_TOKEN_PATH密钥Optional local path for OAuth tokens. Defaults to ~/.whoop-mcp/tokens.json.

WHOOP_PRIVACY_MODEOptional payload mode: summary, structured, or raw. Defaults to structured. raw means full WHOOP API payloads, not raw device sensor streams.

WHOOP_CACHEOptional SQLite cache toggle. Set to true or sqlite to enable.

WHOOP_CACHE_PATHOptional local SQLite cache path. Defaults to ~/.whoop-mcp/cache.sqlite.

WHOOP_NO_CACHESet to true to bypass the in-memory HTTP response cache (60s TTL for GET only). POST/PUT/DELETE and 4xx/5xx responses are never cached regardless.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmwhoop-mcp-unofficial0.5.3stdio

工具

收录的工具列表 · 更新于 3 周前

参数	类型	必填	说明
response_format	enum	否	markdown \| json

详细介绍

WHOOP MCP

让你的 AI Agent 获取 WHOOP 恢复、睡眠、负荷和 HRV 数据，无需从应用中复制粘贴。
本地优先的 MCP 服务 — 令牌绝不会离开你的设备。

⚡ 通过 Delx Wellness for Hermes 一条命令即可安装： npx -y delx-wellness-hermes setup — 在专用的 Hermes 配置中预先配置此连接器和完整的 Delx Wellness 技术栈。

也可以将其独立接入 Claude Desktop / Cursor / ChatGPT Desktop — 请参阅下方的安装部分。可运行示例见 Delx Wellness 中心。

公开证明： WHOOP MCP 的数据会与下载量、星标数和下一步行动优先级一同记录在 Delx 开源增长快照中。如果它为你节省了 OAuth 和 MCP 设置时间，请为此仓库点个星标，让其他专注于恢复的 Agent 构建者更容易找到它。

第一个实用提示词： Use whoop_connection_status, then whoop_daily_summary, then give me a 5-line operating brief for today.

本地优先的 MCP 服务，可将 AI Agent 连接到你的 WHOOP 恢复、睡眠、负荷和 HRV 数据。

非官方项目。 与 WHOOP, Inc. 无关联，未获其认可或支持。WHOOP 是其各自所有者的商标。仅将此项目用于你自己的 WHOOP 账户，并遵守 WHOOP 的开发者条款。

由 David Mosiah 构建，面向使用 Claude、Cursor、Hermes、OpenClaw 或其他兼容 MCP 的 Agent 来思考训练、睡眠和恢复的人 — 无需从 WHOOP 应用中复制粘贴数据。属于 Delx Wellness，这是一个本地优先的健康 MCP 连接器注册表。

前期工作与致谢

WHOOP MCP Unofficial 基于 Shashank Mishra 先前为 WHOOP MCP 奠定的基础构建，包括 OAuth/WHOOP API 方向，以及早期采用 MIT 许可证的 whoop-ai-mcp 软件包（源代码）。本项目在此基础上扩展，加入本地优先的设置、隐私审计、双传输方式、Agent 清单、摘要、缓存、注册表元数据以及与 Delx Wellness 中心的集成。

如果这个连接器对你的 Agent 工作流有所帮助，请为仓库点个星。星标能让其他 AI 构建者更容易发现本项目，也有助于 Delx 持续推出本地优先的健康基础设施。

WHOOP MCP 本地优先 Agent 工作流演示

为什么要做这个项目

WHOOP 提供丰富的生理数据——恢复分数、HRV、睡眠阶段、负荷——但这些数据被封闭在 OAuth API 和专有应用中。如今要将它接入 AI Agent，你得自行实现 OAuth 流程、安全存储令牌、规范化响应并处理分页。

这个软件包会在本地完成所有这些工作，通过模型上下文协议提供 WHOOP 数据，并让任何兼容 MCP 的 Agent 只需一段配置就能读取你的 WHOOP 上下文。令牌绝不会离开你的设备。

60 秒内完成设置

你需要一个 WHOOP Developer 应用（在此创建），并将重定向 URI 设为 http://127.0.0.1:3000/callback。

npx -y whoop-mcp-unofficial setup    # interactive: paste client id + secret
npx -y whoop-mcp-unofficial auth     # opens browser, captures the OAuth code
npx -y whoop-mcp-unofficial doctor   # verifies you're ready

然后将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "whoop-mcp-unofficial"]
    }
  }
}

对于 Claude Desktop，运行 setup --client claude，即可自动为你写入配置片段。

连接前先看看效果

还没有 WHOOP 账户？调用 whoop_demo，即可获取逼真的合成恢复、睡眠和负荷数据（标记为 is_demo: true），让你的 Agent 在进行任何 OAuth 操作前熟悉数据格式。只需询问：

Call whoop_demo and explain what my daily WHOOP signals would look like.

默认（markdown）输出：

# WHOOP Demo

- **is_demo**: true
- **recovery_score**: 67
- **sleep_score**: 88
- **strain_score**: 11.2
- **recent_training_load**: normal
- **recommended_handoff**: exercise_catalog_recommend_session

使用 response_format=json 可获取实时工具所返回的完整数据结构：

{
  "ok": true,
  "is_demo": true,
  "sample": {
    "whoop_daily_summary": {
      "kind": "daily_summary",
      "generated_at": "2026-05-01T09:20:00.000Z",
      "lookback_days": 10,
      "data_quality": {
        "confidence": "high",
        "counts": {
          "recoveries": 8,
          "sleeps": 8,
          "cycles": 8,
          "workouts": 3
        },
        "pages_fetched": {
          "recoveries": 1,
          "sleeps": 1,
          "cycles": 1,
          "workouts": 1
        }
      },
      "latest": {
        "recovery": {
          "date": "2026-05-01, 6:12 a.m.",
          "score": 67,
          "band": "green",
          "hrv_rmssd_milli": 58,
          "hrv_delta_pct": -6,
          "resting_heart_rate": 52,
          "resting_hr_delta_bpm": 2,
          "score_state": "SCORED"
        },
        "sleep": {
          "start": "2026-04-30, 10:48 p.m.",
          "performance_pct": 88,
          "consistency_pct": 74,
          "efficiency_pct": 91,
          "actual_sleep_hours": 7.7,
          "sleep_need_hours": 8.4,
          "sleep_debt_hours": 0.6,
          "awake_minutes": 26,
          "disturbances": 5,
          "score_state": "SCORED"
        },
        "cycle": {
          "start": "2026-05-01, 5:04 a.m.",
          "strain": 11.2,
          "baseline_strain": 12.4,
          "score_state": "SCORED"
        },
        "workout": {
          "start": "2026-05-01, 6:35 a.m.",
          "sport": "running",
          "strain": 8.2,
          "high_zone_minutes": 15,
          "aerobic_minutes": 50,
          "score_state": "SCORED"
        }
      },
      "diagnostic": {
        "primary_signal": "Recovery is 67 (green).",
        "signals": [
          "Recovery is 67 (green).",
          "HRV is 58 ms (-6% vs recent baseline).",
          "Resting HR is 52 bpm (2 bpm vs recent baseline).",
          "Sleep performance is 88%; actual sleep 7.7h vs need 8.4h.",
          "Latest cycle strain is 11.2 vs baseline 12.4.",
          "Latest workout: running, strain 8.2."
        ],
        "action_candidates": [
          "Training: good window for progressive load if sleep, soreness and schedule are aligned.",
          "Cognition: schedule deep work during the most stable energy window; use shorter analytical blocks if readiness is low."
        ],
        "disclaimer": "Performance coaching only; not medical advice."
      }
    },
    "whoop_wellness_context": {
      "source": "whoop",
      "context_contract_version": "delx-wellness-context/v1",
      "context_type": "wellness_context",
      "generated_at": "2026-05-01T09:20:00.000Z",
      "recovery_score": 67,
      "sleep_score": 88,
      "strain_score": 11.2,
      "recent_training_load": "normal",
      "soreness": [],
      "injury_flags": [],
      "notes": [
        "WHOOP recovery band: green.",
        "Latest workout: running."
      ],
      "data_quality": {
        "confidence": "high",
        "counts": {
          "recoveries": 8,
          "sleeps": 8,
          "cycles": 8,
          "workouts": 3
        },
        "pages_fetched": {
          "recoveries": 1,
          "sleeps": 1,
          "cycles": 1,
          "workouts": 1
        }
      },
      "recommended_handoff": {
        "tool": "exercise_catalog_recommend_session",
        "reason": "Use WHOOP recovery, sleep and strain to scale workout intensity and volume."
      },
      "telegram_summary": "WHOOP wellness context | Recovery: 67 | Sleep: 88 | Strain: 11.2 | Load: normal"
    },
    "whoop_list_recoveries": {
      "endpoint": "/v2/recovery",
      "privacy_mode": "structured",
      "count": 3,
      "records": [
        {
          "cycle_id": 93101,
          "sleep_id": "1a2b3c4d-0000-4000-8000-000000000001",
          "created_at": "2026-05-01T09:14:00.000Z",
          "updated_at": "2026-05-01T09:14:00.000Z",
          "score_state": "SCORED",
          "recovery_score": 67,
          "resting_heart_rate": 52,
          "hrv_rmssd_milli": 58,
          "user_id": 10000001,
          "user_calibrating": false,
          "spo2_percentage": 96.1,
          "skin_temp_celsius": 33.7,
          "score": {
            "user_calibrating": false,
            "recovery_score": 67,
            "hrv_rmssd_milli": 58,
            "resting_heart_rate": 52,
            "spo2_percentage": 96.1,
            "skin_temp_celsius": 33.7
          }
        }
      ],
      "next_token": "c3ludGhldGljLWRlbW8tcGFnZS0y",
      "has_more": true,
      "pages_fetched": 1
    }
  },
  "notes": [
    "All sample data is synthetic; tagged with is_demo=true.",
    "Real calls return live data from the WHOOP Developer API after OAuth setup.",
    "Shapes are verified against the real tools by scripts/demo-contract-test.mjs on every build.",
    "whoop_list_recoveries is shown in the default privacy_mode=structured; summary mode drops the nested score object.",
    "Performance coaching only; not medical advice."
  ]
}

此处的 records 数组仅保留了第一条记录；实时工具会返回全部三条，每条都包含相同的键。records[].score 是未经处理的 WHOOP 对象，而非数字——若解析器将其视为标量读取，会悄无声息地得到 undefined。

完成下方的 OAuth 设置后，whoop_daily_summary、whoop_wellness_context 和 whoop_list_recoveries 将使用你的实时 WHOOP 数据返回相同的数据结构。

安全地录制真实演示

完成 OAuth 连接后，可生成经过隐私清理的记录，用于 README 演示、问题更新或 Agent 评估：

npx -y whoop-mcp-unofficial demo-capture \
  --output whoop-recovery-demo.redacted.json \
  --markdown whoop-recovery-demo.redacted.md \
  --assert-sanitized

demo-capture 会运行 Agent 应采用的相同就绪检查流程：先检查 whoop_connection_status 的数据结构，然后调用 whoop_daily_summary，最后发送一条简短的、结合恢复数据的提示词。若设置不完整，它会拒绝继续；清理器会屏蔽 OAuth 密钥、本地令牌路径、原始数据、精确恢复数值和精确睡眠详情。已提交的脱敏规范仅供测试使用；发布真实记录前应先审核。

使用你的 Agent 试试看

先问以下三个问题：

Use whoop_connection_status to check setup, then run whoop_daily_summary.
Give me a 5-line operating brief for today.

Call whoop_weekly_summary with response_format=json. Identify the top
bottleneck and give me a sleep + training plan for next week.

Use the whoop_daily_performance_coach prompt. Focus on whether I should train
hard today.

数据可用性

此软件包使用官方 WHOOP OAuth API（v2）。它不会访问原始设备传感器数据流。

数据	可用	说明
恢复评分、HRV、RHR、SpO2、皮肤温度	✓	WHOOP 返回已评分的恢复数据时可用
睡眠时段 + 阶段 + 表现	✓	所有已评分的睡眠记录
周期 + 每日负荷 + 千焦	✓	生理周期
锻炼 + 运动项目 + 心率区间	✓	所有记录的锻炼
个人资料 + 身体测量数据	✓	身高、体重、最大心率
连续心率 / 设备遥测数据	—	WHOOP 的公开 API 不提供
实时 BLE 心率监听	—	此软件包不是蓝牙监听器

本文中的 raw 指受支持端点的上游 WHOOP API JSON，而非原始传感器采样数据。

工具

从以下工具开始：

whoop_demo — 逼真的合成恢复 / 睡眠 / 负荷数据，无需 OAuth（参见连接前先查看）
whoop_connection_status — 调用 WHOOP 前验证本地设置
whoop_data_inventory — 清点支持的数据领域、作用域、隐私模式和建议的首次调用，不调用 WHOOP API。
whoop_daily_summary — 今日的准备度、睡眠、负荷和行动建议
whoop_weekly_summary — 记分卡、与上周的比较、下周计划

身份验证与诊断

whoop_capabilities、whoop_agent_manifest、whoop_privacy_audit、whoop_cache_status
whoop_get_auth_url、whoop_exchange_code、whoop_revoke_access

个人资料

whoop_get_profile、whoop_get_body_measurements

集合（支持分页，可使用 start/end 筛选并覆盖隐私模式）

whoop_list_recoveries、whoop_list_sleeps、whoop_list_cycles、whoop_list_workouts

常用集合参数：start、end、limit（最大值为 25）、next_token、all_pages、max_pages、response_format（markdown/json）、privacy_mode（summary/structured/raw）。

start 和 end 在 WHOOP 边界处保持为精确的、带时区的 ISO 日期时间。无效或倒序的范围会在发起网络请求前报错。

按 ID 获取单条记录

whoop_get_cycle、whoop_get_sleep、whoop_get_workout
whoop_get_cycle_sleep、whoop_get_cycle_recovery

提示词

whoop_daily_performance_coach — 根据今天的信号制定实用的每日计划
whoop_weekly_training_review — 比较本周情况 + 制定下周计划
whoop_sleep_recovery_investigator — 调查睡眠 ↔ 恢复模式

每个提示词都接受 timezone（IANA，默认为 UTC）。

资源

whoop://capabilities
whoop://summary/daily、whoop://summary/weekly
whoop://latest/recovery、whoop://latest/sleep、whoop://latest/cycle

隐私与安全

OAuth 令牌存储在 ~/.whoop-mcp/tokens.json 中，权限为 0600，工具绝不会返回这些令牌。
刷新令牌轮换使用锁文件，避免并发刷新冲突。
whoop_revoke_access 是唯一具有破坏性的工具 — 它会删除本地令牌并撤销授权。
WHOOP_PRIVACY_MODE 默认为 structured。只有在 raw 模式或通过单次调用覆盖时，才会选择获取原始 WHOOP API 负载。
结构化模式会保留完整的嵌套生理数据和上游未来新增的字段，同时移除 GPS 和包含机密的值。
demo-capture 会在写入任何用于文档或问题报告的内容前，对演示对话记录进行脱敏。
MCP 客户端看不到访问令牌或刷新令牌。
这不是医疗建议。此服务仅为个人 AI 工作流提供用户授权的数据，不用于诊断或治疗。

配置

setup 会将其中大多数设置写入 ~/.whoop-mcp/config.json（0600）。支持手动通过环境变量覆盖：

WHOOP_CLIENT_ID=…
WHOOP_CLIENT_SECRET=…
WHOOP_REDIRECT_URI=http://127.0.0.1:3000/callback

# Optional
WHOOP_SCOPES="read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement"
WHOOP_PRIVACY_MODE=structured        # summary | structured | raw
WHOOP_CACHE=sqlite                   # optional read-through cache
WHOOP_TOKEN_PATH=~/.whoop-mcp/tokens.json
WHOOP_CACHE_PATH=~/.whoop-mcp/cache.sqlite

Hermes / 远程配置

npx -y whoop-mcp-unofficial setup --client hermes --no-auth
npx -y whoop-mcp-unofficial auth                       # run locally if browser auth is needed
npx -y whoop-mcp-unofficial doctor --client hermes
hermes mcp test whoop

Hermes 配置更改后，使用 /reload-mcp 或 hermes mcp test whoop。常规数据访问无需重启网关。

如果浏览器 OAuth 必须在与 Hermes 不同的机器上完成，请在本地运行 auth，然后将 ~/.whoop-mcp/tokens.json 复制到服务器，并设置 chmod 600。

要求

Node.js 20+
一个 WHOOP Developer 应用，重定向 URI 为 http://127.0.0.1:3000/callback

默认 OAuth 权限范围：

read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement

开发

git clone https://github.com/davidmosiah/whoop-mcp.git
cd whoop-mcp
npm install
npm test
npm run build

使用 MCP Inspector 测试：

npx @modelcontextprotocol/inspector node dist/index.js

HTTP（v2 无状态）

默认使用 stdio。可选的 Streamable HTTP — 无会话 ID，返回 JSON，仅限环回地址：

npx -y whoop-mcp-unofficial --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

环境变量：WHOOP_MCP_HOST、WHOOP_MCP_PORT、WHOOP_MCP_TRANSPORT=http。

文档

链接

npm：https://www.npmjs.com/package/whoop-mcp-unofficial
文档网站：https://wellness.delx.ai/connectors/whoop
旧版文档：https://whoopmcp.vercel.app/
GitHub Pages 镜像：https://davidmosiah.github.io/whoop-mcp/
Delx Wellness 注册表：https://github.com/davidmosiah/delx-wellness
连接器质量标准：https://github.com/davidmosiah/delx-wellness/blob/main/docs/connector-quality-standard.md
WHOOP 官方 API 文档：https://developer.whoop.com/api/

另请参阅

完整的 Delx Wellness 连接器库：

提供方	软件包	仓库
WHOOP	`whoop-mcp-unofficial`	whoop-mcp
Oura	`oura-mcp-unofficial`	ouramcp
Garmin	`garmin-mcp-unofficial`	garminmcp
Strava	`strava-mcp-unofficial`	strava-mcp
Fitbit	`fitbit-mcp-unofficial`	fitbitmcp
Withings	`withings-mcp-unofficial`	withingsmcp
Apple Health	`apple-health-mcp-unofficial`	apple-health-mcp
Polar	`polar-mcp-unofficial`	polarmcp
Nourish（营养）	`wellness-nourish`	wellness-nourish

Hermes 一键配置 — 预配置以上所有连接器以及 wellness 技能和入门引导：delx-wellness-hermes。

📧 联系与支持

📨 [email protected] — 一般问题、集成帮助、合作事宜
🐛 Bug 报告 / 功能请求 — GitHub Issues
🐦 动态 — X 上的 @delx369
🌐 网站 — wellness.delx.ai

许可证

MIT — 参见 LICENSE。行为准则。

免责声明

本软件按原样提供。它不是医疗器械，不提供医疗建议，也不应用于诊断或治疗。若有医疗方面的疑虑，请务必咨询合格的专业人士。

演示：docs/readme-demo-synthetic.md（未提供设备记录时使用合成数据）。

原始模式指 WHOOP 官方 API JSON，而非连续传感器数据流。

技能或 MCP

同一个软件包，两种使用方式。MCP 通过 stdio/HTTP 注册工具。如果客户端不支持 MCP，技能可以通过 CLI 调用相同的工具：

npx -y whoop-mcp-unofficial call whoop_connection_status --json '{}'

将 skill/SKILL.md 复制到你的 Agent 技能目录。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。