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/