Hevy MCP

🚀 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_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/