chrisdoc/hevy-mcp

Manage your Hevy workouts, routines, folders, and exercise templates. Create and update sessions faster, organize plans, and search exercises to build workouts quickly. Stay synced with changes so your training log is always up to date.

Hevy MCP - AIフレンドリーなHevyフィットネスアプリへのブリッジ

概要 - hevy-mcpは、**Model Context Protocol（MCP）**を実装した小さなオープンソースサーバーです。HevyのワークアウトトラッキングAPI（読み取り専用および書き込み可能なエンドポイント）を、Claude、Codex、Cursor、その他のMCP互換クライアントが呼び出せる一連のMCP ツールとして公開します。

重要性 - 個人のワークアウトデータを標準的なツールインターフェースに変換することで、このサーバーは大規模言語モデルアシスタントがトレーニング履歴を推論し、自然言語の質問に答え、ワークアウト、ルーティン、カスタムエクササイズ、身体測定記録の作成や更新まで行えるようにします。これらはすべてユーザーの明示的な同意のもとで行われます。

コア機能（23ツール）

カテゴリ	ツール例	できること
トレーニング分析	`get-training-summary`、`analyze-workout-progress`（ガイド付きプロンプト）	数週間分のワークアウトと身体測定の要約、ギャップの特定、頻度の高いエクササイズの表示。
ワークアウト	`get-workouts`、`get-workout`、`create-workout`、`update-workout`、`replace-workout-exercises`、`get-workout-events`	過去のセッションの一覧表示、個別のワークアウト詳細の取得、新しいワークアウトの記録、メタデータやエクササイズセットの編集。
ルーティンとフォルダ	`search-routines`、`get-routines`、`get-routine`、`create-routine`、`update-routine`、`create-routine-folder`、`get-routine-folder`	保存済みルーティンの検索、ルーティンのレイアウトの読み取り、再利用可能な新しいルーティンの作成、フォルダでの整理。
エクササイズカタログ	`search-exercise-templates`、`get-exercise-template`、`create-exercise-template`、`get-exercise-history`	Hevyの全エクササイズライブラリの閲覧、カスタムテンプレートの追加、指定されたエクササイズの過去の実行セットの取得。
身体測定	`get-body-measurements`、`get-body-measurement`、`create-body-measurement`、`update-body-measurement`	体重、体脂肪率などの追跡、エントリの追加または修正。
診断	`feedback`	問題発生時にプライバシーに配慮した短いレポートを送信。

すべての変更ツールはMCP確認でフラグ付けされているため、互換性のあるクライアントはデータ変更操作の前に確認を求めます。

仕組み

AIアシスタント → MCP（ストリーミングHTTPまたはstdio）→ hevy-mcpサーバー → Hevy API

ホストモード – Cloudflare Workerがhttps://mcp.hevy-mcp.dev/mcpでサーバーを実行します。クライアントは固定のAuthorization: Bearer <Hevy-API-key>ヘッダーを送信します。ワーカーはキーを検証し、15分間キャッシュしてHevyに転送します。
ローカルモード – npmパッケージ（またはDockerイメージ）を自分のマシンで実行します。サーバーはHEVY_API_KEY環境変数からAPIキーを読み取り、stdioでクライアントと通信します。
OAuthレイヤー – ホストされたワーカーはオプションのOAuth 2.1フロー（Claude.aiカスタムコネクタで使用）も提供し、キーを暗号化してグラントに保存するため、静的ヘッダーを設定できないクライアントも認証できます。

はじめに（最短パス）

Hevy APIキーを取得 – Hevy PROサブスクリプションが必要です（設定 → 開発者 → APIキー）。
接続 – 公開エンドポイントhttps://mcp.hevy-mcp.dev/mcpを使用します。
- Codexの場合：環境にHEVY_API_KEYを設定し、codex mcp add hevy --url https://mcp.hevy-mcp.dev/mcp --bearer-token-env-var HEVY_API_KEYでサーバーを追加します。
- 他のクライアントの場合：同じURLと固定のAuthorization: Bearer <key>ヘッダーを指定します。
質問する – 例：「過去4週間のトレーニングサマリーを教えてください。」アシスタントがget-training-summaryを呼び出し、簡潔なレポートを返します。

完全に制御したい場合は、サーバーをローカルで実行できます：

npm install -g hevy-mcp   # npx/bunx/dockerも可
set HEVY_API_KEY=your-key
export HEVY_API_KEY=your-key
npx -y hevy-mcp            # stdio MCPサーバーを起動

クライアントをそのコマンドを起動するように設定します（READMEを参照：Claude Desktop、Cursor、Google Antigravityなど）。

エコシステムとツール

@chrisdoc/hevy-cli – Hevy APIに直接話しかける別のコマンドラインクライアント（MCPなし）。スクリプトや簡単なデータダンプに便利です。
Claudeプラグイン – .claude-plugin/plugin.jsonと.mcp.jsonにより、Claude.aiがOAuth経由でホストされたエンドポイントに接続し、Hevyワークアウトスキルを公開できます。
Dockerイメージ – ghcr.io/chrisdoc/hevy-mcp:latest（linux/amd64およびlinux/arm64をサポート）。
MCPトップリストバッジ – 公開MCP実装の中でのサーバーのランキングを示します。

誰が使うのか

フィットネスに特化したAIアシスタント – 個人用LLMコーチに進捗を分析させ、ルーティンの微調整を提案させ、完了したばかりのワークアウトを記録させることができます。
カスタムエージェントを開発する開発者 – 手動でHevy API呼び出しを作成する代わりに、既製の23ツールを使用します。
パワーユーザー – hevy-mcpサーバーを他のMCPサービス（例：栄養トラッカー）と組み合わせて、統一された健康アシスタントを構築します。

ライセンスと貢献

MITライセンスです。
貢献を歓迎します。Cloudflare Workerのセルフホスティング、新しいツールの追加、ドキュメントの改善についてはCONTRIBUTING.mdを参照してください。

結論： hevy-mcpは個人のHevyワークアウトデータをクリーンでAI対応のインターフェースに変換し、任意のMCP互換アシスタントから自然言語クエリと安全で確認済みの変更操作を可能にします。