Hevy Coach

hevy-coach-mcp

Hevy（ワークアウト記録アプリ）用のMCP サーバーです。Hevyからワークアウト、ルーティン、エクササイズテンプレートをリアルタイムで取得します。ローカルキャッシュやデータベースは使わず、分析処理（e1RM、PR、ボリューム、一貫性、期間比較）を行うため、MCPクライアントは推測ではなく実際の数値に基づいて判断できます。依頼された内容（ルーティン、フォルダー、体重）の書き戻しにも対応しますが、ワークアウト履歴には一切触れません。

Hevy PRO とHevy APIキーが必要です（Hevyアプリ → Settings → API）。

インストール

claude mcp add hevy -e HEVY_API_KEY=your_key_here -- npx -y hevy-coach-mcp

または、クライアントのMCP設定に手動で追加します。

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "hevy-coach-mcp"],
      "env": { "HEVY_API_KEY": "your_key_here" }
    }
  }
}

Claude Desktop（claude_desktop_config.json）、Claude Code（.mcp.jsonまたは上記のコマンド）、Cursor（.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）で利用できます。どの環境でも同じ形式です。

APIキーはローカルに保持されます。HEVY_API_KEY環境変数から読み込まれ、Hevy独自のAPIへの呼び出し以外でマシンの外部に送信されることはありません。

ローカルプロセスを起動できないクライアント（Claude.ai、ChatGPT）向けに、OAuthを使ったStreamable HTTP経由のホストモードもあります。https://hevy-mcp-alpha.vercel.app/mcpを指定すると、クライアント側でOAuthフローが実行されます。docs/CONNECTOR.mdでは、クライアントごとの両方のセットアップ方法に加え、セルフホスト、質問例、プライバシーに関する詳細を説明しています。

初回利用

health-checkをいつでも実行して、接続を確認できます。それ以外のすべてのツールはHevyからリアルタイムでデータを取得するため、事前の同期やウォームアップは不要です。

ツール

15個の読み取りツールがあり、すべてreadOnlyHintとしてマークされています。

• health-check — 接続状態
• get-workouts、get-workout — ワークアウトの一覧表示／詳細確認
• list-routines、get-routine — ルーティンの一覧表示／詳細確認
• list-routine-folders — ルーティンが整理されているフォルダーとそのID
• search-exercises、get-exercise-history — 名前からエクササイズを特定し、記録された履歴を確認
• get-progress、get-records — エクササイズごとの推定1RMの推移とPR（1／3／5／8RM）。get-progressでは、各セッション時の体重を基準にした報告も可能です
• get-volume-report — 筋肉群ごとの週間の有効セット数と総重量
• get-consistency — トレーニング頻度、連続記録、最長の間隔
• compare-periods — 2つの期間におけるボリューム／ワークアウト数の差
• get-body-measurements — 記録された体重と測定値を新しい順に表示
• get-bodyweight-trend — 指定期間の体重変化：合計、割合、週あたりの変化率

4個の書き込みツールがあります。書き込みとして宣言されているため、クライアントは実行前に確認します。

• create-routine — エクササイズ名を使って新しいルーティンを作成します。番号ではなく名前で指定したフォルダーへの追加も可能です
• update-routine — 既存のルーティンを編集します。エクササイズのリストを渡すと、既存のリストを完全に置き換えます（destructiveHint）
• create-routine-folder — フォルダーを追加します。同じタイトルのフォルダーがすでにある場合は、重複して作成されません
• log-body-measurement — 指定した日付の体重または測定値を記録します。同じ日付に再記録しても、その日に保存されたほかのデータは保持されます

リソース

hevy://profile、hevy://routines、hevy://exercises、hevy://stats/summary、hevy://workouts/recent — クライアントがツールを呼び出さずに参照できる、負荷の小さいリアルタイムスナップショットです。

プロンプト

weekly-review、program-audit、deload-check、prepare-session — よくあるトレーニングの質問に対して、適切なツールを呼び出すようクライアントをガイドします。

数値を判断に変える、その上位レイヤーにあたる常設のシステムプロンプトについては、docs/COACH-PROMPT.mdを参照してください。

プライバシー

アカウントに関する情報は一切保存されません。各ツール呼び出しでは、お客様ご自身のキーを使ってHevyのAPIから最新の情報を取得し、アカウントに関する情報がほかの場所に送信されることもありません。

Hevyへの書き込みを行うツールは、create-routine、update-routine、create-routine-folder、log-body-measurementの4つです。これらはすべて書き込みとして宣言されているため、実行前にクライアントが確認を求めます。ワークアウト履歴への書き込みは一切ありません。この方針は変わりません。ここで扱うすべての数値は記録済みのワークアウトに基づいて算出されるため、変更できるのはアプリ上でお客様ご自身が操作した場合のみです。HevyのAPIには削除エンドポイントがないため、このサーバーが作成したものをここから削除することもできません。また、HevyのAPIキーにはスコープがなく、このサーバーがどのように利用するかにかかわらず、アカウントへの完全なアクセス権が付与される点にご注意ください。

コントリビューション

リポジトリをクローンし、yarn installを実行して、.env.exampleを.env.localにコピーしてください。変更を検証するには、 CIで実行されるのと同じ次の3つのコマンドを実行してください。 yarn typecheck && yarn test && yarn build

AGENTS.mdには、アーキテクチャ、規約、変更前に把握しておくべき判断事項をすべて記載しています。AIコーディングエージェント向けに書かれていますが、人が概要を把握する際にも最も手早く役立ちます。

ライセンス

MIT