Hevy MCP Server

社区

通过 Hevy API 管理健身、训练计划和运动数据

分类: 其他第 30 / 230
Stars: ★ 509 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Node.js 20+ · Docker · Bun · 远程托管（无需本地环境）
凭据: 需要 API Key / 凭据
许可证: MIT
最近提交: 1 天前
工具数: 26

66FMRS · C

Hevy MCP Server 是一个功能丰富的 MCP 服务器，提供 26 个工具用于管理 Hevy 数据，支持本地 stdio 和托管 Streamable HTTP 两种模式。它适合需要 AI 辅助训练分析的高级用户，但要求 Hevy PRO 订阅，且不是官方产品。安全方面需要注意 API 密钥保护和遥测隐私。

最强项 · 文档质量 17/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

14/20

维护活跃度

12/20

文档质量

17/20

安装易用性

14/20

查看各项评分依据

可靠性 9/20: 清单内部一致（npm hevy-mcp 5.1.0、stdio 传输、必需的 HEVY_API_KEY 且标记为 secret），README 宣称 26 个工具与表格实际列出 26 个一致，读写工具划分合理，并如实说明 Hevy API 无删除端点所以没有删除工具。但这是静态评审：所供材料中没有任何真实 CI 工作流文件或已提交的测试源码，无法证明服务器能干净启动并完成 MCP 初始化与工具列表握手。文档提到的错误处理（API 超时回退、HEVY_MCP_DEBUG、SDK v1.29.0 默认参数兼容性说明）体现用心，但都属于 README 声称而非可验证证据；按校准规则可靠性与执行证据挂钩，故封顶并扣分。
安全与权限 14/20: 对受评的 Node stdio 服务器而言，密钥在清单中标记为必需且 secret，文档说明本地模式经子进程环境变量传入、绝不放 URL、日志与屏幕截图，且创建/更新类工具带 MCP mutation 注解以便客户端确认；不存在删除/部署/支付类工具，因此没有不可逆默认操作。遥测默认开启但提供显式关闭开关和详细隐私白名单，明确禁止采集原始参数、结果、标识符与正文。扣分项：遥测默认开启；单一 API 密钥对整个账户具有读写权限，确认机制依赖客户端而非服务器强制；README 中的 Origin 白名单、Worker 不存储密钥、OAuth 加密等安全声明属于未被评分的 Cloudflare 兄弟服务器，不能为 Node 包加分，且加密/校验实现无法静态核实。
维护活跃度 12/20: 仓库未归档、有 MIT 许可证，版本号已达 5.1.0，README 异常详尽并引用 CONTRIBUTING.md 与 CI 徽章，说明项目在持续演进；但 CI/Codecov 徽章属于不可信声称。扣分项：所给材料中没有提交历史、发布日期、依赖更新记录或 issue 响应时效证据，无法确认"持续维护"；14 个未关闭 issue 表明存在可见积压。整体属于"活跃但治理与版本证据不完整"，按证据缺失扣分。
文档质量 17/20: 文档分层且深入：快速开始、托管与本地两种模式、Codex/Claude Desktop/Cursor/Antigravity/bunx/Docker/add-mcp 多种客户端配置示例、完整 26 工具表与资源表、带默认值和注解的环境变量参考、缓存行为、遥测与隐私披露、安全与变更语义、故障排查，甚至记录了 MCP SDK v1.29.0 的参数兼容性细节。限制（需 Hevy PRO、无删除端点、OAuth 为可选）均如实披露。扣分项：缺少逐工具的完整参数/输入模式参考，无明确 API 限流与成本信息，无可见更新日志，CONTRIBUTING.md 与 CLI README 仅被引用而未提供。
安装易用性 14/20: 安装路径确实简洁：获取 API key 后，要么配置托管 URL 加 Authorization 头（零安装），要么用 `npx -y hevy-mcp` 加 HEVY_API_KEY 本地运行，且注明 Node.js 20+ 要求并给出多种主流客户端的配置示例与安装排障。扣分项：静态校准则要求若无可验证的 CI 与已提交测试文件，setup 上限为 15；Docker、Antigravity 手动配置、本地 HTTP 模式等路径仍需较多手工步骤，密钥需要在每个客户端环境中小心管理，存在一定脆弱性。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么访问网络修改第三方账户数据

