WHOOP连接器

MCP服务器和CLI，用于通过OpenClaw平台将WHOOP数据连接到个人Coach代理。

内容

用途
它是如何工作的
项目结构
安装
配置
首次发射
命令行界面
MCP工具
连接到OpenClaw
在VPS上部署
安全
限制
扩展

______________________________________________________________________

用途

该项目允许部署在OpenClaw中的个人Coach代理通过MCP协议访问WHOOP数据。Coach可以：

阅读恢复、睡眠、负荷和HRV指标；
分析身体数据（身高、体重、最大小时数）并计算BMI；
基于恢复评分的训练建议；
显示7、14或30天的趋势；
将期间数据导出到JSON；
注意恶化，建议减轻压力。

除了MCP服务器，该项目还包括一个完整的CLI，易于调试、监视和脚本。

______________________________________________________________________

它是如何工作的

WHOOP API v2 (OAuth 2.0 + PKCE)
        │
        ▼
whoop/api/client.py     ← httpx async, TTL кэш 5 мин, auto-retry на 401
        │
        ▼
whoop/schema/mappers.py ← JSON → unified dataclasses
        │
        ▼
whoop/services.py       ← WhoopService (shared core)
       / \
      /   \
     ▼     ▼
mcp_server  cli
(stdio)     (Typer + Rich)
     │
     ▼
OpenClaw Gateway → Coach → Telegram

MCP协议

服务器由OpenClaw作为子进程运行。通过标准（STDIN/STDOUT JSON-RPC）。这是本地部署最简单、最可靠的选择。

认证

第一次启动时 OAuth 2.0сPKCE:

打开浏览器→WHOOP授权页。
在 localhost:8080/callback 用代码重定向。
参数 state 通过CSRF验证。
令牌加密 AES-256-GCM 并存储在磁盘上（~/.whoop/tokens.enc).
在以下请求中，令牌将通过Refresh Token自动更新。

无浏览器的VPS可用 无头模式 页：1 在VPS上部署.

OAuth作用域

服务器在授权时请求以下权限：

scope访问 |---|---| | read:profile |Имя、电子邮件、用户ID| | read:body_measurement 身高，体重，最大值哦。 | read:recovery |恢复评分、心率变异性、静息心率、血氧饱和度| | read:sleep 睡眠数据：阶段，效率，呼吸。 | read:workout 训练：Strain，HR，卡路里，距离 | read:cycles 生理周期：日负荷 | offline –Refresh Token自动更新›

创建应用程序时，必须在whoop developer dashboard中启用所有scopes。

缓存

所有对WHOP API的Get请求都在TTL 5分钟内缓存到内存中。 WHOOP_CACHE_TTL).过时的记录在下次处理时会懒惰地清理，再加上每60秒彻底清理一次。

______________________________________________________________________

项目结构

whoop_connecter/
├── whoop/                    # Shared core — библиотека
│   ├── auth/
│   │   ├── oauth.py          # OAuth 2.0 PKCE flow + headless mode
│   │   └── token_store.py    # AES-256-GCM хранилище токенов
│   ├── api/
│   │   ├── client.py         # httpx async клиент, авто-retry на 401
│   │   ├── cache.py          # In-memory TTL кэш
│   │   └── endpoints.py      # Константы WHOOP API v2 endpoints
│   ├── schema/
│   │   ├── unified.py        # Source-agnostic dataclasses
│   │   └── mappers.py        # WHOOP JSON → unified schema
│   ├── analytics/
│   │   ├── daily_summary.py  # Агрегация дня + рекомендация
│   │   └── trends.py         # Тренды за N дней (↑↓→)
│   └── services.py           # WhoopService facade
│
├── mcp_server/               # MCP-сервер (stdio)
│   ├── server.py             # Точка входа, регистрация инструментов
│   └── tools/                # По одному файлу на инструмент
│       ├── summary.py        # get_daily_summary
│       ├── trends.py         # get_trends
│       ├── recovery.py       # get_recovery
│       ├── sleep.py          # get_sleep
│       ├── workouts.py       # get_workouts
│       ├── cycles.py         # get_cycles
│       ├── body.py           # get_body_measurement
│       ├── profile.py        # get_profile
│       └── auth_status.py    # get_auth_status
│
├── cli/
│   └── main.py               # CLI (Typer + Rich)
│
├── deploy/
│   ├── openclaw_mcp_config.json  # Шаблон MCP-конфига для OpenClaw
│   └── setup_vps.sh              # Скрипт развёртывания на VPS
│
├── damp/
│   └── openapi.json          # OpenAPI-спецификация WHOOP API v2
│
├── tests/                    # 199 тестов (unit + integration + acceptance)
├── .env.example
├── pyproject.toml
└── README.md

