Hevy Coach

hevy-coach-mcp

适用于 Hevy（训练追踪应用）的 MCP 服务。它会从 Hevy 实时获取训练记录、训练计划和动作模板——不使用本地缓存或数据库——然后进行数据分析（e1RM、个人纪录、训练量、规律性、周期对比），让 MCP 客户端能基于真实数据进行判断，而非猜测。它会按你的要求写入内容——训练计划、文件夹、体重——绝不会修改你的训练记录历史。

需要 Hevy PRO 和 Hevy API 密钥（Hevy 应用 → Settings → API）。

安装

claude mcp add hevy -e HEVY_API_KEY=your_key_here -- npx -y hevy-coach-mcp

也可以手动将其添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "hevy-coach-mcp"],
      "env": { "HEVY_API_KEY": "your_key_here" }
    }
  }
}

这适用于 Claude Desktop（claude_desktop_config.json）、Claude Code（.mcp.json 或上述命令）、Cursor（.cursor/mcp.json）和 Windsurf（~/.codeium/windsurf/mcp_config.json）——配置格式处处相同。

你的 API 密钥会保留在本地：它从 HEVY_API_KEY 环境变量中读取，除调用 Hevy 自己的 API 外，绝不会离开你的设备。

此外，还提供通过 Streamable HTTP 和 OAuth 的托管模式，供无法启动本地进程的客户端（Claude.ai、ChatGPT）使用。将它们指向 https://hevy-mcp-alpha.vercel.app/mcp，它们便会自行完成 OAuth 流程。docs/CONNECTOR.md 介绍了各客户端的两种配置方式、自托管、示例问题和隐私详情。

首次使用

随时运行 health-check 来确认连接状态。其他所有工具都会从 Hevy 实时获取数据——无需先同步或预热。

工具

十五个只读工具，均标记为 readOnlyHint：

• health-check — 连接状态
• get-workouts、get-workout — 列出／查看训练记录
• list-routines、get-routine — 列出／查看训练计划
• list-routine-folders — 训练计划所属文件夹及其 ID
• search-exercises、get-exercise-history — 按名称查找动作并查看其记录历史
• get-progress、get-records — 每个动作的预估 1RM 趋势和个人纪录（1/3/5/8RM）；get-progress 还可以根据你当时的体重报告每次训练的情况
• get-volume-report — 每周各肌群的有效组数和总训练量
• get-consistency — 训练频率、连续训练天数、最长间隔
• compare-periods — 对比两个日期范围的训练量／训练次数
• get-body-measurements — 记录的体重和身体测量数据，按时间从新到旧排列
• get-bodyweight-trend — 某个时间范围内的体重变化：总变化、百分比和每周变化率

四个写入工具，声明为写入操作，因此客户端会先征求你的同意：

• create-routine — 根据动作名称创建训练计划，可选择放入按名称而非编号指定的文件夹
• update-routine — 编辑现有训练计划；传入动作列表会直接替换原列表（destructiveHint）
• create-routine-folder — 添加文件夹；如果已有同名文件夹，则不会重复创建
• log-body-measurement — 记录指定日期的体重或身体测量数据；重新记录某个日期时，会保留当天已存储的其他数据

资源

hevy://profile、hevy://routines、hevy://exercises、hevy://stats/summary、hevy://workouts/recent — 供客户端无需调用工具即可读取的轻量实时快照。

提示词

weekly-review、program-audit、deload-check、prepare-session — 引导客户端调用合适的工具，回答常见训练问题。

若要了解如何在此基础上构建更高层的功能——一条将数据转化为决策的常驻系统提示词——请参阅 docs/COACH-PROMPT.md。

隐私

不会存储任何账户信息——每次调用工具都会使用你自己的密钥，从 Hevy API 获取最新数据；也不会将任何账户信息发送到其他地方。

有四个工具会向 Hevy 写入数据：create-routine、update-routine、create-routine-folder 和 log-body-measurement。它们都声明为写入操作，因此客户端会在运行前征求你的确认。任何工具都不会写入你的训练记录——这是不可逾越的界限：此处计算的所有数值都来自已记录的训练，因此只能由你在应用中修改。Hevy API 没有删除端点，因此此服务创建的内容也无法从这里删除。请注意，Hevy API 密钥没有权限范围——无论此服务选择如何使用它，该密钥都会授予完整的账户访问权限。

贡献

克隆仓库，运行 yarn install，然后将 .env.example 复制为 .env.local。每次更改后运行 yarn typecheck && yarn test && yarn build 进行验证——CI 也会运行相同的三个命令。

AGENTS.md 是完整指南，介绍了架构、约定以及修改内容前值得了解的决策。它是为 AI 编码 Agent 编写的，但也是人类快速了解项目的最佳途径。

许可证

MIT