Hevy MCP

@diecoscai/hevy-mcp

Hevy フィットネス API 用の Model Context Protocol サーバーです。MCP 対応クライアント（Claude Desktop、Claude Code、Cursor、VS Code など、stdio 経由で MCP を利用できるあらゆるクライアント）から、ワークアウト、ルーティン、エクササイズ、身体測定値を管理できます。

概要

この MCP サーバーは、公開されている Hevy API（api.hevyapp.com/v1）を、型付けされた 22 個のツールとして公開します。LLM エージェントは、クライアント側に専用のグルーコードを用意することなく、ワークアウトの一覧表示、ルーティンの作成、エクササイズテンプレートの検索、身体測定値の記録、差分同期フィードの利用ができます。

設計目標：

• デフォルトで安全。 HEVY_MCP_ALLOW_WRITES=1 を設定しない限り、書き込み操作は { dry_run: true, would_send: { ... } } のプレビューを返します。Hevy API にはどのリソースにも DELETE がないため、誤った書き込みは取り消せません。ドライランがその歯止めになります。
• 境界で検証。 すべてのツール入力は、ネットワークにデータを送信する前に Zod で検証されます。サイズ超過のタイトル、不明なフィールド、範囲外のページサイズ、無効な列挙値は、モデルが自力で修正できる SEP-1303 形式のエラーとして即座に返されます。
• 追加のセットアップは不要。 認証に必要なのは環境変数 HEVY_API_KEY だけです。セットアップウィザードも設定ファイルも必要ありません。利用するクライアント向けのスニペットを貼り付けるだけです。

スキーマは Hevy 独自の OpenAPI 仕様から生成され、自動的に再同期されるため、サーバーは上流の変更に対応し、古い状態に取り残されません。書き込みはデフォルトでドライランになり、すべての公開エンドポイントを網羅しています。

プロジェクトの状況

メンテナンスモードです。Hevy の公開 API 向けの機能はすべて実装済みです。スキーマは Hevy の OpenAPI 仕様から生成されます。スケジュール済みワークフローが毎週再同期を行い、変更があれば PR を作成します。また、ライブ統合テストで、ドキュメントに記載されていないサーバーの変更を検出します。課題トラッカーからのバグ報告や PR を歓迎します。

前提条件

• Node.js 20 以降（node --version）。
• Hevy Pro サブスクリプション — 公開 API は Pro の機能です。
• https://hevy.com/settings?developer から取得した Hevy API キー。

クイックセットアップ

最も手早くセットアップするには、setup サブコマンドを使います。API キーを検証し、サーバーが自動的に読み込む設定ファイルを書き込みます。

npx @diecoscai/hevy-mcp setup

Hevy Pro API キー（https://hevy.com/settings?developer から取得）を入力するよう求められ、実際の API でキーを検証し、書き込み操作を有効にするかどうかを確認したうえで、すべてを ~/.config/hevy-mcp/config.json（モード 0600）に保存します。その後、環境変数ブロックは不要で、MCP クライアントにサーバーを追加します。

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"]
    }
  }
}

クライアントを再起動すると、22 個の Hevy ツールがツールパネルに表示されます。

環境変数を使いたい場合は？ setup をスキップし、代わりに env ブロックで HEVY_API_KEY（および任意で HEVY_MCP_ALLOW_WRITES=1）を渡してください。設定を参照してください。環境変数は常に設定ファイルより優先されます。

引数なしでの実行に関する注意。 引数なしで npx @diecoscai/hevy-mcp を実行すると、stdio MCP サーバーが起動し、標準入力／標準出力経由で MCP クライアントが接続するまで待機します。自分でターミナルから実行するものではありません。MCP クライアントが起動します。ブロックせずに実行するには、npx @diecoscai/hevy-mcp --help、--version、または setup を使ってください。

書き込みツールはデフォルトでドライランです。 サーバーに何か（ワークアウト、ルーティン、身体測定値など）の作成や更新を初めて依頼すると、実際の変更ではなくプレビューのペイロードが表示されます。setup 中に「yes」と答えるか、env ブロックで HEVY_MCP_ALLOW_WRITES=1 を設定して書き込みを有効にしてください。安全性を参照してください。

ソースから実行

npx を使わず、ローカルのクローンから直接サーバーを実行することもできます。特定のコミットに固定したい場合、ローカルでツールをデバッグしたい場合、または未リリース版を実行したい場合に便利です。コントリビューターは、代わりに以下の開発を参照してください。

