Scan to join WeChat grouparticle
README
🚀 Hevy MCP服务器
这是用于Hevy健身API的MCP服务器，具备HTTP传输和会话管理功能。它完全用Rust编写，以实现低内存管理，同时还提供了良好的异步支持！
🚀 快速开始
使用Docker快速开始
docker pull ghcr.io/zelosleone/hevy-mcp-server:latest
docker run -e HEVY_API_KEY=your-api-key -p 5000:5000 ghcr.io/zelosleone/hevy-mcp-server:latest
📋 要求
- Hevy PRO订阅
- 从https://hevy.com/settings?developer 获取的Hevy API密钥
🛠️ 配置
| 变量 | 是否必需 | 默认值 | 描述 |
|------|----------|---------|-------------|
| HEVY_API_KEY | 否 | -- | 来自Hevy开发者设置的API密钥。启用单用户模式。如果未设置，每个客户端必须在URL参数中提供 ?apikey=xxx。 |
| HEVY_HTTP_ADDR | 否 | 127.0.0.1:3000（源码） / 0.0.0.0:5000（Docker） | 绑定HTTP服务器的套接字地址 |
| HEVY_MCP_PATH | 否 | / | MCP端点的HTTP路由路径。如果缺少前导 /，会自动添加。 |
| HEVY_SESSION_TIMEOUT_SECS | 否 | 3600 | 会话过期前的非活动秒数 |
🎮 操作模式
单用户模式
设置 HEVY_API_KEY 环境变量。所有会话共享此密钥，无需查询参数。
HEVY_API_KEY=your-api-key ./target/release/hevy-mcp-server
多用户模式
不设置 HEVY_API_KEY。每个客户端在初始化期间必须将自己的密钥作为查询参数传递：
POST /?apikey=xxx
如果两种方法都未提供密钥，服务器将返回错误。
🌐 HTTP传输
服务器在配置的路径（默认为 /）上公开两个端点：
POST {path} -- MCP请求
发送JSON-RPC请求和通知。第一个请求必须是 initialize 调用。响应包含一个 Mcp-Session-Id 头，后续所有请求都必须发送该头。
POST /
Content-Type: application/json
Mcp-Session-Id: <session-id>
会话生命周期
- 每个
initialize请求都会创建一个新会话，并通过Mcp-Session-Id响应头返回一个UUID。 - 所有非
initialize请求都必须包含Mcp-Session-Id头；没有该头的请求将被拒绝。 - 会话在
HEVY_SESSION_TIMEOUT_SECS秒的非活动时间后（默认3600秒）自动清理。后台任务每60秒检查一次过期会话。 - 会话也可以通过
DELETE端点显式删除。
🛠️ 可用工具
训练计划
get_workouts-- 分页列出训练计划。参数：page（从1开始索引），page_size（最大10）。get_workouts_count-- 获取账户上训练计划的总数。get_workout_events-- 列出自某个时间戳以来的训练计划更新/删除事件。参数：page，page_size（最大10），since（ISO 8601格式）。get_workout-- 按ID获取单个训练计划。返回包括练习和组的完整详细信息。create_workout-- 创建一个训练计划。必需参数：title，start_time，end_time（ISO 8601格式），包含sets的exercises。可选参数：is_private，description。update_workout-- 按ID替换现有的训练计划。与create_workout相同的字段加上id。
训练套路
get_routines-- 分页列出训练套路。参数：page，page_size（最大10）。get_routine-- 按ID获取单个训练套路，包括练习和组模板。create_routine-- 创建一个训练套路（训练计划模板）。必需参数：title，folder_id，包含sets的exercises。可选参数：notes。update_routine-- 按ID替换现有的训练套路。与create_routine相同的字段加上id。
练习模板
get_exercise_templates-- 从Hevy库中列出练习模板。参数：page，page_size（最大100）。get_exercise_template-- 按ID获取一个练习模板，包括肌肉群和设备。create_exercise_template-- 创建一个自定义练习模板。必需参数：title，exercise_type，equipment_category，muscle_group。可选参数：other_muscles。
训练套路文件夹
get_routine_folders-- 分页列出训练套路文件夹。参数：page，page_size（最大10）。get_routine_folder-- 按ID获取一个训练套路文件夹。create_routine_folder-- 创建一个文件夹来组织训练套路。必需参数：title。
练习历史
get_exercise_history-- 获取某个练习模板的训练历史。必需参数：exercise_template_id。可选参数：start_date，end_date（ISO 8601格式）。
📦 从源码构建
cargo build --release
HEVY_API_KEY=your-api-key ./target/release/hevy-mcp-server
服务器默认绑定到 127.0.0.1:3000。可以使用 HEVY_HTTP_ADDR 进行覆盖：
HEVY_API_KEY=your-api-key HEVY_HTTP_ADDR=0.0.0.0:8080 ./target/release/hevy-mcp-server
📄 许可证
本项目采用MIT许可证，详情请参阅 LICENSE。
🔗 参考资料
- https://api.hevyapp.com/docs/