Hevy MCP

@diecoscai/hevy-mcp

适用于 Hevy 健身 API 的模型上下文协议服务。可通过任意兼容 MCP 的客户端管理训练、训练计划、动作和身体测量数据，包括 Claude Desktop、Claude Code、Cursor、VS Code，以及其他所有支持通过 stdio 使用 MCP 的客户端。

概述

此 MCP 服务将公开的 Hevy API（api.hevyapp.com/v1）封装为 22 个强类型工具。大模型 Agent 可以列出训练记录、创建训练计划、查找动作模板、追踪身体测量数据，以及获取增量同步数据流——无需在客户端编写专用连接代码。

设计目标：

• 默认安全。 除非设置 HEVY_MCP_ALLOW_WRITES=1，否则写入操作会返回 { dry_run: true, would_send: { ... } } 预览。Hevy API 没有任何资源的 DELETE 操作，因此意外写入无法撤销；试运行模式可防止此类情况。
• 在边界处进行验证。 每个工具输入都会先通过 Zod 验证，再向网络发送任何数据。标题过长、字段未知、分页大小超出范围以及枚举值无效等情况都会立即失败，并返回符合 SEP-1303 格式的错误，供模型自行修正。
• 无需额外设置。 只需设置一个环境变量即可完成身份验证——HEVY_API_KEY。无需向导，也无需配置文件；只需粘贴适用于你的客户端的配置片段。

架构根据 Hevy 自有的 OpenAPI 规范生成，并会自动重新同步，因此服务能跟进上游变更，不会与之脱节。写入默认采用试运行模式；所有公开端点均有覆盖。

项目状态

维护模式。已完整支持 Hevy 的公开 API。架构根据 Hevy 的 OpenAPI 规范生成；定时工作流 每周会重新同步架构，并在发现任何变更时创建 PR；实时集成测试会检测服务端未公开说明的变更。欢迎通过问题跟踪器提交错误报告和 PR。

先决条件

• Node.js 20 或更高版本（node --version）。
• Hevy Pro 订阅——公开 API 是 Pro 功能。
• 在 https://hevy.com/settings?developer 获取 Hevy API 密钥。

快速设置

最快的方式是使用 setup 子命令——它会验证你的密钥，并写入服务器自动读取的配置文件：

npx @diecoscai/hevy-mcp setup

它会提示你输入 Hevy Pro API 密钥（可在 https://hevy.com/settings?developer 获取），并通过实时 API 验证密钥、询问是否启用写入操作，最后将所有内容保存到 ~/.config/hevy-mcp/config.json（权限模式为 0600）。然后，无需添加 env 块，即可将服务添加到 MCP 客户端：

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"]
    }
  }
}

重启客户端后，22 个 Hevy 工具就会显示在工具面板中。

更喜欢使用环境变量？ 跳过 setup，改为在 env 块中传入 HEVY_API_KEY（以及可选的 HEVY_MCP_ALLOW_WRITES=1）——请参阅配置。环境变量的优先级始终高于配置文件。

关于直接运行的说明。 不带参数运行 npx @diecoscai/hevy-mcp 会启动一个 stdio MCP 服务，并阻塞等待 MCP 客户端通过其 stdin/stdout 连接。你无需在终端中自行运行它——MCP 客户端会启动它。若要以非阻塞方式运行，请使用 npx @diecoscai/hevy-mcp --help、--version 或 setup。

写入工具默认采用试运行模式。 首次要求服务创建或更新任何内容（锻炼、训练计划或身体测量数据）时，你会看到预览负载，而不会进行实际更改。要启用写入功能，请在 setup 期间回答“yes”，或在 env 块中设置 HEVY_MCP_ALLOW_WRITES=1——请参阅安全性 — 试运行写入。

从源代码运行

你也可以从本地克隆直接运行服务，而不必通过 npx 运行。如果你想固定到特定提交、在本地调试工具或运行尚未发布的版本，这种方式会很有用。贡献者请改为使用下文的开发。

git clone https://github.com/diecoscai/hevy-mcp.git
cd hevy-mcp
npm ci
npm run build

然后将 MCP 客户端指向构建好的入口，而不是 npx @diecoscai/hevy-mcp：