git clone https://github.com/diecoscai/hevy-mcp.git
cd hevy-mcp
npm ci
npm run build

npx @diecoscai/hevy-mcp の代わりに、ビルド済みのエントリーポイントを MCP クライアントに指定します。

{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp/dist/index.js"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

env ブロック（HEVY_MCP_ALLOW_WRITES を含む）は、以下の npx の例と同じように機能します。

設定

各 MCP クライアントは、env ブロックで HEVY_API_KEY を指定したうえで、サーバーを stdio サブプロセスとして起動します。

Claude Desktop

設定ファイルのパス：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json（2026 年時点で、Anthropic は Claude Desktop の公式 Linux ビルドを提供していません。このパスは非公式のコミュニティビルドにのみ適用されます。）

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

書き込みツールを有効にするには、env ブロックに "HEVY_MCP_ALLOW_WRITES": "1" を追加します。

Claude Code CLI

claude mcp add hevy --env HEVY_API_KEY=PASTE_YOUR_KEY_HERE -- npx -y @diecoscai/hevy-mcp

書き込みを有効にするには、--env HEVY_MCP_ALLOW_WRITES=1 を追加します。

Cursor

設定ファイルのパス：~/.cursor/mcp.json。Claude Desktop と同じ形式です。

{
  "mcpServers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

VS Code（ネイティブ MCP サポート、1.102+）

ワークスペースのルートに .vscode/mcp.json を作成します（または、VS Code のビルドがユーザーレベルの MCP 設定をサポートしている場合は、同じ形式の設定をそこに追加します）。

{
  "servers": {
    "hevy": {
      "command": "npx",
      "args": ["-y", "@diecoscai/hevy-mcp"],
      "env": {
        "HEVY_API_KEY": "PASTE_YOUR_KEY_HERE"
      }
    }
  }
}

別の形式を想定するサードパーティ製 MCP 拡張機能を使う場合は、そのドキュメントを確認してください。VS Code のネイティブ MCP 統合は 1.102 で追加されました。

トラブルシューティングとクライアント固有の注意事項については、docs/configuration.md を参照してください。MCP クライアントを接続して実行できる一連のフローについては、docs/examples.md を参照してください。

安全性 — ドライランでの書き込み

すべての POST および PUT ツールハンドラーは、呼び出し時に HEVY_MCP_ALLOW_WRITES を確認します。

• 未設定（デフォルト） — ツールは HTTP 呼び出しを行わず、プレビューを返します。

  {
    "dry_run": true,
    "would_send": {
      "method": "POST",
      "path": "/v1/routine_folders",
      "body": { "routine_folder": { "title": "Push days" } }
    },
    "hint": "set HEVY_MCP_ALLOW_WRITES=1 to execute"
  }
  

• 1 に設定 — ツールは実際のリクエストを実行します。

Hevy API には、どのリソースにも DELETE エンドポイントがありません。不適切な書き込みはクライアントからロールバックできず、Hevy アプリで手動修正するまでアカウントに残ります。ドライランが最初の防御策であり、書き込みを明示的にオプトインすることが第二の防御策です。

ツールリファレンス（概要）

サーバーは、リソースごとに分類された 23 個のツールを公開します。入力スキーマと例については、docs/tools.md を参照してください。

ユーザー

ツール	説明
hevy_get_user_info	認証済みユーザー（名前、ID、プロフィール URL）を返します。

ワークアウト

ツール	説明
hevy_list_workouts	ページ分割されたワークアウトを取得します（pageSize は 1～10）。
hevy_get_workout	UUID を指定してワークアウトを 1 件取得します。
hevy_get_workout_count	アカウント上のワークアウトの総数を取得します。
hevy_get_workout_events	差分同期フィードです。指定したタイムスタンプ以降の updated / deleted イベントを取得します。
hevy_create_workout	新しいワークアウトを記録します（書き込み — デフォルトはドライラン）。
hevy_update_workout	既存のワークアウトを全面的に置き換えます（書き込み — デフォルトはドライラン）。

ルーティン

ツール	説明
hevy_list_routines	ページ分割されたルーティンを取得します。
hevy_get_routine	UUID を指定してルーティンを 1 件取得します。
hevy_create_routine	ルーティンを作成します（書き込み — デフォルトはドライラン）。
hevy_update_routine	ルーティンを全面的に置き換えます（書き込み — デフォルトはドライラン）。

ルーティンフォルダー

ツール	説明
hevy_list_routine_folders	ページ分割されたフォルダーを取得します。
hevy_get_routine_folder	正の整数 ID を指定してフォルダーを 1 件取得します。
hevy_create_routine_folder	フォルダーを作成します（書き込み — デフォルトはドライラン）。

エクササイズテンプレート

ツール	説明
hevy_list_exercise_templates	ページ分割されたエクササイズライブラリを取得します。pageSize に最大 100 を指定できる唯一のリストです。
hevy_search_exercise_templates	名前でテンプレートを検索します（大文字と小文字を区別しない部分一致）。人が読む名前（例：「ベンチプレス」）を exercise_template_id に解決します。カタログ全体をページ分割して取得し、結果を 1 時間キャッシュします。
hevy_get_exercise_template	ID を指定してテンプレートを 1 件取得します（組み込みテンプレートは 8 文字の 16 進数、カスタムテンプレートは UUID）。
hevy_create_exercise_template	カスタムエクササイズを作成します（書き込み — デフォルトはドライラン）。
hevy_get_exercise_history	指定したエクササイズテンプレートについて、記録済みのすべてのセットを取得します。

身体測定値

ツール	説明
hevy_list_body_measurements	ページ分割された測定値を取得します。レコードは日付をキーとして管理されます。
hevy_get_body_measurement	単一の YYYY-MM-DD のレコードを取得します。
hevy_create_body_measurement	新しいレコードを作成します（書き込み — デフォルトはドライラン）。日付がすでに存在する場合は 409 を返します。
hevy_update_body_measurement	指定した日付のレコードを置き換えます。送信されなかったフィールドは NULL に設定されます（書き込み — デフォルトはドライラン）。

環境変数

名前	必須	説明
HEVY_API_KEY	必須*	Hevy Pro API キー（UUID v4）です。通常は、MCP クライアント設定の env ブロックを通じて渡します。
HEVY_MCP_ALLOW_WRITES	任意	1 に設定すると、実際の POST / PUT 呼び出しが有効になります。未設定を含むその他の値では、ドライランが有効のままになります。
HEVY_MCP_DISABLE_CACHE	任意	1 に設定すると、インメモリのエクササイズテンプレートキャッシュが無効になります（下記参照）。
HEVY_MCP_CACHE_TTL_SECONDS	任意	キャッシュの TTL（秒）です。デフォルトは 3600 です。キャッシュが無効な場合は無視されます。

* npx @diecoscai/hevy-mcp setup を実行してキー（および書き込み設定）を ~/.config/hevy-mcp/config.json に保存した場合を除き、HEVY_API_KEY が必要です。解決順序は、環境変数が優先され、設定ファイルがフォールバックとして使われます。同じ優先順位が HEVY_MCP_ALLOW_WRITES とファイル内の allowWrites にも適用されます。

エクササイズテンプレートのキャッシュ

hevy_list_exercise_templates と hevy_get_exercise_template は、プロセスごとのインメモリキャッシュ（エントリーごとに TTL を持つ Map。デフォルトは 1 時間）を経由して読み取ります。テンプレートカタログは大規模で、セッション中はほとんど変化しないため、ルーティンの作成中に ID を調べるなど、繰り返し解決する場合でも、HTTP の往復を多数ではなく 1 回に抑えられます。

書き込みが成功すると、hevy_create_exercise_template はキャッシュのリスト部分を無効化します。単一テンプレートのエントリーはそのまま残ります（別のカスタムテンプレートを作成しても、古くなることはありません）。キャッシュがプロセスをまたいで永続化されることはありません。

HEVY_MCP_DISABLE_CACHE=1 でキャッシュ全体を無効にするか、HEVY_MCP_CACHE_TTL_SECONDS でキャッシュの有効期間を短縮または延長します。

ウェブフック — 意図的に公開していません

Hevy の公開 API（api.hevyapp.com/v1/*）にはウェブフックのサブスクリプションが記載されていません。関連するエンドポイントは、別の認証方式（このサーバーが使用する api-key ヘッダーではなく、リフレッシュトークンのベアラー認証）を使う非公開のウェブセッション API（/webhook-subscription、/subscribe_to_webhook）にあります。これらのツールを公開すると、（a）すべてのユーザーに「エンドポイントを利用できません」というエラーを返すハンドラーを提供するか、（b）URL を登録するだけのために、ユーザーにウェブセッションのトークンを渡してもらうことになります。

差分同期が必要な場合は、since タイムスタンプを指定して hevy_get_workout_events を使用してください。これは updated と deleted の両方のワークアウトを対象とし、公開 API が提供する唯一の変更検出手段です。

Hevy が公開 OpenAPI 仕様にウェブフックを掲載した場合は、ほかの書き込み操作と同じドライランの制限を適用したサブスクリプションツールをここに追加します。

ほかの Hevy MCP サーバーの中には、Hevy の非公開ウェブセッション API にアクセスしてウェブフックツールを公開しているものもあります。このサーバーは意図的に、記載されている公開 API のみを使用します。

仕様 ≠ 実際の動作

公開 OpenAPI ドキュメント（独自のバージョン番号 0.0.1）は、いくつかの点で実際のサーバーと異なります。POST /v1/exercise_templates のラッパーが誤っていること、CustomExerciseType の列挙値が誤っていること、PUT /v1/routines/{id} で folder_id が拒否されること、テンプレートの作成成功時にプレーンテキストが返されることなどがあります。このサーバーは、実際のサーバーが受け付ける内容に基づいて実装されています。確認済みの相違点の全一覧は docs/api-quirks.md にあり、scripts/verify-api.sh のプローブスイートで再検証できます（GitHub リポジトリ内にあり、npm の tarball には含まれていません）。

開発

サーバー自体に取り組むコントリビューター向けの説明です。自分の Hevy アカウントを使ってサーバーをローカルで実行したいだけの場合は、代わりにソースから実行を参照してください。

git clone https://github.com/diecoscai/hevy-mcp.git
cd hevy-mcp
npm ci
npm run build
npm test

便利なスクリプト：

スクリプト	用途
npm run dev	ソースを対象に tsc --watch を実行します。
npm run lint	src/ と tests/ 全体に Biome lint を実行します。
npm run format	Biome で自動フォーマットします。
npm run check	Biome で lint とフォーマットをまとめてチェックします。
npm run coverage	V8 カバレッジを有効にして Vitest を実行します。
npm run smoke	エンドツーエンドテスト：npm ci && build && test && lint に加え、stdio プローブと言語ゲートを実行します。
npm run inspect	ビルド済みサーバーに対して MCP Inspector を起動します。

ツールの追加手順：

1. src/validate.ts に Zod スキーマを追加します（すべてのオブジェクトに .strict() を指定してください）。
2. src/index.ts の TOOLS 配列にツール仕様（名前、説明、JSON Schema の inputSchema）を追加します。
3. ディスパッチ用の switch に case を追加します。ネットワークにアクセスする前に必ず validateInput(name, rawArgs) を呼び出し、書き込み処理は guardWrite で囲んでください。
4. tests/ 以下のテストを拡張します（最低限、スキーマと否定的なプローブを追加してください）。
5. この README の表を更新します。

詳しくは CONTRIBUTING.md を参照してください。

セキュリティ

• API キーは MCP クライアントの設定ファイルに保存されます（そこに貼り付けるほかのキーと同じ脅威モデルです）。サーバーが独自の設定ファイルを読み書きすることはありません。
• 書き込みはデフォルトでドライランです。キーが漏えいした場合でも、Hevy アプリでキーを再発行し、新しいキーをクライアントの設定に貼り付けるのにかかる時間は 1 分もありません。
• サーバーが呼び出すのは、記載されている /v1/* エンドポイントのみです。非公開 API への通信、テレメトリー、サードパーティへのリクエスト転送はありません。

脅威モデルの全容については docs/security.md を参照してください。

コントリビューション

コントリビューションを歓迎します。PR を作成する前に CONTRIBUTING.md をお読みください。

ライセンス

MIT。

リンク

• Hevy 公開 API ドキュメント — https://api.hevyapp.com/docs
• MCP レジストリーのエントリー — https://registry.modelcontextprotocol.io/v0/servers?search=io.github.diecoscai/hevy-mcp（公開後に掲載されます）
• イシュートラッカー — https://github.com/diecoscai/hevy-mcp/issues
• MCP 仕様 — https://modelcontextprotocol.io