WHOOP MCP

whoop-mcp

一个 MCP 服务，可将你的 WHOOP 数据同步到 Postgres，并让 AI Agent 查询这些数据。

WHOOP 的公共 API 有速率限制，使用游标分页，并且每次只返回一条记录。这对于同步任务来说没问题，但如果 Agent 想回答“我本周的 HRV 与基线相比如何？”之类的问题，就很不方便。因此，这个服务将工作分为两部分：

• 同步路径：从 WHOOP API 拉取周期、恢复、睡眠、锻炼和身体测量数据，存入有文档说明的 Postgres 架构，并在类型化列旁保留每条记录的原始 JSON；
• 查询路径：一组只读取 Postgres 的 MCP 工具。它们速度快，不会触及 WHOOP 的速率限制，并且数据同步后即使离线也能继续工作。

你的数据会存入由你掌控的数据库，并采用可通过任何 SQL 客户端读取的架构。除调用 WHOOP 外，不会有任何数据离开你的设备。

Python 3.12+ · MIT · stdio MCP 服务 + CLI · Postgres 存储

---

目录

• 工具
• 安装
• 快速开始
• 配置
• 注册到 MCP 客户端
• 同步机制
• 安全模型
• 开发
• 项目结构
• 许可证

---

工具

两个写入端工具会与 WHOOP API 通信；其他工具都只读取 Postgres。

工具	参数	功能
whoop_auth_url	无	返回可在浏览器中打开的 OAuth 授权 URL。
whoop_connect	code	使用 OAuth code 换取令牌，保存令牌，并返回已连接的用户。
whoop_sync	days=7、full=false	将 WHOOP 数据拉取到 Postgres。返回各数据集合的记录数和错误。
whoop_status	无	各数据集合的同步状态：上次同步时间、水位标记、行数和上次错误。
whoop_overview	days=7	最新恢复状况和生命体征与 30 天基线的对比、昨夜睡眠、近期锻炼和负荷。
whoop_recovery	days=7、limit=50	近期恢复评分、静息心率、HRV、SpO2、皮肤温度。
whoop_sleep	days=7、limit=50	近期睡眠和小睡，包含阶段明细、睡眠需求、表现和效率。
whoop_workouts	days=14、limit=50	近期锻炼，包括负荷、心率、能量、距离和各心率区间分钟数。
whoop_cycles	days=7、limit=50	近期生理周期（WHOOP 日），包括每日负荷和心率。
whoop_baseline	无	各项生命体征的 30 天均值和标准差。

days 上限为 365，limit 上限为 200。所有工具均返回 JSON 文本。

安装

uv tool install whoop-postgres-mcp      # or: pipx install whoop-postgres-mcp

也可以不安装，直接运行：

uvx whoop-postgres-mcp --help

你还需要一个 Postgres 数据库（任意近期版本均可；14+ 即可）和一个 WHOOP 开发者应用。docs/SETUP.md 介绍了两者的配置步骤。

快速开始

export WHOOP_CLIENT_ID=...
export WHOOP_CLIENT_SECRET=...
export WHOOP_REDIRECT_URI=http://localhost:8765/callback
export WHOOP_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop

whoop-mcp init-db          # create the `whoop` schema (idempotent)
whoop-mcp auth-url         # print the URL to visit; approve access in a browser
whoop-mcp connect <code>   # paste the `code` from the redirect URL
whoop-mcp sync --all       # first backfill; later runs: whoop-mcp sync --days 7
whoop-mcp                  # serve MCP over stdio

也可以使用 MCP 工具（whoop_auth_url、whoop_connect、whoop_sync）执行相同流程，让 Agent 完成整个设置过程。

配置

所有配置均通过环境变量完成。服务会在启动时验证每个变量，并在退出时显示缺少的变量名称。

变量	必填	含义
WHOOP_CLIENT_ID	是	WHOOP 开发者应用的客户端 ID。
WHOOP_CLIENT_SECRET	是	WHOOP 开发者应用的客户端密钥。
WHOOP_REDIRECT_URI	是	重定向 URI，必须与应用中注册的地址完全一致。任何 URL 均可；服务不会监听该地址。你需要从地址栏复制 code。
WHOOP_DB_URL	是	Postgres DSN，例如 postgresql://user:pass@host:5432/db。令牌和数据均存储在此处。

向 MCP 客户端注册