______________________________________________________________________

安装

要求

Python 3.10+
开发者Whoop帐号： developer.hop.com

步骤

# 1. Клонировать репозиторий
git clone https://github.com/asgoone/whoop-connecter.git
cd whoop-connecter

# 2. Создать виртуальное окружение
python3 -m venv .venv
source .venv/bin/activate

# 3. Установить зависимости
pip install -e .

安装后，有两个命令可用：

团队描述 |---------|----------| | whoop #CLI用于WHOOP数据。 | whoop-mcp OpenClaw的MCP服务器（STDIO）

______________________________________________________________________

配置

1.创建 `.env`

cp .env.example .env
chmod 600 .env

2.填写参数

# Обязательно — из developer.whoop.com
WHOOP_CLIENT_ID=ваш_client_id
WHOOP_CLIENT_SECRET=ваш_client_secret

# Ключ шифрования токенов (генерируется один раз)
WHOOP_TOKEN_ENCRYPTION_KEY=ваш_64_символьный_hex

# Опционально
WHOOP_REDIRECT_URI=http://localhost:8080/callback
WHOOP_TOKEN_PATH=~/.whoop/tokens.enc
WHOOP_CACHE_TTL=300
LOG_LEVEL=WARNING

3.生成加密密钥

python3 -c "import secrets; print(secrets.token_hex(32))"

环境变量的完整列表

变量是必需的，默认情况下是必需的。 |---|---|---|---| | WHOOP_CLIENT_ID |Да|--|OAuth客户端IDизWHOOP开发人员仪表板| | WHOOP_CLIENT_SECRET |Да|--|OAuth客户端密钥| | WHOOP_TOKEN_ENCRYPTION_KEY ÐÐÐÐÐÐÐÐÐÐÐÐÐÐÐ | WHOOP_REDIRECT_URI 没有 http://localhost:8080/callback |重定向URIдляOAuth回调| | WHOOP_TOKEN_PATH 没有 ~/.whoop/tokens.enc token文件路径 | WHOOP_CACHE_TTL 没有 300 –TTL API响应缓存，秒。 | LOG_LEVEL 没有 WARNING log（DEBUG, INFO, WARNING, ERROR) |

whoop developer app下载

В developer.hop.com 创建应用程序时：

重定向URI -指定 http://localhost:8080/callback.
范围 -全部打开： read:profile, read:body_measurement, read:recovery, read:sleep, read:workout, read:cycles.
复制 Client ID 和 Client Secret 在 .env.

______________________________________________________________________

首次发射

1.授权

# С браузером (локальная машина)
whoop auth login

# Без браузера (VPS, сервер)
whoop auth login-headless

当 login 浏览器将打开。登录whoop并允许访问。代币将自动以加密形式保存。

当 login-headless 终端将显示URL-在任何设备上的浏览器中打开它，登录并将callback URL粘贴回终端。

2.核实

whoop auth status
# → Authenticated — token is valid, expires at 2026-03-18T08:00:00+00:00

whoop summary
# → 🟢 Recovery 74% | Sleep 85 | HRV 61 | RHR 55 | Strain 8.3
#   → Good recovery. You can train at full intensity.

______________________________________________________________________

命令行界面

CLI使用相同的 WhoopService与MCP服务器一样，没有重复的逻辑。

命令

`whoop summary` -每日报告

whoop summary                     # сегодня
whoop summary --date 2026-03-15   # конкретная дата
whoop summary --raw               # JSON

`whoop recovery` -恢复度量

whoop recovery
whoop recovery --start 2026-03-10T00:00:00Z --end 2026-03-17T23:59:59Z
whoop recovery --raw

显示：Recovery Score，HRV（RMSD），Resting HR，SPO2。

`whoop sleep` 睡眠数据

whoop sleep
whoop sleep --raw

Показывает：睡眠评分、持续时间、效率、呼吸频率、睡眠一致性、所需睡眠（基线/债务/紧张/午睡）。

`whoop body` 身体测量

whoop body
whoop body --raw

