Hevy MCP Server

Hevy MCP サーバー

Hevy CLI

ターミナルを使いたいですか？別パッケージの @chrisdoc/hevy-cli は、Hevy API からワークアウト、ルーティン、エクササイズ、身体測定値を直接取得し、明示的な確認のうえでこれらのリソースを作成または更新できます。削除には対応していません。

npm install -g @chrisdoc/hevy-cli
export HEVY_API_KEY=your-hevy-api-key

hevy workouts list --page-size 10
hevy summary --weeks 4

スクリプトやパイプラインで使うには、任意のコマンドに --json を追加してください。CLI はスタンドアロンの Hevy API クライアントであり、MCP のラッパーではありません。コマンドの完全なリファレンス、ページネーションの動作、終了コードについては、 packages/cli/README.md を参照してください。

hevy-mcp は、Hevy のフィットネスおよびワークアウト記録アプリ向けのオープンソースの Model Context Protocol (MCP) サーバーです。認証済みの Hevy API リクエストを通じて、AI アシスタントが Hevy のワークアウト、ルーティン、エクササイズテンプレート、身体測定値を読み取り、分析、作成、更新できるようにします。

Node の stdio/HTTP アダプターと Cloudflare Worker は、同じ MCP ツールを共有します。トランスポートを選ぶにはデプロイモードを、ワークスペースの所有権、ランタイムスコープ、対応する埋め込み API についてはアーキテクチャを参照してください。

Hevy PRO で利用できる Hevy API キーが必要です。

実際の動作を見る

_{プレビューをクリックすると、18 秒の高画質デモを再生できます。}

デモでは、アシスタントが実際の Hevy データを取得し、ユーザーのワークアウト履歴に基づく根拠を示しながら、複数の要素からなるトレーニングに関する質問に回答します。

これで何ができますか？

• トレーニングの進捗を分析する： 1〜12 週間分のワークアウトと身体測定値を、1 回のツール呼び出しで要約できます。
• 自然な言葉で質問する： 最近のセッション、よくトレーニングしているエクササイズ、一貫性が途切れている期間、ルーティンの詳細、エクササイズの履歴を確認できます。
• トレーニングを計画して記録する： ワークアウト、ルーティン、ルーティンフォルダー、カスタムエクササイズ、身体測定値を作成または更新できます。
• 膨大な応答を避けて検索する： コンパクトで AI に適した結果で、ルーティンやエクササイズのテンプレートを見つけられます。
• お好みの MCP クライアントから接続する： ホスト型 Streamable HTTP エンドポイントを使うか、Codex、Claude Desktop、Cursor、その他のクライアントでローカル実行できます。
• 何もインストールせずに始める： 本番環境の Cloudflare Worker に直接接続できます。Node.js、パッケージのダウンロード、Docker コンテナは不要です。
• 必要なときはローカルで管理する： 同じサーバーを npx、bunx、または公式 Docker イメージで実行できます。

次のように尋ねてみてください。

過去 6 週間のトレーニングを分析してください。週ごとのワークアウト数、最も頻繁にトレーニングしたエクササイズ、明らかな抜けや不規則性を示し、使用したワークアウトの根拠も挙げてください。

プッシュデイのルーティンを見つけて、エクササイズとセットを表示してください。

最近の身体測定値とトレーニングの継続性を比較してください。

保存済みのルーティンから、完了済みのワークアウトを作成してください。Hevy に記録する前に、不足しているセットの結果があれば尋ねてください。

Claude との連携

このリポジトリには、ユーザーの Hevy API キーを埋め込まずに、ホスト型の OAuth 対応 MCP エンドポイントに接続する Claude プラグインが含まれています。

Claude.ai と Claude Desktop

Claude で 設定 → コネクター → カスタムコネクターを追加 を開き、次を入力します。

https://mcp.hevy-mcp.dev/mcp

OAuth フローを完了し、プロンプトが表示されたら Hevy API キーを入力します。同じリモートエンドポイントは、Claude Desktop や、リモート MCP コネクターに対応したその他のクライアントでも使用できます。