Claude Code：

claude mcp add whoop -e WHOOP_CLIENT_ID=... -e WHOOP_CLIENT_SECRET=... \
  -e WHOOP_REDIRECT_URI=http://localhost:8765/callback \
  -e WHOOP_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop \
  -- uvx whoop-postgres-mcp

Claude Desktop（claude_desktop_config.json）或任何接受 stdio 命令的客户端：

{
  "mcpServers": {
    "whoop": {
      "command": "uvx",
      "args": ["whoop-postgres-mcp"],
      "env": {
        "WHOOP_CLIENT_ID": "...",
        "WHOOP_CLIENT_SECRET": "...",
        "WHOOP_REDIRECT_URI": "http://localhost:8765/callback",
        "WHOOP_DB_URL": "postgresql://whoop:whoop@localhost:5432/whoop"
      }
    }
  }
}

同步工作原理

WHOOP 的集合端点会按记录的发生时间筛选，而非最后修改时间；记录在创建后也会发生变化（睡眠记录创建时的状态为 PENDING_SCORE，之后才会评分）。因此，同步会：

1. 始终重新获取最近 days 天的数据，以捕获延迟评分的记录；
2. 跟踪每个集合的水位线（whoop_sync_state 中的 newest_updated_at）。如果距上次同步已超过 days 天，则将时间窗口向前扩展至水位线之前两天，确保间隔不会造成数据缺失；
3. 按自然键（id，恢复数据则使用 cycle_id）对每条记录执行 upsert，因此窗口重叠不会造成问题，重复运行也安全；
4. 在 whoop_sync_state 中记录每个集合的错误，并继续处理其他集合，而不是中止本次运行。

full=true（或 whoop-mcp sync --all）会取消时间下限，并遍历账户的全部历史记录。身体测量数据只有一条当前记录，每次同步都会刷新。

令牌会主动刷新（在过期前五分钟），并通过 Postgres 咨询锁进行串行处理，因此 MCP 服务和由 cron 驱动的 whoop-mcp sync 可以共用一行令牌记录而不会发生竞争。

完整的数据模型见 docs/SCHEMA.md。

安全模型

• 数据库访问等同于令牌访问。 OAuth 令牌以明文存储在 whoop.whoop_tokens 中。任何能够读取该表的人，都可以代表你调用 WHOOP API，直到刷新令牌被撤销。请相应限制数据库授权，并将 WHOOP_DB_URL 视为机密。
• 读取工具不会访问网络。 只有 whoop_connect 和 whoop_sync 会与 WHOOP 通信。其他所有操作都是针对你的数据库执行的 SQL 查询。
• Postgres 之外不会写入任何内容。 不写入文件，不使用缓存，也不收集遥测数据。
• 权限范围仅限读取。 应用会请求 read:* 权限范围，以及用于刷新令牌的 offline。它无法修改 WHOOP 账户中的任何内容。
• 要撤销访问权限，请从 whoop_tokens 中删除该行，并从 WHOOP 账户设置中移除该应用。

开发

git clone https://github.com/cunicopia-dev/whoop-mcp
cd whoop-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

ruff check .
mypy src
pytest                       # pure-logic tests
WHOOP_TEST_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop pytest   # + live DB tests

实时测试会应用架构，并在每项测试前清空目标数据库中的所有表。请使用临时数据库运行这些测试。

用于本地测试的临时 Postgres：

docker run -d --rm --name whoop-pg -e POSTGRES_USER=whoop -e POSTGRES_PASSWORD=whoop \
  -e POSTGRES_DB=whoop -p 5432:5432 postgres:16-alpine

项目结构

src/whoop_mcp/
  config.py     environment variables, validated at startup
  auth.py       OAuth2 flow, token persistence, locked refresh
  client.py     httpx client: pagination, backoff, Retry-After
  schema.sql    the Postgres DDL (applied by `whoop-mcp init-db`)
  db.py         connection + schema helpers
  sync.py       incremental sync with per-collection watermarks
  queries.py    read-side SQL behind the MCP tools
  server.py     MCP server over stdio + CLI entry point
docs/
  SETUP.md      WHOOP app registration, OAuth walkthrough, DB init, first sync
  SCHEMA.md     column-by-column data model
tests/          config, schema, client, auth, sync, and stdio protocol tests

许可证

MIT。参见 LICENSE。