chrisdoc/hevy-mcp

Manage your Hevy workouts, routines, folders, and exercise templates. Create and update sessions faster, organize plans, and search exercises to build workouts quickly. Stay synced with changes so your training log is always up to date.

Hevy MCP – 连接 Hevy 健身应用的 AI 友好桥梁

简介 – hevy-mcp 是一个实现 Model Context Protocol (MCP) 的小型开源服务器。它将 Hevy 锻炼追踪 API（只读和可写端点）公开为一组 MCP 工具，供 Claude、Codex、Cursor 或其他任何 MCP 兼容客户端调用。

重要性 – 通过将个人锻炼数据转化为标准工具接口，该服务器让大语言模型助手能够推理您的训练历史、回答自然语言问题，甚至创建或更新锻炼、常规、自定义练习和身体测量记录——所有这些都在用户的明确同意下进行。

核心功能（23 个工具）

类别	示例工具	功能
训练分析	`get-training-summary`、`analyze-workout-progress`（引导提示）	总结数周的锻炼和身体测量数据，发现缺口，显示最频繁的练习。
锻炼	`get-workouts`、`get-workout`、`create-workout`、`update-workout`、`replace-workout-exercises`、`get-workout-events`	列出过去的会话，获取单个锻炼的详细信息，记录新的已完成锻炼，编辑元数据或练习组。
常规与文件夹	`search-routines`、`get-routines`、`get-routine`、`create-routine`、`update-routine`、`create-routine-folder`、`get-routine-folder`	发现已保存的常规，读取常规布局，创建新的可复用常规或在文件夹中组织。
练习目录	`search-exercise-templates`、`get-exercise-template`、`create-exercise-template`、`get-exercise-history`	浏览 Hevy 的完整练习库，添加自定义模板，检索特定练习的过去执行组。
身体测量	`get-body-measurements`、`get-body-measurement`、`create-body-measurement`、`update-body-measurement`	追踪体重、体脂率等；添加或更正条目。
诊断	`feedback`	出现问题时发送隐私安全的简短报告。

所有修改工具都标记为 MCP 确认，因此兼容客户端会在任何数据更改操作前询问您。

工作原理

AI 助手 → MCP (流式 HTTP 或 stdio) → hevy-mcp 服务器 → Hevy API

托管模式 – Cloudflare Worker 在 https://mcp.hevy-mcp.dev/mcp 运行服务器。客户端发送固定的 Authorization: Bearer <Hevy-API-密钥> 标头；worker 验证密钥，缓存 15 分钟，然后转发给 Hevy。
本地模式 – 在您自己的机器上运行 npm 包（或 Docker 镜像）。服务器从 HEVY_API_KEY 环境变量读取 API 密钥，并通过 stdio 与客户端通信。
OAuth 层 – 托管的 worker 还提供可选的 OAuth 2.1 流程（供 Claude.ai 自定义连接器使用），将密钥加密存储在授权中，因此无法设置静态标头的客户端也能进行身份验证。

快速入门（最快路径）

获取 Hevy API 密钥 – 需要 Hevy PRO 订阅（设置 → 开发者 → API 密钥）。
连接 – 使用公共端点 https://mcp.hevy-mcp.dev/mcp。
- 对于 Codex：在环境中设置 HEVY_API_KEY，并使用 codex mcp add hevy --url https://mcp.hevy-mcp.dev/mcp --bearer-token-env-var HEVY_API_KEY 添加服务器。
- 对于其他客户端，提供相同的 URL 和固定的 Authorization: Bearer <密钥> 标头。
提问 – 例如：“给我过去四周的训练总结。”助手将调用 get-training-summary 并返回简洁的报告。

如果您希望完全控制，可以本地运行服务器：

npm install -g hevy-mcp   # 或使用 npx/bunx/docker
set HEVY_API_KEY=your-key
export HEVY_API_KEY=your-key
npx -y hevy-mcp            # 启动 stdio MCP 服务器

配置您的客户端以启动该命令（参见 README 中的 Claude Desktop、Cursor、Google Antigravity 等）。

生态系统与工具

@chrisdoc/hevy-cli – 一个直接与 Hevy API 通信的独立命令行客户端（无 MCP）。适合脚本编写或快速数据转储。
Claude 插件 – .claude-plugin/plugin.json 和 .mcp.json 允许 Claude.ai 通过 OAuth 连接到托管端点，公开 Hevy 锻炼技能。
Docker 镜像 – ghcr.io/chrisdoc/hevy-mcp:latest（支持 linux/amd64 和 linux/arm64）。
MCP 排行榜徽章 – 显示该服务器在公共 MCP 实现中的排名。

适用人群

专注于健身的 AI 助手 – 让个人 LLM 教练分析您的进度、建议常规调整或记录您刚完成的锻炼。
开发自定义代理的开发者 – 使用 23 个现成工具代替手动构建 Hevy API 调用。
高级用户 – 将 hevy-mcp 服务器与其他 MCP 服务（例如营养追踪器）结合，构建统一的健康助手。

许可证与贡献

根据 MIT 许可证授权。
欢迎贡献；有关自托管 Cloudflare Worker、添加新工具或改进文档的详细信息，请参阅 CONTRIBUTING.md。

总结： hevy-mcp 将您的个人 Hevy 锻炼数据转换为干净、AI 就绪的接口，使任何 MCP 兼容的助手都能进行自然语言查询和安全、确认的修改操作。