Claude Code と Cowork

Claude プラグインは .claude-plugin/plugin.json と .mcp.json で定義されています。この公開リポジトリから、または公開後に Claude Plugin Directory からインストールしてください。ホスト型の Hevy MCP コネクターと Hevy ワークアウトスキルが追加されます。

ホスト型サービスのデータ取り扱いについては、プライバシーポリシーをご覧ください。

クイックスタート

1. Hevy API キーを取得する

Hevy の API 設定で API キーを作成し、安全な場所に保管してください。現在、API の利用には Hevy PRO サブスクリプションが必要です。

2. hevy-mcp をクライアントに接続する

ホスト型 Cloudflare エンドポイントを使うのが、最も手早く始める方法です。リモートで実行されるため、クライアントに Node.js、Bun、Docker、ローカルサーバープロセスは必要ありません。

ホスト型エンドポイントに接続する

本番環境 URL：

https://mcp.hevy-mcp.dev/mcp

このエンドポイントは Streamable HTTP を使用します。リクエストごとに、Hevy API キーをベアラートークンとして送信してください。

Codex

Codex CLI、Codex デスクトップアプリ、IDE 拡張機能は、同じ MCP 設定を共有します。Codex の起動時に使われる環境で Hevy API キーを利用できるようにしてから、ホスト型サーバーを追加します。

export HEVY_API_KEY=your-hevy-api-key
codex mcp add hevy \
  --url https://mcp.hevy-mcp.dev/mcp \
  --bearer-token-env-var HEVY_API_KEY

Codex は、キーそのものではなく環境変数名を MCP 設定に保存します。Codex を再起動するか新しいセッションを開始してから、codex mcp list を実行し、サーバーが設定されていることを確認してください。

その他の Streamable HTTP クライアント

リモート MCP URL と固定ヘッダーを受け付けるクライアントでは、一般的に次の形式を使用します。

{
	"mcpServers": {
		"hevy": {
			"url": "https://mcp.hevy-mcp.dev/mcp",
			"headers": {
				"Authorization": "Bearer your-hevy-api-key"
			}
		}
	}
}

正確な設定キーはクライアントによって異なります。ホスト型サーバーを利用するには、Streamable HTTP と固定の Authorization ヘッダーへの対応が必要です。

重要

ベアラー値はパスワードと同様に扱ってください。Worker はリクエストごとに Hevy で検証し、保存せず、必須の api-key ヘッダーとしてのみ Hevy に転送します。

代わりにローカルで実行する

自分のマシンでサーバーを実行したい場合、またはクライアントがリモート MCP リクエストに固定の認証ヘッダーを設定できない場合は、ローカルの stdio を選択してください。

Codex

codex mcp add hevy \
  --env HEVY_API_KEY=your-hevy-api-key \
  -- npx -y hevy-mcp

Claude Desktop または Cursor

クライアント設定に次の mcpServers エントリを追加します。

