hevy2whoop

hevy2whoop

将你在 Hevy 中记录的力量训练复制到 WHOOP Strength Trainer：包括每个训练动作和每组正式训练组，以及次数和重量。 WHOOP 没有 Hevy 集成，因此如果不使用此工具，每次训练后都必须在 WHOOP 应用中手动录入这些训练组。

hevy2whoop 负责处理 Hevy 端和训练动作映射。写入 WHOOP 的操作由 Brian Gao 开发的 MCP 服务 totem 完成。

使用前请阅读。 本项目与 Hevy 或 WHOOP 均无关联。 WHOOP 未提供用于写入 Strength Trainer 训练的公开 API。 totem 使用 WHOOP 的私有 iOS API，而 WHOOP 的条款不允许使用该 API，且该 API 可能随时变更，恕不另行通知。使用风险由你自行承担，且只能使用自己的账号。hevy2whoop 在你的计算机上运行；你的 Hevy 密钥和 WHOOP 令牌只会发送给 Hevy 和 WHOOP。

使用 AI Agent 进行设置

将以下消息发送给你的 Agent（Claude Code、Codex、Cursor 等）：

请按照以下说明为我安装 hevy2whoop： https://raw.githubusercontent.com/mselcukozturk/hevy2whoop/main/AGENT_INSTALLATION.md

AGENT_INSTALLATION.md 会引导 Agent 完成每个步骤并进行检查，与你一起映射尚未映射的训练动作，并在你的客户端中注册 MCP 服务。它会要求 Agent 将 WHOOP 登录留给你操作，并且仅在你批准预览后才写入 WHOOP。

功能

1. 通过官方 Hevy API 读取你最近一次 Hevy 训练，或指定日期范围内的所有训练。
2. 使用 mapping.json 将每个训练动作转换为 WHOOP 训练动作 ID。热身组会被排除。没有映射条目的训练动作会被报告，但不会写入。
3. 检查 WHOOP 中是否已有开始和结束时间与 Hevy 训练相差不超过 2 分钟的 Strength Trainer 活动。如果有，则不会再次写入该训练，因此重复运行是安全的。
4. 显示预览。使用 --write 时，会将训练记录到 WHOOP。

它可以作为命令行工具运行，也可以作为 MCP 服务运行，让 Claude 或其他 MCP 客户端按需执行同步（“将昨天的训练复制到 WHOOP”）。

要求

• Node.js 24 或更高版本
• Hevy Pro（Hevy API 密钥仅对 Pro 用户开放）： hevy.com/settings?developer
• WHOOP 账号
• 已安装并登录的 totem

安装

git clone https://github.com/mselcukozturk/hevy2whoop.git
cd hevy2whoop
npm install -g @thebriangao/totem
totem auth                      # sign in to WHOOP once
export HEVY_API_KEY=your-hevy-api-key

hevy2whoop 没有 npm 依赖项。它会从你的 PATH 中启动 totem start。totem 的 WHOOP 登录状态会持续约 30 天；过期后，请再次运行 totem auth。

用法

node hevy2whoop.mjs sync                                      # preview the latest workout
node hevy2whoop.mjs sync --write                              # write it to WHOOP
node hevy2whoop.mjs sync --from 2026-09-01 --to 2026-09-30    # preview a date range
node hevy2whoop.mjs sync --from 2026-09-01 --to 2026-09-30 --write
node hevy2whoop.mjs catalog "lateral raise"                   # find WHOOP exercise IDs

日期采用你的本地时区，且包含起止日期。输出示例：

2026-09-06 13:34–14:27  Upper Body
  unmapped: Wide Grip Row (template 0b7e5c2a-4d1f-4e8a-9c3b-6f2a1d8e7b90)
  skipped by mapping: Warm Up
  preview: would write 10 exercises, 20 sets (run with --write to write)

如需自动同步，可在训练结束一段时间后，通过 cron 或 systemd 定时器运行 node hevy2whoop.mjs sync --write。

MCP 服务

node hevy2whoop.mjs mcp 会通过 stdio 运行一个包含两个工具的 MCP 服务：

工具	参数	效果
hevy2whoop_sync	from、to（YYYY-MM-DD，可选）、write（默认为 false）	与 sync 相同。每次训练返回一个结果：preview、written、already_in_whoop、nothing_to_write 或 error，并包含未映射和已跳过的训练动作。
hevy2whoop_catalog	search（可选）	与 catalog 相同。

