Hevy MCP

社区

通过 MCP 在 AI 助手中管理您的 Hevy 训练数据。

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

77FMRS · B

Hevy MCP Server 是一个专为 Hevy 健身应用设计的非官方 MCP 服务器。它提供 26 个工具，用于管理训练、日常计划、动作模板和身体测量数据，并需要 Hevy API 密钥（需要 Hevy PRO）。它支持多种 MCP 客户端，可通过 npm 或 Docker 在本地运行，并可通过 Cloudflare Worker 托管的 HTTP 端点用于远程访问。

最强项 · 文档质量 18/20 最弱项 · 可靠性 12/20

可靠性

12/20

安全与权限

16/20

维护活跃度

16/20

文档质量

18/20

安装易用性

15/20

查看各项评分依据

可靠性 12/20: 证据：仓库包含server.json清单，指向npm包'hevy-mcp'，并描述stdio传输。README列出了26个工具及资源。仓库有CI工作流（build-and-test.yml）和Codecov徽章，表明存在测试和覆盖率。但静态审查未执行代码，无法验证实际行为或错误处理。扣分原因：没有提交的单元测试或集成测试的直接证据，边角情况和失败模式未证实。因此，上限为12。
安全与权限 16/20: 证据：服务器需要HEVY_API_KEY，标记为必需且秘密。README强调不在源码控制、URL或日志中包含密钥，并提供安全指南。部署的Cloudflare Worker使用Bearer令牌，不存储密钥，并支持OAuth，密钥以加密形式存储。变更工具具有MCP突变注释，允许客户端确认。未发现明显危险操作，如无确认的删除。扣分原因：未提供代码级证据表明所有工具都正确实现确认或输入验证。但未发现红旗。
维护活跃度 16/20: 证据：MIT许可证，活跃的GitHub仓库（385颗星，14个未解决问题，未归档）。README显示持续开发，多版本（version 5.1.0），并详细说明CLI、Worker和Docker部署。有贡献指南和CI。扣分原因：无法从静态审查确认提交频率或问题响应。然而，仓库看起来维护良好。
文档质量 18/20: 证据：全面的README，涵盖安装、认证、配置、工具、资源、故障排除、安全和隐私。包含清晰的环境变量表、配置示例、hosted端点和本地安装文档。包含演示和示例。扣分原因：文档主要来自README，这是不可信的证据，但静态分析显示其详细且有结构。没有扣分，但鉴于不可信来源，上限为18。
安装易用性 15/20: 证据：README提供了多种安装方式：npm（npx）、bunx、Docker、hosted Cloudflare端点。为Claude Desktop、Cursor、Codex和Google Antigravity提供逐步客户端配置示例。环境变量HEVY_API_KEY有明确文档。由于CI和测试证据有限，未能达到15以上的上限。扣分原因：静态审查未验证安装步骤是否实际正常工作，但文档提供了明确的指导。

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

查看 FMRS 评分方法 →

选型与风险

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

适合谁

Hevy PRO 用户希望 AI 助理直接读写其训练数据
喜欢使用 Claude、Cursor、Codex 等 MCP 客户端进行训练跟踪的人
需要从训练数据生成摘要和洞察的任何人

不适合谁

没有 Hevy PRO 订阅的用户（API 密钥需要）
希望无需 API 密钥即可使用的用户
需要删除工作流的人（Hevy API 不提供删除端点）

所需权限

需要 HEVY_API_KEY 环境变量以进行 Hevy API 认证
可通过工具创建、更新和替换训练、日常计划、文件夹、模板和身体测量数据
读取操作可获取训练、日常计划、文件夹、模板、历史和用户信息

风险与副作用

API 密钥如果泄露可能被滥用；不要在 URL、日志或截图等中暴露
创建操作在重试时可能产生重复项；更新操作会替换现有记录
该服务器将数据发送到 Hevy API，并可能将遥测数据发送到外部服务（除非禁用）

安装接入

准备工作

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

HEVY_API_KEY 必填密钥 Hevy 应用的 API 密钥，用于认证；目前需要 Hevy PRO 订阅，在 Hevy 应用中创建。

HEVY_MCP_HTTP_BEARER_TOKEN 可选密钥可选；本地 HTTP 模式非回环绑定时的访问令牌，不能使用 Hevy API key。

其他可选配置项（7 个）

HEVY_MCP_API_TIMEOUT 可选可选；Hevy API 请求超时时间（毫秒），默认 30000。

HEVY_MCP_DEBUG 可选可选；设为 1 时在 stderr 输出诊断信息。

HEVY_MCP_TELEMETRY 可选可选；设为 0 可在启动前禁用遥测。

XDG_CACHE_HOME 可选可选；修改 npm 更新检查缓存目录的根路径。

SENTRY_DSN 可选可选；Sentry 错误上报地址覆盖，留空则禁用 Sentry 上报。

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

MCP_ALLOWED_ORIGINS 可选可选；自托管部署时覆盖浏览器请求的来源允许列表。

在 Hevy 应用中获取 Hevy API 密钥（需要 Hevy PRO）。
使用 npx 配置 MCP 客户端：'npx -y hevy-mcp'，并设置环境变量 HEVY_API_KEY。或者使用 Docker：'docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest'。
将提供的 JSON 配置添加到客户端的 mcpServers 配置中。
重启或重新连接您的 MCP 客户端。

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 账号已连接？”——get-user-info 应返回账号 ID、显示名称和公开主页链接，即可确认配置成功。

常见排障

确保 Node.js 20 或更高版本已安装
确认 HEVY_API_KEY 已正确设置为环境变量
重启或重新连接 MCP 客户端（配置更改后）
检查 API 密钥是否有效且属于 Hevy PRO 账户

试试这样问

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

给我最近四周的训练总结。
分析我过去六周的训练：每周锻炼次数、最常训练的动作，以及不一致的地方。
找到我的推日（push-day）模板，并列出它的动作和组数。
搜索标题包含 squat 的动作模板。

工具能力 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。

使用场景

分析训练进度：总结 1-12 周的训练和身体测量数据。

用自然语言提问：查找最近的训练、经常训练的动作、一致性差距、日常计划详情或动作历史。

规划并记录训练：创建或更新训练、日常计划、文件夹、自定义动作和身体测量数据。

搜索而不产生巨大响应：发现日常计划和动作模板，结果紧凑且 AI 友好。

支持客户端

Claude Desktop

Cursor

Codex

Antigravity

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

详细介绍

Hevy MCP Server 是一个开源 Model Context Protocol (MCP) 服务器，用于 Hevy 健身与训练追踪应用。它使 AI 助手能够通过经过身份验证的 Hevy API 请求读取、分析、创建和更新您的 Hevy 训练、日常计划、动作模板和身体测量数据。该服务器通过 npm 包以 stdio 方式运行，需要 Hevy API 密钥（需要 Hevy PRO 订阅）。它注册 26 个工具、4 个资源和 2 个引导提示。

同仓库的其他 Server

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