显示：身高，体重，最大值。CHS，BMI（自动计算）。

`whoop trends` -期间趋势

whoop trends              # 7 дней
whoop trends --days 30    # 30 дней
whoop trends --raw

显示5个度量，方向（^↓→）和变化百分比。

`whoop export` -数据输出

whoop export                           # 7 дней → stdout
whoop export --days 30                 # 30 дней
whoop export --days 14 --output data.json  # в файл

将身体+n天每日健康（睡眠、恢复、活动）导出到JSON。使用Batch查询： 4 HTTP呼叫 无论天数（1 body+3 paginated:cycles，recovery，sleep）。

`whoop auth` -授权管理

whoop auth status          # проверить статус токена
whoop auth login           # авторизация через браузер
whoop auth login-headless  # авторизация без браузера (VPS)
whoop auth logout          # удалить токен

auth status 如果令牌过期，自动尝试通过refresh更新令牌，并显示当前状态。

`whoop raw` 原始API（调试）

whoop raw profile
whoop raw body
whoop raw recovery --start 2026-03-10T00:00:00Z
whoop raw sleep
whoop raw workouts
whoop raw cycles

输出原始的WHOP API JSON响应，用于调试和学习数据格式。

旗 `--raw`

所有团队支持 --raw 对于纯JSON输出，脚本很方便：

whoop summary --raw | jq '.recovery_score'
whoop sleep --raw | jq '.sleep_needed'
whoop export --days 7 | jq '.daily[0].recovery'

______________________________________________________________________

MCP工具

MCP服务器提供 9工具教练以他们的名字称呼他们。

`get_daily_summary`

每日摘要。早上简报的主要工具。

参数：

参数类型必需描述类型 |---|---|---|---| | date ÐstringÐÐÐÐÐÐÐÐÐÐÐ YYYY-MM-DD默认为今天。 |

答案示例：

{
  "date": "2026-03-17",
  "recovery_score": 74,
  "sleep_score": 85,
  "hrv_rmssd": 61.2,
  "resting_hr": 55,
  "strain": 8.3,
  "recommendation": "Good recovery. You can train at full intensity.",
  "emoji": "🟢",
  "summary_line": "🟢 Recovery 74% | Sleep 85 | HRV 61 | RHR 55 | Strain 8.3\n→ Good recovery. You can train at full intensity."
}

建议逻辑：

Recovery Score颜色推荐 |---|---|---| | >= 67 | 🟢 | 满载。 | 34-66 | 🟡 | 中等负荷。 | \ 3%, ↓ 下降>3% → 稳定的。

______________________________________________________________________

`get_recovery`

期间恢复指标。

参数： start, end — ISO datetime.不一定。

返回： score, hrv_rmssd, resting_hr, spo2, skin_temp_deviation.

______________________________________________________________________

`get_sleep`

睡眠数据。自动选择主要睡眠 SCORED 记录。

参数： start, end.

返回：

字段类型描述 |---|---|---| | score |int |睡眠性能百分比（0-100）| | duration_hours Float在床上的时间 | efficiency 床上睡眠的比例（0.0-1.0）→ | stages 睡眠阶段（light，sws，rem，awake） | respiratory_rate –Float–呼吸频率（呼吸/分钟）→ | sleep_consistency 睡眠一致性（0-100%） | sleep_needed –DICT→睡眠需求：baseline，debt，strain，nap（ms）→

______________________________________________________________________

`get_workouts`

期间的训练清单。

参数： start, end.

返回： 对象数组：

字段类型描述 |---|---|---| | sport string运动名称 | strain 荷载（0-21） | duration_minutes Float持续时间 | avg_hr 平均脉搏 | max_hr int，max。脉搏 | calories 卡路里 | | distance_meter （float）–米距离（如果有GPS）→ | altitude_gain_meter –float–以米为单位的爬高（如果有的话）→ | percent_recorded #float 记录的HR数据的百分比 float 记录的HR数据的百分比 float | zone_durations –DICT–脉动区时间（zoneu zero..zoneu five，ms）

______________________________________________________________________

`get_cycles`

Whoop生理周期（每天的负荷和卡路里）

参数： start, end.

返回： strain, calories.

______________________________________________________________________

`get_body_measurement`

用户身体的测量需要scope read:body_measurement.

参数： 没有

返回：

{
  "height_meter": 1.80,
  "weight_kilogram": 82.5,
  "max_heart_rate": 195
}

