hevy-mcp-server

Hevy（https://hevy.com）のワークアウト追跡API用のMCPサーバー。LLMにワークアウト、ルーチン、エクササイズテンプレート、エクササイズごとの履歴、身体測定値への読み書きアクセスを提供します。

Hevy公開API（v0.0.1）の全15エンドポイントを27のツールでカバーしています。

Requirements

• Node.js 18+

• Hevy Pro サブスクリプション — APIアクセスはPro限定です

• APIキーは https://hevy.com/settings?developer から取得

Related MCP server: hevy-mcp-server

Install

pnpm install
pnpm run build

Configure

MCPクライアント設定で HEVY_API_KEY を設定します。Claude Desktopの場合は、claude_desktop_config.json に設定します：

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

リモート/HTTPモード（ローカル）:

TRANSPORT=http PORT=3000 pnpm start   # POST JSON-RPC to http://127.0.0.1:3000/mcp

ツールを対話的に検査:

HEVY_API_KEY=your-key pnpm run inspect

デプロイ（Claudeモバイル / claude.aiコネクタ用）

Claudeは、デバイスからではなくAnthropicのクラウドからカスタムコネクタに接続するため、モバイルとclaude.aiでは、これを公開HTTPS経由で到達可能にする必要があります。Claude CodeとClaude Desktopはその必要はありません — 代わりにstdioを使用してください。

1. パスシークレットを生成

openssl rand -hex 32

サーバーは、MCP_PATH_SECRET が設定されていない場合、非ループバックインターフェースでの起動を拒否します。公開エンドポイントにHevyキーが保持されると、アカウントへのオープンプロキシになるためです。設定すると、エンドポイントは /mcp/<secret> に移動し、他のすべてのパスは404を返します — 間違ったシークレットも含めて、ホストを調べてもMCPサーバーが存在することを明かしません。

2. デプロイ

同梱の Dockerfile と railway.json は、Railway、Render、Flyでそのまま動作します。イメージは TRANSPORT=http と HOST=0.0.0.0 を設定し、非rootユーザーとして実行されます。プラットフォームのダッシュボードで2つの変数を設定します：

PORT はプラットフォームによって注入されます。/healthz は認証不要の死活プローブです。

3. 確認

curl -s https://your-app.up.railway.app/healthz
# {"status":"ok","server":"hevy-mcp-server","version":"1.0.0"}

4. コネクタを追加

claude.aiでブラウザ上で — コネクタはモバイルアプリからは追加できません：

1. カスタマイズ → コネクタ → カスタムコネクタを追加

2. URL: https://your-app.up.railway.app/mcp/<secret>

3. スマートフォンでチャットを開き、+ → コネクタ の下で有効にします。

そのURLはパスワードのように扱ってください：インターネットとあなたのトレーニングログの間に立つ唯一のものです。漏れた場合は、MCP_PATH_SECRET をローテーションしてコネクタを再追加してください。

ツール

ワークアウト — hevy_list_workouts, hevy_get_workout, hevy_count_workouts, hevy_list_workout_events, hevy_create_workout, hevy_update_workout

セッション — hevy_start_session, hevy_get_active_session, hevy_finish_session, hevy_cancel_session

ルーチン — hevy_list_routines, hevy_get_routine, hevy_create_routine, hevy_update_routine

ルーチンフォルダ — hevy_list_routine_folders, hevy_get_routine_folder, hevy_create_routine_folder

エクササイズテンプレート — hevy_search_exercise_templates, hevy_list_exercise_templates, hevy_get_exercise_template, hevy_create_exercise_template

進捗 — hevy_get_exercise_history, hevy_list_body_measurements, hevy_get_body_measurement, hevy_create_body_measurement, hevy_update_body_measurement

アカウント — hevy_get_user_info

すべての読み取りツールは response_format: "markdown" | "json" を受け取ります。Markdownがデフォルトで、LLMが読むのに最適化されています。JSONは完全な構造化ペイロードです。structuredContent は形式に関係なく常に設定されます。

例

「今週は何をトレーニングした？」 → page_size=5 の hevy_list_workouts。各セッションのタイトル、時間、エクササイズリスト、総ボリュームを返します。

「今日のベンチを記録：60kgで3x8」 → query="bench press" の hevy_search_exercise_templates でIDを取得し、{ weight_kg: 60, reps: 8 } の3セットで hevy_create_workout を実行します。