{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp/dist/index.js"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

env 块（包括 HEVY_MCP_ALLOW_WRITES）的用法与下方的 npx 示例完全相同。

配置

每个 MCP 客户端都会将服务作为 stdio 子进程启动，并在其 env 块中设置 HEVY_API_KEY。

Claude Desktop

配置文件路径：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json （截至 2026 年，Anthropic 尚未发布 Claude Desktop 的官方 Linux 版本；此路径仅适用于非官方社区版本。）

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

在 env 块中添加 "HEVY_MCP_ALLOW_WRITES": "1"，即可启用写入工具。

Claude Code CLI

claude mcp add hevy --env HEVY_API_KEY=PASTE_YOUR_KEY_HERE -- npx -y @diecoscai/hevy-mcp

要启用写入功能，请追加 --env HEVY_MCP_ALLOW_WRITES=1。

Cursor

配置文件路径：~/.cursor/mcp.json。结构与 Claude Desktop 相同：

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

VS Code（原生 MCP 支持，1.102+）

在工作区根目录下创建 .vscode/mcp.json（如果你的 VS Code 版本支持用户级 MCP 配置，也可以将相同结构放在那里）：

{
  "servers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

如果你使用的第三方 MCP 扩展要求不同的结构，请查阅其文档——VS Code 的原生 MCP 集成是在 1.102 中引入的。

如需故障排查和特定客户端的说明，请参阅 docs/configuration.md；如需了解可通过已连接的 MCP 客户端运行的端到端流程，请参阅 docs/examples.md。

安全性 — 试运行写入

每个 POST 和 PUT 工具处理程序都会在调用时检查 HEVY_MCP_ALLOW_WRITES：

• 未设置（默认）——工具会返回预览，而不会发起 HTTP 请求：

  {
    "dry_run": true,
    "would_send": {
      "method": "POST",
      "path": "/v1/routine_folders",
      "body": { "routine_folder": { "title": "Push days" } }
    },
    "hint": "set HEVY_MCP_ALLOW_WRITES=1 to execute"
  }
  

• 设置为 1——工具会发起实际请求。

Hevy API 对任何资源都没有 DELETE 端点。错误的写入无法从客户端撤销——它会一直保留在你的账户中，直到你在 Hevy 应用中手动修正。试运行是第一道防线；明确选择启用写入是第二道防线。

工具参考（概要）

该服务按资源分组提供 23 个工具。输入架构和示例请参阅 docs/tools.md。

用户

工具	描述
hevy_get_user_info	返回已通过身份验证的用户（姓名、ID、个人资料 URL）。

训练

工具	描述
hevy_list_workouts	分页获取训练（pageSize 为 1-10）。
hevy_get_workout	按 UUID 获取一项训练。
hevy_get_workout_count	账户中的训练总数。
hevy_get_workout_events	增量同步动态：获取指定时间戳以来的 updated / deleted 事件。
hevy_create_workout	记录一项新训练（写入操作——默认试运行）。
hevy_update_workout	完整替换一项现有训练（写入操作——默认试运行）。

训练计划

工具	描述
hevy_list_routines	分页获取训练计划。
hevy_get_routine	按 UUID 获取一项训练计划。
hevy_create_routine	创建训练计划（写入操作——默认试运行）。
hevy_update_routine	完整替换一项训练计划（写入操作——默认试运行）。

训练计划文件夹

工具	描述
hevy_list_routine_folders	分页获取文件夹。
hevy_get_routine_folder	按正整数 ID 获取一个文件夹。
hevy_create_routine_folder	创建文件夹（写入操作——默认试运行）。

动作模板

工具	描述
hevy_list_exercise_templates	分页获取动作库——这是唯一接受最高为 100 的 pageSize 的列表工具。
hevy_search_exercise_templates	按名称搜索模板（不区分大小写的子字符串匹配）。将易读名称（例如“卧推”）解析为 exercise_template_id。分页检索完整目录；结果缓存一小时。
hevy_get_exercise_template	按 ID 获取一个模板（内置模板使用 8 位十六进制值，自定义模板使用 UUID）。
hevy_create_exercise_template	创建自定义动作（写入操作——默认试运行）。
hevy_get_exercise_history	获取指定动作模板的所有已记录组数。

身体测量

工具	描述
hevy_list_body_measurements	分页获取测量记录。记录以日期为键。
hevy_get_body_measurement	获取某个 YYYY-MM-DD 日期的记录。
hevy_create_body_measurement	创建一条新记录（写入操作——默认试运行）。如果该日期已存在，则返回 409。
hevy_update_body_measurement	替换指定日期的记录——未发送的任何字段都会设为 NULL（写入操作——默认试运行）。

环境变量

名称	必需	描述
HEVY_API_KEY	必需*	Hevy Pro API 密钥（UUID v4）。通常通过 MCP 客户端配置的 env 区块传入。
HEVY_MCP_ALLOW_WRITES	可选	设置为 1 以启用真实的 POST / PUT 调用。其他任何值（包括未设置）都会保持试运行模式。
HEVY_MCP_DISABLE_CACHE	可选	设置为 1 以禁用内存中的动作模板缓存（见下文）。
HEVY_MCP_CACHE_TTL_SECONDS	可选	缓存 TTL（秒）。默认为 3600。禁用缓存时忽略此项。

* 除非你运行过 npx @diecoscai/hevy-mcp setup，否则必须设置 HEVY_API_KEY。该命令会将密钥（以及写入设置）保存到 ~/.config/hevy-mcp/config.json。解析顺序：优先使用环境变量；环境变量未设置时回退到配置文件。HEVY_MCP_ALLOW_WRITES 与文件中的 allowWrites 也遵循相同的优先级。

动作模板缓存

hevy_list_exercise_templates 和 hevy_get_exercise_template 使用每个进程内存中的缓存（Map，按条目设置 TTL，默认为 1 小时）。模板目录很大，且在一次会话期间基本不会变化，因此重复解析（例如在创建训练计划时查找 ID）只需一次 HTTP 往返，而不必多次请求。

hevy_create_exercise_template 在成功写入后会使缓存中的列表部分失效；单个模板条目会保留（创建其他自定义模板不会使它们过时）。缓存不会跨进程持久化。

将 HEVY_MCP_DISABLE_CACHE 设为 1 可完全禁用缓存；也可以通过 HEVY_MCP_CACHE_TTL_SECONDS 缩短或延长缓存的有效时间。

Webhook —— 有意不提供

Hevy 的公共 API（api.hevyapp.com/v1/*）未记录 webhook 订阅；相关端点位于私有 Web 会话 API（/webhook-subscription、/subscribe_to_webhook）中，该 API 使用不同的身份验证方案（refresh-token bearer，而非本服务使用的 api-key 标头）。提供这些工具，要么（a）向所有用户提供只会抛出“端点不可用”错误的处理程序，要么（b）要求用户仅为注册 URL 就交出 Web 会话令牌。

如果你需要增量同步，请使用带有 since 时间戳的 hevy_get_workout_events —— 它涵盖已更新和已删除的训练记录，也是公共 API 提供的唯一变更检测机制。

如果 Hevy 在公共 OpenAPI 规范中发布 webhook，订阅工具将会在此处推出，并采用与其他写入操作相同的试运行门控。

其他一些 Hevy MCP 服务会调用 Hevy 的私有 Web 会话 API 来提供 webhook 工具。本服务特意仅使用有文档记录的公共 API。

规范 ≠ 现实

公共 OpenAPI 文档（自行标注版本 0.0.1）在多个方面与在线服务不一致——POST /v1/exercise_templates 的包装格式错误、CustomExerciseType 的枚举值错误、PUT /v1/routines/{id} 拒绝 folder_id、成功创建模板时返回纯文本等。本服务实现的是实际服务端接受的内容。已确认的差异完整列表见 docs/api-quirks.md，并可通过 scripts/verify-api.sh 探测套件重新验证（该套件位于 GitHub 仓库中，不包含在 npm 压缩包内）。

开发

适用于参与服务本身开发的贡献者。如果你只想在本地使用自己的 Hevy 账户运行服务，请改用从源代码运行。

git clone https://github.com/diecoscai/hevy-mcp.git
cd hevy-mcp
npm ci
npm run build
npm test

实用脚本：

脚本	用途
npm run dev	对源代码运行 tsc --watch。
npm run lint	使用 Biome 对 src/ + tests/ 进行 lint。
npm run format	使用 Biome 自动格式化。
npm run check	使用 Biome 组合检查 lint + 格式。
npm run coverage	使用 V8 覆盖率运行 Vitest。
npm run smoke	端到端检查：npm ci && build && test && lint + stdio 探测 + 语言门控。
npm run inspect	针对构建后的服务启动 MCP Inspector。

添加工具：

1. 在 src/validate.ts 中添加 Zod 模式（每个对象都使用 .strict()）。
2. 将工具规范（名称、描述、JSON Schema inputSchema）添加到 src/index.ts 中的 TOOLS 数组。
3. 在分发 switch 中添加 case；访问网络前始终调用 validateInput(name, rawArgs)；使用 guardWrite 包装写入操作。
4. 在 tests/ 下扩展测试（至少包含模式测试 + 负向探测）。
5. 更新本 README 中的表格。

更多信息请参阅 CONTRIBUTING.md。

安全

• API 密钥保存在 MCP 客户端的配置文件中（威胁模型与粘贴到该文件中的任何其他密钥相同）。服务绝不会读取或写入自己的配置文件。
• 写入操作默认采用试运行模式；在 Hevy 应用中轮换泄露的密钥，并将新密钥粘贴到客户端配置中，整个过程不到一分钟。
• 服务只会调用有文档记录的 /v1/* 端点——不会访问私有 API、发送遥测数据或扇出请求到第三方。

完整威胁模型请参阅 docs/security.md。

贡献

欢迎贡献。提交 PR 前，请阅读 CONTRIBUTING.md。

许可证

MIT。

链接

• Hevy 公共 API 文档 — https://api.hevyapp.com/docs
• MCP 注册表条目 — https://registry.modelcontextprotocol.io/v0/servers?search=io.github.diecoscai/hevy-mcp（发布后填充）
• 问题跟踪 — https://github.com/diecoscai/hevy-mcp/issues
• MCP 规范 — https://modelcontextprotocol.io