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トランスポート

サーバーは、設定されたパス（デフォルトは /）で2つのエンドポイントを公開します。

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), exercises と sets。オプション: is_private, description。
• update_workout -- IDで既存のワークアウトを置き換えます。create_workout と同じフィールドに加えて id が必要です。

ルーチン

• get_routines -- ページネーション付きでルーチンをリストします。パラメータ: page, page_size (最大10)。
• get_routine -- IDで単一のルーチンを取得します。エクササイズとセットテンプレートを含みます。
• create_routine -- ルーチン（ワークアウトテンプレート）を作成します。必須: title, folder_id, exercises と sets。オプション: 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/