「今から脚を始める」 → title="Leg Day" の hevy_start_session。開始時刻はサーバー側で記録され、セッションはHevyで進行中として表示されます。終了したら、実行した内容で hevy_finish_session を呼び出すと、実際の時間で閉じられます。

「スクワットは強くなってる？」 → query="squat" の hevy_search_exercise_templates、次に start_date を指定した hevy_get_exercise_history。記録されたすべてのセットを新しい順に返し、推定1RMによるベストセットも返します。

設計メモ

書く前に検索。 Hevyにはサーバーサイドのエクササイズ検索がありませんが、すべての書き込みには exercise_template_id が必要です。hevy_search_exercise_templates はカタログをページングし（最大30ページ×100件）、タイトル、筋肉グループ、器具、カスタムのみでローカルにフィルタリングします。モデルに最初にこのツールを指し示してください — IDは推測できません。

更新は置き換えであり、パッチではありません。 hevy_update_workout、hevy_update_routine、hevy_update_body_measurement はリソース全体を上書きします。省略されたものは削除またはnullになります。3つすべてに destructiveHint: true が設定されており、その説明はモデルに現在の状態を最初に読むように指示します。これらは唯一の破壊的なツールです — Hevy APIには削除エンドポイントがありません。

ライブセッションはタイトルの規約であり、サーバー状態ではありません。 HevyのAPIにはワークアウト開始エンドポイントがなく、アプリ内タイマーを駆動できないため、hevy_start_session は 🔴 In Progress — <title> というタイトルの実際のワークアウトを事前に作成し、hevy_finish_session は実際の終了時刻で書き換えます。そのマーカーが永続する唯一のハンドルです — サーバーはリクエスト間で状態を保持しないため、どのデバイスのどのチャットでも、最近のワークアウトをスキャンして開いているセッションを見つけます。コストは、未完了のセッションがログに表示され続けることであり、Hevyには削除がないため、hevy_cancel_session はラベルを変更するだけで、削除はできません。

すべてはキログラムです。 APIには単位フィールドがありません。入力フィールドは weight_kg と名付けられているため、モデルが送信する内容に曖昧さがなく、マークダウン出力は両方（60 kg (132.3 lb)）を表示するため、米国の読者は暗算で変換する必要がありません。

ページサイズの上限はクライアント側で強制されます。 Hevyは過大なページに対して単なる400を返します。Zodスキーマは各エンドポイントを文書化された制限（ほとんどは10、エクササイズテンプレートは100）に制限するため、モデルは失敗したリクエストではなく正確なメッセージを受け取ります。

エラーは次のアクションに解決されます。 404はそのリソースの有効なIDを生成するツールを指名します。身体測定値の409は更新ツールを指します。403はAPIアクセスにProが必要であることを説明します。

寛容な出力スキーマ。 Hevyのドキュメントは、この0.0.1 APIが予告なく構造を変更する可能性があると警告しています。出力スキーマはオプションフィールドで passthrough() を使用するため、上流のフィールド追加がツールの重大な失敗になりません。

プロジェクト構成

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # API limits, enums, character limit
├── types.ts               # interfaces for every Hevy entity
├── services/
│   └── hevy-client.ts     # fetch wrapper, auth, error → guidance mapping
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # pagination, truncation, format dispatch
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── workouts.ts
    ├── sessions.ts         # in-progress workout tracking
    ├── routines.ts
    ├── exercise-templates.ts
    └── progress.ts

注意事項

• Hevy APIは正式にはバージョン0.0.1であり、そのドキュメント自体が構造が変更されたり放棄されたりする可能性があると警告しています。

• ルーチンのフォルダは作成後に変更できません — 更新エンドポイントは folder_id を受け付けません。

• 検索での器具フィルタリングはエクササイズタイトルに対して一致します。APIがテンプレートに器具をフィールドとして公開していないためです。

• hevy_create_exercise_template は、APIの他の場所で使用される文字列IDとは異なり、数値IDを返します。

テスト

pnpm run build
pnpm test         # 45 checks: MCP handshake, tools, sessions, formatting, errors (mocked API)
pnpm run test:http  # 13 checks: path-secret gating, health check, origin allowlist

両方のスイートはローカルモックに対して実行されるため、APIキーやネットワークアクセスは不要です。