{
	"mcpServers": {
		"hevy": {
			"command": "npx",
			"args": ["-y", "hevy-mcp"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

Google Antigravity

Google Antigravity（agy）用に Hevy MCP サーバーを設定する方法は 2 つあります。

オプション A：プラグインの自動インストール（推奨）

組み込みのプラグインシステムを使用します。

プラグインはリポジトリのルートにある mcp_config.json を読み込み、ローカルの stdio サーバーを起動します。この設定には意図的に API キーを含めていません。以下で説明するように、サーバーはホスト環境から HEVY_API_KEY を継承します。これは、以下で説明する手動のユーザー全体設定や、ホストされた HTTP/OAuth を設定するリポジトリの .mcp.json とは別のものです。

1. プラグインをインストールします。

   agy plugin install https://github.com/chrisdoc/hevy-mcp
   

2. CLI の子プロセスが継承できるよう、ホストのシェル環境に HEVY_API_KEY を設定します。

   • 永続的な設定： システムまたはシェルの設定に環境変数 HEVY_API_KEY を保存します。
     • macOS / Linux： シェルのプロファイル設定（例：~/.zshrc または ~/.bashrc）に追加します。

       export HEVY_API_KEY="your-actual-api-key"
       

     • Windows： ユーザーまたはシステムの環境変数に追加します。PowerShell では、次のコマンドを実行できます。

       [Environment]::SetEnvironmentVariable("HEVY_API_KEY", "your-actual-api-key", "User")
       

   • 一時的な設定（セッションのみ）： キーを永続化しない場合は、agy の実行前にアクティブなターミナルセッションでエクスポートします。

     export HEVY_API_KEY="your-actual-api-key"
     

オプション B：手動設定（プラグインなし）

グローバル設定ファイルを使用して静的に設定する場合：

1. グローバル MCP 設定ファイルを開きます。

   • 場所： ~/.gemini/config/mcp_config.json

2. mcpServers キーの下に hevy 設定ブロックを追加します。ファイル全体の内容を置き換えるのではなく、既存のサーバー設定と統合してください。

   {
   	"mcpServers": {
   		"hevy": {
   			"command": "npx",
   			"args": ["-y", "hevy-mcp"],
   			"env": {
   				"HEVY_API_KEY": "your-actual-api-key"
   			}
   		}
   	}
   }
   

一般的なローカル設定ファイルの場所：

• macOS の Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows の Claude Desktop： %APPDATA%\Claude\claude_desktop_config.json
• Cursor： ~/.cursor/mcp.json

ファイルを保存した後、クライアントを再起動するか、再接続してください。

任意の stdio MCP クライアント

子プロセスの環境に HEVY_API_KEY を設定して、次のコマンドを起動するようクライアントを設定します。

npx -y hevy-mcp

npx には Node.js 20 以降が必要です。設定を保存した後、クライアントを再起動するか、再接続してください。

{
	"mcpServers": {
		"hevy": {
			"command": "bunx",
			"args": ["hevy-mcp@latest"],
			"env": {
				"HEVY_API_KEY": "your-hevy-api-key"
			}
		}
	}
}

export HEVY_API_KEY=your-hevy-api-key
docker run -i --rm -e HEVY_API_KEY ghcr.io/chrisdoc/hevy-mcp:latest

{
	"mcpServers": {
		"hevy": {
			"command": "docker",
			"args": [
				"run",
				"-i",
				"--rm",
				"--env-file",
				"/absolute/path/to/hevy-mcp.env",
				"ghcr.io/chrisdoc/hevy-mcp:latest"
			]
		}
	}
}

add-mcp を使って、対応クライアントに npm サーバーを追加することもできます。

npx add-mcp hevy-mcp --env "HEVY_API_KEY=your-hevy-api-key"

3. 最初の質問をする

MCP クライアントを再起動または再接続した後、次のいずれかを試してみてください。

• 「過去 4 週間のトレーニング概要を教えてください。」
• 「Hevy に保存しているルーティンを教えてください。」
• 「直近 3 件のワークアウトを表示してください。」
• 「スクワットを含むエクササイズテンプレートを探してください。」
• 「接続している Hevy アカウントはどれですか？」

クライアントがツールの実行確認に対応している場合、アシスタントは変更を伴うツールを実行する前に承認を求めます。

仕組み

Hosted:  Your AI assistant  →  Streamable HTTP  →  Cloudflare Worker  →  Hevy API
Local:   Your AI assistant  →  MCP over stdio   →  local hevy-mcp     →  Hevy API

ホストされたエンドポイントは、リクエストごとに新しい MCP サーバーと Hevy クライアントを作成します。 直接のベアラ認証では、指定された Hevy キーを使用し、キーそのものを保存せずに、検証の成功を15分間キャッシュします。 OAuth では、キーを暗号化してグラントに保存します。どちらの方法でも、共有 MCP ユーザーセッションは作成されません。 ローカルサーバーも同じツールコントラクトに従いますが、Hevy キーはプロセス環境を通じて受け取ります。

どちらのモードでも、読み取りツールはデータを取得します。変更ツールは、アシスタントが呼び出した場合にのみ、データを作成または置き換えます。

ガイド付きプロンプト

このサーバーが提供する MCP プロンプトは、よくある複数ステップのワークフローを調整します。

ツール

hevy-mcp は23個のツールを登録します。読み取り専用ツールは安全に確認できます。作成ツールと更新ツールにはMCPの変更アノテーションが付与されているため、互換性のあるクライアントから確認を要求できます。

| ワークアウト | get-workout-events | タイムスタンプ以降のワークアウトの更新イベントと削除イベントの一覧を取得します。 | | ワークアウト | create-workout | Hevyに完了済みのワークアウトを作成します。 | | ワークアウト | update-workout | IDを指定してワークアウトのメタデータを部分更新します。is_privateは必須です。省略したその他のフィールドとすべてのエクササイズは変更されません。 | | ワークアウト | replace-workout-exercises | すべてのエクササイズとセットを置き換えます。is_privateは必須で、更新されます。その他のワークアウトのメタデータは変更されません。 | | ルーティン | search-routines | ルーティンのタイトルを検索し、検索用の簡潔なメタデータを返します。 | | ルーティン | get-routines | カスタムおよびデフォルトのワークアウトルーティンの一覧を取得します。 | | ルーティン | get-routine | IDを指定して、1件のルーティンとそのエクササイズ設定を取得します。 | | ルーティン | create-routine | 再利用可能なワークアウトルーティンを作成します。 | | ルーティン | update-routine | 既存のルーティンの内容を置き換えます。 |

| ルーティンフォルダー | get-routine-folder | IDを指定して、1件のルーティンフォルダーのメタデータを取得します。 | | ルーティンフォルダー | create-routine-folder | ルーティンフォルダーを作成します。 |

| エクササイズテンプレート | get-exercise-template | IDを指定して、1件のエクササイズテンプレートのメタデータをすべて取得します。 | | エクササイズテンプレート | search-exercise-templates | タイトルの部分文字列でエクササイズカタログ全体を検索します。 | | エクササイズテンプレート | create-exercise-template | カスタムのエクササイズテンプレートを作成します。 | | エクササイズ履歴 | get-exercise-history | 1件のエクササイズテンプレートについて、過去に実施したセットを取得します。 | | 身体測定 | get-body-measurements | 日付付きの身体測定値の一覧を取得します。 | | 身体測定 | get-body-measurement | 1つの日付に該当する身体測定記録を取得します。 | | 身体測定 | create-body-measurement | 日付付きの身体測定記録を作成します。 | | 身体測定 | update-body-measurement | 既存の日付の身体測定記録を更新します。 | | 診断 | feedback | 問題や予期しない動作について、簡潔でプライバシーに配慮した説明を報告します。 |

create-routineとupdate-routineでは、空でないexercises配列を含むトップレベルのroutineエンベロープが必要です。各エクササイズには少なくとも1つのセットを含める必要があり、すべての階層のフィールド名にはスネークケースを使用します。

{
	"routine": {
		"title": "Full Body A",
		"folder_id": 123,
		"notes": "First four exercises are the minimum viable workout",
		"exercises": [
			{
				"exercise_template_id": "30E293E3",
				"superset_id": null,
				"rest_seconds": 120,
				"notes": "Controlled active ROM",
				"sets": [
					{
						"type": "normal",
						"rep_range": {
							"start": 6,
							"end": 10
						}
					}
				]
			}
		]
	}
}

Hevy APIには現在、ワークアウト、ルーティン、ルーティンフォルダー、エクササイズテンプレート、身体測定値を削除するエンドポイントがありません。そのため、対応する削除ツールもありません。

リソース

ホスト型 Cloudflare エンドポイント

本番 MCP サーバーは、次の場所で稼働しています。

https://mcp.hevy-mcp.dev/mcp

hevy-mcp を使う最も手軽な方法です。ローカルにインストールしたり、実行し続けたりする必要はなく、npm パッケージや Docker イメージと同じ 23 個のツールを提供します。

Cloudflare Worker は、POST /mcp でステートレスな Streamable HTTP を使用します。クライアントは、次の固定の認証ヘッダーで Hevy API キーを送信する必要があります。

{
	"mcpServers": {
		"hevy": {
			"url": "https://mcp.hevy-mcp.dev/mcp",
			"headers": {
				"Authorization": "Bearer your-hevy-api-key"
			}
		}
	}
}

この構成では、Bearer 値は OAuth トークンではなく、Hevy API キーです。Worker は、ハッシュ化されたキーを使って検証の成功を 15 分間キャッシュします。この直接接続ではキーの生データを永続化せず、Hevy が必須としている api-key ヘッダーでのみ上流に転送します。

Claude.ai やその他のリモート MCP クライアント向け OAuth

本番環境の Worker には OAUTH_KV 名前空間バインディングが設定されているため、固定ヘッダーを送信できない Claude.ai のカスタムコネクタなどのクライアント向けに、完全な OAuth 2.1 レイヤーを提供します。セルフホストの Worker で有効にするには、CONTRIBUTING.md の OAUTH_KV セットアップに従ってください。

• /.well-known/ 配下の RFC 8414／RFC 9728 検出メタデータ
• クライアント ID メタデータドキュメント（CIMD）。動的クライアント登録（/register）を代替手段として提供し、PKCE トークン交換（/token）にも対応します
• Hevy API キーを一度貼り付ける /authorize ページ。キーは Hevy で検証され、OAuth グラント内に暗号化して保存されます

末尾が /mcp の Worker URL を Claude.ai のカスタムコネクタとして追加し、ブラウザーで認可フローを完了してください。直接の Authorization: Bearer <hevy-api-key> リクエストも引き続きそのまま機能します。OAuth レイヤーは追加機能です。Hevy キーを取り消すかローテーションすると、そのキーを使った以後の Hevy API アクセスはできなくなりますが、保存済みのグラントが削除されたり、キャッシュされた検証が直ちに消去されたりするわけではありません。

OAuth アクセストークンの有効期間は 7 日間、リフレッシュトークンの有効期間は 30 日間です。これにより、頻繁な毎時の更新による KV 書き込みを減らしつつ、対応クライアントの自動更新を維持できます。

このエンドポイントは、レガシー SSE や GET イベントストリームを公開しません。OAuth レイヤーを有効にしていない場合、OAuth 検出、動的登録、CIMD、またはトークン更新が必要なクライアントは、上記の固定カスタムヘッダーを送信できない限り互換性がありません。

Worker のセルフホスト

クリーンなクローンから pnpm --dir packages/worker exec cf deploy を実行すると、移植可能な TypeScript Cloudflare 構成をデプロイし、workers.dev URL を取得できます。OAuth には独自の OAUTH_KV 名前空間が必要です。カスタムドメイン、ルート、オブザーバビリティの送信先は、いずれもアカウント所有者が任意で設定する項目です。セットアップと、セルフホストとメンテナー専用の名前付き環境の違いについては、CONTRIBUTING.md を参照してください。

セルフホストの Streamable HTTP 用 Cloudflare Worker のデプロイ方法については、CONTRIBUTING.md を参照してください。

高度な設定

HEVY_API_KEY=your-hevy-api-key npx hevy-mcp --transport http --host 127.0.0.1 --port 3000

ローカル MCP エンドポイントは http://127.0.0.1:3000/mcp です。ループバック以外のアドレスにバインドするには、別途 HEVY_MCP_HTTP_BEARER_TOKEN 環境変数が必要です。Docker でデプロイする場合は、ポートを明示的に公開する必要があります。

docker run --rm -p 3000:3000 -e HEVY_API_KEY -e HEVY_MCP_HTTP_BEARER_TOKEN \\
  ghcr.io/chrisdoc/hevy-mcp:latest --transport http --host 0.0.0.0 --port 3000

この Node HTTP モードは、前述のステートレスな Cloudflare Worker HTTP エンドポイントとは異なります。Node サーバーはステートフルなクライアントセッションを管理しますが、Worker はホスト型デプロイ向けに設計されており、Node コードをインポートしません。

キャッシュの動作

search-exercise-templates と hevy://exercise-templates は、サーバー単位のインメモリカタログキャッシュを共有します。

• エントリーの有効期間は 5 分で、キャッシュに保持されるカタログは最大 1 つです。
• 可能な場合、同時に行われるカタログリクエストは、進行中の取得処理を共有します。
• search-exercise-templates では、refresh: true を指定してキャッシュを無効化できます。
• ホスト型 Worker の各リクエストでは新しいカタログキャッシュが作成されるため、キーをまたいだ共有は発生しません。
• ローカル HTTP の各セッションは、それぞれ専用の MCP サーバーとカタログキャッシュを持ちます。キャッシュはセッション間で共有されません。

ローカル Node のテレメトリとプライバシー

公開済みの Node ビルドでは、プロジェクトのテレメトリがデフォルトで有効になっています。ビルド前のソースを実行する場合（開発用スクリプトやプローブスクリプトなど）、HEVY_MCP_TELEMETRY=1 を明示的に設定しない限り、テレメトリは無効です。これはローカル Node の動作に限られます。Cloudflare Worker は Node のテレメトリをインポートしません。どちらのモードでも Node の起動前に HEVY_MCP_TELEMETRY=0 を設定すると、プロジェクトのテレメトリをすべて無効にできます。公開済みビルドでは、値が文字列 0 そのものでない限り、デフォルトで有効になります。スコープ化された Node ライフサイクルの Layer がテレメトリを取得します。パッケージをインポートしても副作用は発生しません。有効にしたソースの実行では、Sentry 環境として development が使用され、公開済みビルドでは production が使用されます。SENTRY_ENVIRONMENT を設定すると、このラベルを上書きできます（例：qa や staging）。マスター設定は SENTRY_DSN と、パッケージまたはランタイムの OTEL_COLLECTOR_TOKEN 認証情報より優先されるため、無効な場合はテレメトリエクスポーターや定期的なメトリクスリーダーが作成されず、テレメトリのネットワークリクエストも送信されません。SENTRY_DSN は Sentry 専用の設定です。テレメトリが有効な場合、空の値を指定すると Sentry へのエクスポートのみが無効になります。

テレメトリが有効な場合、対応が必要なエラーは SENTRY_DSN で設定された Sentry プロジェクトに送信されます。Sentry のパフォーマンストレーシングは無効です。エクスポート前に、例外メッセージとスタックには長さ制限が適用され、機密情報が削除されます。詳細を抑制しながら構造的なトレースとメトリクスを維持するには、HEVY_MCP_TELEMETRY_DIAGNOSTICS=0 を設定します。トレースとメトリクスは引き続き、次のコレクターに送信されます。 https://otel.chrisdoc.dev/v1/traces と https://otel.chrisdoc.dev/v1/metrics。このプロジェクトでは独自の OpenTelemetry Collector を使用しており、下流の送信先はそのインフラストラクチャで設定されます。メトリクスは 30 秒ごとにエクスポートされます。Cloudflare の OTLP エクスポートとドメイントレーシングについては、オブザーバビリティのドキュメントを参照してください。

生の API キーがエクスポートされることはありません。通常のツールのテレメトリには、相関のためにキーから生成した短く決定的な HMAC の仮名が含まれることがあります。feedback は、観測されない別個の経路を使用します。対応が必要なエラーには、障害ごとの診断 ID と OTel トレース ID が付加される場合があります。テレメトリのフィールド制限とプライバシーに関する仕様については、テレメトリデータ辞書を参照してください。

例外メッセージとスタックは診断情報として扱われます。長さを制限し、認証情報、URL、ローカルのホームディレクトリパスを除去します。また、HEVY_MCP_TELEMETRY_DIAGNOSTICS=0 の場合は完全に削除されます。プロンプト、ツールの引数、ツールの結果、リクエスト本文、API キー、生の識別子やクエリ、正確な日付、ワークアウト／ルーティン／フォルダー／テンプレート／身体測定の内容、名前／タイトル／説明／メモ、測定値、任意のクライアントメタデータ、正規化されていないエンドポイントパスは、引き続き禁止されています。

セキュリティと変更操作

• HEVY_API_KEY をソース管理、URL、ログ、スクリーンショットに含めないでください。
• ローカルクライアントは、子プロセスの環境変数を通じてキーを渡します。
• ホスト型クライアントは、Authorization: Bearer ヘッダーでのみ Hevy キーを送信します。有効なキーは検証後にキャッシュされますが、キーの生データは永続化されません。 OAuth の許可では、キーは暗号化して保存されます。どちらの方法でも、Hevy には api-key ヘッダーでのみ送信されます。
• ブラウザーからの MCP リクエストは、同一オリジンであるか、完全一致する許可リストのオリジンである必要があります。デフォルトの許可リストには Claude.ai、ChatGPT、Web 用 VS Code、github.dev が含まれます。セルフホスト型のデプロイでは、MCP_ALLOWED_ORIGINS で上書きできます。OAuth 認証フォームの例外については、デプロイモードを参照してください。
• ローカル開発では、.dev.vars.example を .dev.vars にコピーして、MCP Inspector の Origin 検証を無効にできます。PR プレビューの Worker でも、ブラウザーのオリジンが動的であるため、同じ開発専用設定を使用します。本番環境の Worker では、MCP_DISABLE_ORIGIN_CHECK=true を絶対に設定しないでください。
• 作成操作は、再試行すると重複を生じる場合があります。通常の更新では内容が置き換えられます。ワークアウトのメタデータ更新では、省略されたフィールドやエクササイズが保持されますが、replace-workout-exercises ではすべてのエクササイズとセットが置き換えられます。ツールの入力を確認し、クライアントで確認を行ってください。

トラブルシューティング

• サーバーが表示されない場合： 設定を変更した後、MCP クライアントを再起動するか、再接続してください。
• npx が失敗する場合： Node.js 20 以降がインストールされていることを確認し、ターミナルで npx -y hevy-mcp --version を実行してください。
• Codex からサーバーが見えない場合： codex mcp list を実行し、hevy エントリが存在することを確認してから、新しい Codex セッションを開始してください。
• Hevy API が 401 を返す場合： キーが無効、期限切れ、取り消し済み、または設定ミスの可能性があります。Hevy の API 設定で有効なキーを確認または作成し、クライアントを再起動してください。
• ホスト型の認証に失敗する場合： キーが Hevy PRO アカウントに属しており、Authorization: Bearer <HEVY_API_KEY> として送信されていることを確認してください。
• ローカル認証に失敗する場合： キーが有効であり、MCP の子プロセスから HEVY_API_KEY として利用できることを確認してください。
• 診断情報が必要な場合： HEVY_MCP_DEBUG=1 を設定してください。診断出力は stderr に送られ、stdout 上の MCP メッセージには影響しません。

バグを見つけた場合や機能のリクエストがある場合は、issue を作成してください。

コントリビューション

コントリビューションを歓迎します。開発環境のセットアップ、テストレーン、生成クライアントのワークフロー、Cloudflare Worker のデプロイ、プルリクエストのルールについては、CONTRIBUTING.md に記載されています。

mise を使用して固定バージョンの Node.js と pnpm を設定し、決定論的なユニットテストレーンを実行してください。Hevy API キーは必要ありません：

MISE_AUTO_INSTALL=false mise install
MISE_AUTO_INSTALL=false mise exec -- pnpm install
MISE_AUTO_INSTALL=false mise exec -- pnpm run test:unit

ライセンスと謝辞

• ライセンス： MIT
• 謝辞： Model Context Protocol および Hevy Fitness