适合谁

Hevy PRO 用户
希望用 AI 助手分析训练数据和规划锻炼的健身爱好者
需要在多个 MCP 客户端（如 Claude Desktop、Codex、Cursor）中集成 Hevy 数据的开发者

不适合谁

没有 Hevy PRO 订阅的用户
需要删除功能的用户（Hevy API 不提供删除端点）
寻找官方支持的用户（此服务器由社区维护，非 Hevy 官方）

所需权限

需要 Hevy API 密钥（`HEVY_API_KEY`）
能够读取和写入 Hevy 数据（锻炼、计划、动作模板、身体测量等）
托管端点会向 Hevy 发送 API 密钥，并在每个请求中验证

风险与副作用

API 密钥泄露风险：密钥不应出现在源代码、URL、日志或截图中。
误操作风险：创建操作在重试时可能产生重复数据；更新操作会替换现有记录。
数据隐私：本地包默认启用遥测（可禁用），可能发送错误和指标到外部服务。
依赖第三方服务：托管端点依赖 Cloudflare Worker，存在可用性风险。
库存路由：请求可能需要确认，但客户端支持程度不同。

安装接入

准备工作

运行环境：Node.js 20+ · Docker · Bun · 远程托管（无需本地环境）

HEVY_API_KEY 必填密钥 Hevy 应用的 API 密钥，需 Hevy PRO 订阅才能在 Hevy 中生成。

HEVY_MCP_HTTP_BEARER_TOKEN 可选密钥本地 HTTP 模式非回环地址绑定时必需的独立令牌，不要使用 Hevy API 密钥。

其他可选配置项（8 个）

HEVY_MCP_API_TIMEOUT 可选 Hevy API 请求超时时间（毫秒），默认 30000，仅本地 stdio。

HEVY_MCP_DEBUG 可选设为 1 可在 stderr 输出隐私受限的诊断信息。

HEVY_MCP_TELEMETRY 可选设为 0 可在启动/导入前完全禁用本地 Node 遥测。

XDG_CACHE_HOME 可选更改 npm 更新检查缓存（hevy-mcp/update-check.）的根目录。

SENTRY_DSN 可选 Sentry 兼容的错误上报目标覆盖，留空则禁用 Sentry 导出。

SENTRY_RELEASE 可选覆盖本地 Sentry 错误事件附带的版本标签。

MCP_ALLOWED_ORIGINS 可选自托管部署可覆盖浏览器来源白名单。

MCP_DISABLE_ORIGIN_CHECK 可选仅在开发环境禁用来源校验，切勿在生产 Worker 上设置。

在 Hevy 中创建 API 密钥（需要 Hevy PRO）。
本地安装：在 MCP 客户端配置中添加 npx -y hevy-mcp，并设置环境变量 HEVY_API_KEY。
或使用托管端点：将 https://mcp.hevy-mcp.dev/mcp 作为 Streamable HTTP URL，并在请求头中携带 Authorization: Bearer <HEVY_API_KEY>。
重启或重新连接客户端，然后询问第一个问题。

