hevy-mcp-server

用于 Hevy 锻炼追踪 API 的 MCP 服务器。为 LLM 提供对锻炼、常规训练、动作模板、每个动作的历史记录和身体测量数据的读写访问。

涵盖 Hevy 公共 API（v0.0.1）的全部 15 个端点，共 27 个工具。

要求

• Node.js 18+

• Hevy Pro 订阅——API 访问仅限 Pro 用户

• 来自 https://hevy.com/settings?developer 的 API 密钥

Related MCP server: hevy-mcp-server

安装

pnpm install
pnpm run build

配置

在 MCP 客户端配置中设置 HEVY_API_KEY。对于 Claude Desktop，在 claude_desktop_config.json 中：

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

远程/HTTP 模式，本地运行：

TRANSPORT=http PORT=3000 pnpm start   # POST JSON-RPC to http://127.0.0.1:3000/mcp

交互式检查工具：

HEVY_API_KEY=your-key pnpm run inspect

部署（用于 Claude 移动端 / claude.ai 连接器）

Claude 从 Anthropic 的云端连接自定义连接器，而不是从你的设备，因此移动端和 claude.ai 需要通过公共 HTTPS 访问此服务。Claude Code 和 Claude Desktop 不需要——请改用 stdio。

1. 生成路径密钥

openssl rand -hex 32

如果未设置 MCP_PATH_SECRET，服务器将拒绝在非回环接口上启动，因为持有你的 Hevy 密钥的公共端点相当于你账户的开放代理。设置后，端点移至 /mcp/<secret>，所有其他路径返回 404——包括错误的密钥，因此探测主机不会暴露那里存在 MCP 服务器。

2. 部署

附带的 Dockerfile 和 railway.json 可直接在 Railway、Render 或 Fly 上使用。镜像设置 TRANSPORT=http 和 HOST=0.0.0.0，并以非 root 用户运行。在平台仪表板中设置两个变量：

PORT 由平台注入。/healthz 是未认证的存活探针。

3. 验证

curl -s https://your-app.up.railway.app/healthz
# {"status":"ok","server":"hevy-mcp-server","version":"1.0.0"}

4. 添加连接器

在 claude.ai 浏览器中——无法从移动应用添加连接器：

1. 自定义 → 连接器 → 添加自定义连接器

2. URL：https://your-app.up.railway.app/mcp/<secret>

3. 在手机上打开聊天，并在 + → 连接器 下启用它

将那个 URL 视为密码：它是互联网与你的训练日志之间的唯一屏障。如果泄露，请轮换 MCP_PATH_SECRET 并重新添加连接器。

工具

训练 — hevy_list_workouts、hevy_get_workout、hevy_count_workouts、hevy_list_workout_events、hevy_create_workout、hevy_update_workout

会话 — hevy_start_session、hevy_get_active_session、hevy_finish_session、hevy_cancel_session

常规训练 — hevy_list_routines、hevy_get_routine、hevy_create_routine、hevy_update_routine

常规训练文件夹 — hevy_list_routine_folders、hevy_get_routine_folder、hevy_create_routine_folder

动作模板 — hevy_search_exercise_templates、hevy_list_exercise_templates、hevy_get_exercise_template、hevy_create_exercise_template

进度 — hevy_get_exercise_history、hevy_list_body_measurements、hevy_get_body_measurement、hevy_create_body_measurement、hevy_update_body_measurement

账户 — hevy_get_user_info

每个读取工具都接受 response_format: "markdown" | "json"。Markdown 是默认格式，专为 LLM 阅读优化；JSON 是完整的结构化负载。无论格式如何，structuredContent 始终会被填充。

示例

“我这周练了什么？” → 使用 page_size=5 调用 hevy_list_workouts。返回标题、时长、动作列表和每次会话的总训练量。

“记录今天的卧推：3x8，60kg” → 使用 query="bench press" 调用 hevy_search_exercise_templates 获取 id，然后使用三组 { weight_kg: 60, reps: 8 } 调用 hevy_create_workout。

“我现在开始练腿” → 使用 title="Leg Day" 调用 hevy_start_session。开始时间由服务器端标记，会话在 Hevy 中显示为进行中。完成后，使用你执行的内容调用 hevy_finish_session，以实际时长结束会话。

“我的深蹲在变强吗？” → 使用 query="squat" 调用 hevy_search_exercise_templates，然后使用 start_date 调用 hevy_get_exercise_history。返回每条记录的组，按最新优先，以及按估算 1RM 的最佳组。

设计说明

先搜索再写入。 Hevy 没有服务器端动作搜索，但每次写入都需要 exercise_template_id。hevy_search_exercise_templates 分页浏览目录（最多 30 页，每页 100 条），并在本地按标题、肌肉群、器械和仅自定义进行过滤。先让模型使用此工具——id 无法猜测。

更新是替换，不是补丁。 hevy_update_workout、hevy_update_routine 和 hevy_update_body_measurement 会覆盖整个资源；任何省略的内容都会被删除或置空。这三个工具都带有 destructiveHint: true，其描述会告诉模型先读取当前状态。这是仅有的三个破坏性工具——Hevy API 没有删除端点。

实时会话是标题约定，不是服务器状态。 Hevy 的 API 没有开始锻炼的端点，也无法驱动应用内计时器，因此 hevy_start_session 会预先创建一个标题为 🔴 In Progress — <title> 的真实锻炼，而 hevy_finish_session 会用真实结束时间重写它。该标记是唯一持久化的句柄——服务器在请求之间不保存任何状态，因此任何设备上的任何聊天都可以通过扫描最近的锻炼来找到打开的会话。代价是未完成的会话会保留在日志中，而且由于 Hevy 不提供删除功能，hevy_cancel_session 只能重新标记它，无法移除。

一切都是公斤。 API 没有单位字段。输入字段命名为 weight_kg，这样模型发送的内容就没有歧义，markdown 输出会同时显示两者（60 kg (132.3 lb)），因此美国读者无需心算转换。

页面大小上限在客户端强制执行。 Hevy 对过大的页面返回裸 400。Zod 模式将每个端点限制在其文档规定的上限（大多数为 10，动作模板为 100），因此模型会收到精确的消息，而不是失败的请求。

错误会解析为下一步操作。 404 会指出为该资源生成有效 id 的工具。身体测量数据上的 409 会指向更新工具。403 会说明 API 访问需要 Pro。

宽松的输出模式。 Hevy 的文档警告此 0.0.1 API 可能随时更改结构。输出模式使用 passthrough() 和可选字段，因此上游字段的添加不会导致工具硬失败。

项目结构

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # API limits, enums, character limit
├── types.ts               # interfaces for every Hevy entity
├── services/
│   └── hevy-client.ts     # fetch wrapper, auth, error → guidance mapping
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # pagination, truncation, format dispatch
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── workouts.ts
    ├── sessions.ts         # in-progress workout tracking
    ├── routines.ts
    ├── exercise-templates.ts
    └── progress.ts

注意事项

• Hevy API 官方版本为 0.0.1，其文档警告结构可能更改或被弃用。

• 常规训练的文件夹在创建后无法更改——更新端点不接受 folder_id。

• 搜索中的器械过滤匹配动作标题，因为 API 不将器械作为模板字段暴露。

• hevy_create_exercise_template 返回数字 id，与 API 中其他地方使用的字符串 id 不同。

测试

pnpm run build
pnpm test         # 45 checks: MCP handshake, tools, sessions, formatting, errors (mocked API)
pnpm run test:http  # 13 checks: path-secret gating, health check, origin allowlist

两个测试套件都针对本地模拟运行，因此无需 API 密钥或网络访问。