只有在使用 write: true 调用同步工具时，才会写入 WHOOP。

Claude Code：

claude mcp add hevy2whoop -e HEVY_API_KEY=your-hevy-api-key -- node /path/to/hevy2whoop/hevy2whoop.mjs mcp

发布 npm 包后，无需本地克隆：

claude mcp add hevy2whoop -e HEVY_API_KEY=your-hevy-api-key -- npx -y hevy2whoop mcp

Claude Desktop、Cursor 和其他客户端（claude_desktop_config.json 或客户端的 MCP 设置）：

{
  "mcpServers": {
    "hevy2whoop": {
      "command": "node",
      "args": ["/path/to/hevy2whoop/hevy2whoop.mjs", "mcp"],
      "env": { "HEVY_API_KEY": "your-hevy-api-key" }
    }
  }
}

客户端提供给服务的 PATH 中必须包含 totem。如果客户端找不到它，请将 "PATH" 添加到 env 中。

练习映射

mapping.json 以 Hevy 的 exercise_template_id 为键：

"DE68C825": {
  "hevy": "Single Arm Lateral Raise (Cable)",
  "whoop": ["LATERALRAISELEFT_PULLEYMACHINE", "LATERALRAISERIGHT_PULLEYMACHINE"],
  "approximate": false,
  "note": "the catalog has no two-sided cable lateral raise; every set is written to both sides"
}

字段	含义
hevy	Hevy 练习名称，供文件阅读者查看
whoop	WHOOP 练习 ID。每组正式训练组都会写入列表中的每个 ID。空列表表示永不记录该练习。
approximate	当 WHOOP 目录中没有完全匹配的练习，而选择了最接近的练习时，设为 true
note	选择近似或特殊练习的原因

WHOOP 目录中有 372 个练习，而 Hevy 的练习数量多得多，因此有不少条目是近似匹配。请查看备注，并修改你不同意的条目。

添加练习

1. 运行 sync。未映射的练习会与其模板 ID 一同列出。
2. 使用 node hevy2whoop.mjs catalog <search> 查找 WHOOP ID。
3. 将条目添加到你自己的映射文件（见下文），或添加到 mapping.json，前提是该练习是 Hevy 内置练习，且你希望贡献此条目。

你自己的映射文件

将 HEVY2WHOOP_MAPPING 设置为采用相同格式的 JSON 文件路径。该文件中的条目会添加到 mapping.json 中；如果条目的模板 ID 相同，则会替换捆绑的条目。你可以用它映射自定义 Hevy 练习，也可以保存与捆绑映射不同的选择；这样更新仓库时就不会与自己的更改冲突。

export HEVY2WHOOP_MAPPING=~/.config/hevy2whoop/mapping.json

自定义 Hevy 练习使用 UUID 模板 ID（例如 0b7e5c2a-4d1f-...）。这些练习只存在于你的账户中，因此请将它们保存在自己的文件中，不要提交。

贡献

欢迎提交拉取请求，为 Hevy 内置练习（8 位字符的模板 ID）添加或修正条目。如果匹配并非完全一致，请设置 approximate，并在 note 中说明原因。

限制

• WHOOP 会为每组记录时长；Hevy 不会。训练时长会平均分配到各组正式训练组。
• 递减组和力竭组会作为普通组写入。
• 只有 WHOOP 记录为 Strength Trainer 活动的训练才会被视为已记录。同一训练期间由腕带记录的独立活动不会被更改。
• 对于单侧练习，Hevy 按每侧计数，而 WHOOP 的某些条目可能按总次数计数。请参阅 mapping.json 中的备注。

测试

node test/e2e.mjs

使用模拟 Hevy API 和模拟 totem 服务，端到端运行命令行工具和 MCP 服务，覆盖 docs/failure-scenarios.md 中的情形，并将结果写入 artifacts/e2e-result.json。不会使用真实账户。

致谢

• totem 由 Brian Gao 编写（MIT 许可证），负责所有与 WHOOP 的通信。
• hevy2garmin 为 Garmin Connect 完成相同的工作，也是本项目的参考。

许可证

MIT