garmin-connect-workouts-mcp

Garmin Connect Workouts MCP

自然言語で記述されたワークアウトを、Garmin Connect の構造化されたワークアウトに変換する MCP（Model Context Protocol）サーバーです。セッションの内容を平易な英語で記述すると、呼び出し元のモデルが型付きのステップ形式のワークアウトを作成します。このサーバーはそれを Garmin のワークアウト API 形式にエンコードし、アカウントに直接作成します。

機能

• ペース、心拍数、パワー、ケイデンスの目標値 - ペース範囲、心拍ゾーン 1～5、明示的な bpm 範囲、サイクリングのパワー、ケイデンスをすべて、Garmin の実際の workoutTargetType テーブルに基づいてエンコードします。
• 実際のリピートブロック - 5x1km は、5 つの重複したステップではなく 1 つのリピートグループになり、ウォッチには実際の反復回数カウンターが表示されます。
• スイムワークアウト - ステップごとの泳法（自由形、背泳ぎ、平泳ぎ、バタフライ、ドリル、個人メドレー、または任意の泳法）と用具（フィン、キックボード、パドル、プルブイ、シュノーケル）に対応し、ワークアウト単位でプールの長さをメートルまたはヤードで指定できます。
• ワークアウトのライフサイクル全体に対応 - ワークアウトの作成、一覧表示、取得、更新、削除、Garmin Connect のカレンダーへのスケジュール設定ができます。
• テキスト解析ではなく構造化入力 - サーバーが自由形式のテキストを解析することはありません。すべての時間と目標値は単位が明示されたフィールドで指定されるため、「10 min」のような文字列が誤って解釈されることはありません。

クイックスタート

Claude Code

claude mcp add garmin-workouts npx garmin-connect-workouts-mcp

Claude Desktop

設定ファイルに追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "garmin-workouts": {
      "command": "npx",
      "args": ["-y", "garmin-connect-workouts-mcp"]
    }
  }
}

その後、Claude Desktop を再起動します。

認証

Garmin Connect のウェブクライアントは、サーバーが保持できるパスワードグラントではなく、セッション Cookie と CSRF トークンで認証します。そのため、初めてワークアウトを作成するとき（またはセッションの有効期限が切れたとき）は、次の手順が必要です。

1. サーバーは、軽量な認証リクエストを使って保存済みのセッションを確認します。
2. セッションが存在しないか、拒否された場合は、authenticate_garmin ツールを実行します。ログインできるよう、connect.garmin.com を開いた実際のブラウザーウィンドウが表示されます。
3. ログインが完了すると、セッションが取得され、600 権限（所有者のみ読み取り／書き込み可能）で ~/.config/garmin-connect-workouts-mcp/auth.json に保存されます。

パスワードが保存されることはありません。保存されるのは、ログイン後のセッション Cookie と CSRF トークンのみです。Garmin のセッションには有効期限があるため、セッションをまたいで再認証を求められる場合があります。サーバーは有効期限切れを自動的に検知し、authenticate_garmin を再実行するよう通知します。ログインに使うブラウザーは、~/.config/garmin-connect-workouts-mcp/browser-profile/ にある永続的で分離されたプロファイルを使用するため、Garmin はログイン間でデバイスを記憶できます。個人用のブラウザープロファイルには一切アクセスしません。

ツール

ツール	説明
create_garmin_workout	ステップ、目標値、リピートブロックを含む構造化されたワークアウトを作成します。
list_garmin_workouts	Garmin Connect アカウントのワークアウトを一覧表示します。
get_garmin_workout	1 件のワークアウトの完全な構造を取得します。
update_garmin_workout	ID を維持したまま、既存のワークアウトの内容を置き換えます。
delete_garmin_workout	ワークアウトを削除します。
schedule_garmin_workout	指定した日付の Garmin Connect カレンダーにワークアウトを登録します。
check_garmin_auth	保存済みの Garmin セッションが引き続き有効か確認します。
authenticate_garmin	Garmin Connect の認証を行います（ブラウザーが開きます）。

使用例

• 「ゾーン 2 で 30 分間のイージーランを作成する」
• 「ゾーン 3 で 10 分間のウォームアップを行い、その後、4:00/km で 1 km の閾値インターバルを 5 回、各インターバルの間に 2 分間の休憩を挟み、最後にゾーン 2 で 10 分間のクールダウンを行う」
• 「5 km ペースで 400 m を 8 回、60 秒間の回復を挟んで行い、その後、今週すでに予定されているワークアウトを確認する」
• 「ワークアウト 123456 に 5 分間のクールダウンを追加し、来週の月曜日に予定する」
• 「25 m プールでの水泳を作成する：好きな泳法で 200 m のウォームアップ、キックボードを使った自由形 100 m を 4 回（各 30 秒休憩）、最後に平泳ぎで 100 m のクールダウン」

目標値の仕組み

指定したペースは、範囲の速い側の値として扱われます。Garmin ではペースは単一の値ではなく範囲として保存されるため、4:00/km のみを指定すると、10 秒広げた 4:00-4:10/km の範囲になります。より狭い範囲や異なる範囲を指定するには、fast と slow の両方を明示してください。

開発

pnpm install
pnpm test          # vitest: encoders + golden-file tests against real captured payloads
pnpm run build      # compile TypeScript to dist/
pnpm run dev        # run the server directly with tsx

テストでは、Garmin の Web クライアントから取得したフィクスチャと照合して、ワークアウトのエンコーダー（目標値、時間、繰り返しのネスト構造）を検証します。これにより、ペイロード形式のリグレッションを実際のアカウントに影響する前に検出できます。

免責事項

これは非公式のサードパーティープロジェクトです。Garmin Ltd. またはその関連会社とは提携しておらず、承認や支援も受けていません。また、公式 Web クライアントが行うリクエストをリバースエンジニアリングして、Garmin Connect の Web API と通信します。Garmin がこの API を変更すると、動作しなくなる可能性があります。ご自身の責任でご利用ください。また、アカウントに送信するワークアウトとデータについても、ご自身の責任でご利用ください。

謝辞

Garmin Connect のワークアウトを MCP 経由で操作するというアイデアを最初に考案した Charles Frisbee の garmin-workouts-mcp に感謝します。

ライセンス

MIT