claude_desktop_config.json

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": [
        "-y",
        "hevy-mcp"
      ],
      "env": {
        "HEVY_API_KEY": "your-hevy-api-key"
      }
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "hevy": {
      "command": "npx",
      "args": [
        "-y",
        "hevy-mcp"
      ],
      "env": {
        "HEVY_API_KEY": "your-hevy-api-key"
      }
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

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

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

重启客户端后，在工具列表中确认出现 hevy 服务器的 26 个工具（如 get-user-info），然后问“Which Hevy account is connected?”，若能返回用户 ID 和显示名即证明连接成功。

常见排障

如果服务器没有出现，请重启或重新连接 MCP 客户端。
如果 `npx` 失败，确保 Node.js 20 或更高版本已安装，然后运行 `npx -y hevy-mcp --version`。
如果 Codex 看不到服务器，运行 `codex mcp list`，确认 'hevy' 条目后开始新会话。
如果托管认证失败，确认密钥有效、属于 Hevy PRO 账户，并且作为 `Authorization: Bearer <HEVY_API_KEY>` 发送。
如果需要诊断，设置 `HEVY_MCP_DEBUG=1`，诊断输出到 stderr，不会影响 MCP 消息。
如果本地认证失败，确认密钥有效并在子进程环境中作为 `HEVY_API_KEY` 可用。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

分析我最近六周的训练情况，显示每周的锻炼次数、最常练的动作，并引用具体的锻炼记录作为依据。
给我最近四周的训练摘要。
查找标题里包含 squat 的动作模板。
找到我的推日（push day）训练计划，并列出其中的动作和组数安排。

工具能力 26

get-training-summary 只读

一次调用总结 1-12 周的训练活动和身体测量趋势。

get-workouts 只读

从最新到最旧列出锻炼，包含动作和计时详情。

get-workout 只读

按 ID 获取单个锻炼的完整详情。

get-workout-count 只读

返回账户的总锻炼次数。

get-workout-events 只读

列出自某个时间戳以来的锻炼更新和删除事件。

create-workout 写入

在 Hevy 中创建已完成的锻炼。

update-workout 写入

按 ID 修补锻炼元数据；未提供的字段和所有动作保持不变。

replace-workout-exercises 写入

替换所有动作和组，同时保留锻炼元数据。

展开其余 18 个工具

search-routines 只读

搜索训练计划标题，返回紧凑元数据以供发现。

get-routines 只读

列出自定义和默认的训练计划。

get-routine 只读

按 ID 获取一个训练计划及其动作配置。

create-routine 写入

创建可复用的训练计划。

update-routine 写入

替换现有训练计划的内容。

get-routine-folders 只读

列出默认和自定义的训练计划文件夹。

get-routine-folder 只读

按 ID 获取一个训练计划文件夹的元数据。

create-routine-folder 写入

创建一个训练计划文件夹。

get-exercise-templates 只读

列出带有器械和肌肉元数据的动作模板。

get-exercise-template 只读

按 ID 获取一个动作模板的完整元数据。

search-exercise-templates 只读

按标题子串搜索整个动作目录。

create-exercise-template 写入

创建自定义动作模板。

get-exercise-history 只读

获取一个动作模板的过往训练组。

get-body-measurements 只读

列出有日期的身体测量记录。

get-body-measurement 只读

获取某个日期的身体测量条目。

create-body-measurement 写入

创建一条有日期的身体测量记录。

update-body-measurement 写入

更新现有日期的身体测量记录。

get-user-info 只读

返回用户的 ID、显示名称和公开个人资料 URL。

使用场景

分析最近几周的训练进度、频率、动作分布和身体测量趋势。

用自然语言查询最近的锻炼、常用动作、计划详情或动作历史。

创建或更新锻炼、训练计划、文件夹、自定义动作和身体测量记录。

搜索动作模板和训练计划，获取简洁、适合 AI 的结果。

支持客户端

Claude Desktop

Codex

Cursor

Antigravity

依据项目文档列出，未经本站实测。

详细介绍

Hevy MCP Server 是一个开源的 Model Context Protocol (MCP) 服务器，用于 Hevy 健身与训练追踪应用。它允许 AI 助手通过身份验证的 Hevy API 请求来读取、分析、创建和更新你的 Hevy 锻炼、训练计划、动作模板和身体测量数据。支持多步工作流、提示词和多种工具，可进行训练分析、动作搜索和计划管理。

同仓库的其他 Server

源版本 1f9f9189883c 数据同步于 2026-10-11 查看 FMRS 评分方法