______________________________________________________________________

`get_profile`

用户配置文件：名称、电子邮件、用户ID。

______________________________________________________________________

`get_auth_status`

OAUTH令牌状态。如果令牌过期，自动尝试通过refresh更新令牌。

返回：

{
  "authenticated": true,
  "expires_at": "2026-03-18T08:00:00+00:00",
  "expired": false
}

______________________________________________________________________

连接到OpenClaw

1.填充配置路径

编辑 deploy/openclaw_mcp_config.json替换路径和credentials：

{
  "mcpServers": {
    "whoop": {
      "command": "/home/user/whoop_connecter/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/home/user/whoop_connecter",
      "env": {
        "WHOOP_CLIENT_ID": "ваш_client_id",
        "WHOOP_CLIENT_SECRET": "ваш_client_secret",
        "WHOOP_REDIRECT_URI": "http://localhost:8080/callback",
        "WHOOP_TOKEN_PATH": "/home/user/.whoop/tokens.enc",
        "WHOOP_TOKEN_ENCRYPTION_KEY": "ваш_ключ",
        "WHOOP_CACHE_TTL": "300",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}

2.在OpenClaw中添加配置

添加部分 whoop MCP是OpenClaw安装的配置。具体的配置路径取决于版本。OpenClaw文档。

3.检查

添加配置后，Coach应该看到9个whoop工具。请Coach： _“展示我今天的恢复”_ -he'il打电话给你。 get_daily_summary 或 get_recovery.

4.自定义主动摘要（可选）

上午8:00摘要的cron任务示例：

0 8 * * * cd /home/user/whoop_connecter && \
  .venv/bin/whoop summary --raw 2>/dev/null | \
  curl -s -X POST "https://your-webhook-url" \
    -H "Content-Type: application/json" \
    -d @-

将摘要传递到电报的具体方式取决于您的导师架构。它可以是webhook、cron→openclaw API，也可以是Coach内部的计划任务。

______________________________________________________________________

在VPS上部署

快速启动

# 1. Клонировать и установить
git clone https://github.com/asgoone/whoop-connecter.git
cd whoop-connecter
bash deploy/setup_vps.sh

# 2. Сохранить ключ шифрования, который вывел скрипт!

# 3. Заполнить .env
nano .env   # CLIENT_ID, CLIENT_SECRET, ENCRYPTION_KEY

# 4. Авторизация (headless — без браузера)
.venv/bin/whoop auth login-headless
# → Скрипт покажет URL. Откройте его в браузере на другом устройстве,
#   авторизуйтесь, скопируйте URL редиректа и вставьте в терминал.

# 5. Проверить
.venv/bin/whoop auth status
.venv/bin/whoop summary

无头OAuth流

VPS上没有浏览器，因此使用Headless模式：

运行 whoop auth login-headless.
终端将显示授权URL。
打开此URL 任何设备上的浏览器 （手机，笔记本电脑）
登录Whoop。
浏览器将重定向到 localhost:8080/callback?code=...&state=... -复制 完整URL 从地址栏。
将URL插入VPS终端。
代币被保存，然后通过Refresh Token自动更新。

重要的是： 重定向на localhost:8080 在其他设备上的浏览器中无法工作-这很正常。只需从地址栏复制URL，即使页面没有加载。

VPS上的文件结构

/home/user/
├── whoop_connecter/          # Репозиторий
│   ├── .venv/                # Виртуальное окружение
│   └── .env                  # Credentials (chmod 600)
└── .whoop/
    └── tokens.enc            # Зашифрованные токены (chmod 600)

______________________________________________________________________

安全

方面，实现。 |---|---| Ð代币存储-AES-256-GCM加密，nonce对每个条目都是唯一的› –访问令牌文件的权限。 600 （只有业主） Ð加密密钥›在环境变量中，不在代码中，也不在代码中 .env 在Git？ csrf参数 state 在callback处理程序中验证。 |OAuth PKCE| code_verifier + code_challenge 第256章一次 ÐOpenClaw config中的秘密¸通过环境变量传输，而不是用JSON进行硬编码¸ 医学权威Coach 没有诊断如果测量不好，建议减轻压力或去看医生。 |

`.gitignore` 包括

.env           # Credentials
*.enc          # Зашифрованные токены
.venv/         # Виртуальное окружение

______________________________________________________________________

限制

功能

数据来自Whoop。 其他来源（Oura、Apple Health）在当前版本中不受支持，但架构已准备好通过以下方式进行扩展： unified schema.
当服务器重新启动时，缓存将重置。 使用内存缓存，数据不会经历进程重新启动。
历史数据仅限于API。 Whoop API不保证超过1年的数据。
whoop API不提供：年龄，出生日期，生物年龄，WHOOP年龄，压力水平。

技术

Python 3.10+ -必填（使用语法） X | Y 类型）。
每个进程一个MCP服务器 -对于来自Coach的多个同时请求，它们将按顺序处理（MCP stdio是单线的）。
get_trends / export с days > 30 -由于数据量大，速度较慢，但使用Batch请求（3-4个HTTP呼叫，独立于n）。

世界卫生组织API v2

嵌套响应格式（对象内的度量） score).项目Mapers处理嵌入式和平面格式以实现兼容性。完整的API规范存储在 damp/openapi.json.

______________________________________________________________________

扩展

添加新的MCP工具

创建文件 mcp_server/tools/my_tool.py:

import json
from mcp.types import Tool
from whoop.services import WhoopService

TOOL = Tool(
    name="my_tool",
    description="Описание инструмента для Coach.",
    inputSchema={
        "type": "object",
        "properties": {
            "param": {"type": "string", "description": "Описание параметра."},
        },
    },
)

async def handle(arguments: dict, service: WhoopService) -> str:
    result = await service.some_method(arguments.get("param"))
    return json.dumps(result)

添加进口到 mcp_server/server.py 模块B _TOOL_MODULES.

添加新数据源（Oura，Apple Health）

实现新的客户端和地图 whoop/api/ 和 whoop/schema/.
Mapper必须返回相同的 DailyHealth 数据类с source="oura".
全部分析（build_daily_summary, build_trends（d）工作不变。

调试

# Детальное логирование CLI
LOG_LEVEL=DEBUG whoop summary

# Детальное логирование MCP-сервера
LOG_LEVEL=DEBUG whoop-mcp

# Сырые данные API (минуя маппинг)
whoop raw recovery
whoop raw sleep --start 2026-03-10T00:00:00Z

mcp服务器登录 标准错误，stdout保留给MCP协议。

测试

# Запустить все тесты (199)
.venv/bin/python -m pytest tests/ -v

# Только unit-тесты
.venv/bin/python -m pytest tests/unit/ -v

# Только интеграционные + приёмочные
.venv/bin/python -m pytest tests/integration/ -v

测试结构：

#21040；部测试，数量？ |---|---|---| | tests/unit/ –Maper，分析师，Cash，Token Store–130。 | tests/integration/ –服务层、MCP工具、接收脚本～70～

Whoop Connecter

快速接入

详细介绍

WHOOP连接器

内容

用途

它是如何工作的

MCP协议

认证

OAuth作用域

缓存

项目结构

安装

要求

步骤

配置

1.创建 .env

2.填写参数

3.生成加密密钥

环境变量的完整列表

whoop developer app下载

首次发射

1.授权

2.核实

命令行界面

命令

whoop summary -每日报告

whoop recovery -恢复度量

whoop sleep 睡眠数据

whoop body 身体测量

whoop trends -期间趋势

whoop export -数据输出

whoop auth -授权管理

whoop raw 原始API（调试）

旗 --raw

MCP工具

get_daily_summary

get_recovery

get_sleep

get_workouts

get_cycles

get_body_measurement

get_profile

get_auth_status

连接到OpenClaw

1.填充配置路径

2.在OpenClaw中添加配置

3.检查

4.自定义主动摘要（可选）

在VPS上部署

快速启动

无头OAuth流

VPS上的文件结构

安全

.gitignore 包括

限制

功能

技术

世界卫生组织API v2

扩展

添加新的MCP工具

添加新数据源（Oura，Apple Health）

调试

测试

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1.创建 `.env`

`whoop summary` -每日报告

`whoop recovery` -恢复度量

`whoop sleep` 睡眠数据

`whoop body` 身体测量

`whoop trends` -期间趋势

`whoop export` -数据输出

`whoop auth` -授权管理

`whoop raw` 原始API（调试）

旗 `--raw`

`get_daily_summary`

`get_recovery`

`get_sleep`

`get_workouts`

`get_cycles`

`get_body_measurement`

`get_profile`

`get_auth_status`

`.gitignore` 包括