Garmin Connect

garmin-connect-api

Claude などの MCP クライアント、Python、またはローカル HTTP API を介して、Garmin Connect のデータを読み書きします。セットごとの詳細を含むアクティビティ、日々の健康データ、予定ワークアウト、完了した筋力トレーニング、全身の体組成を含む体重記録を扱えます。

非公式です。 Garmin とは提携しておらず、Garmin の承認も受けていません。個人向けの公開 API を Garmin が提供していないため、python-garminconnect を介して Garmin Connect ウェブサイトと同じ非公開エンドポイントを使用しています。これらのエンドポイントは予告なく変更される可能性があり、その使用は Garmin の利用規約で認められていません。ご自身のアカウントとご自身のデータで使用することを目的としています。

ステータス

v0.3。セットごとの筋力トレーニングの詳細、ラップ、プールでの水泳の距離、日々の健康データ、最大 2 年間のトレンド、名前付きの自己ベストを含むアクティビティを読み取れます。筋力トレーニング、ランニング、ライド、水泳のワークアウト、完了した筋力トレーニング、セットの修正、体組成を含む体重記録を書き込めます。38 個のツールはすべて、実際のアカウントで動作確認済みです。不具合の報告や機能リクエストはGitHub Issuesにお寄せください。

クイックスタート

uv と Python 3.12 以降が必要です。

1. 一度だけログインします。ターミナルで次のように実行します。

uvx --from garmin-connect-api garmin login

パスワードを入力するのはここだけです。Garmin のメールアドレス、パスワード、多要素認証コードを求められた後、トークンがユーザーのみが読み取り可能な ~/.garmin-api/default に保存されます。それ以外の場所でパスワードを求められることはありません。トークンがない場合、すべてのツールがこのコマンドの実行を促します。

2. MCP クライアントにサーバーを追加します。

Claude Code：

claude mcp add --scope user --transport stdio garmin -- uvx garmin-connect-api@latest

Claude Desktop の場合は、claude_desktop_config.json に設定します（macOS では ~/Library/Application Support/Claude/、Windows では %APPDATA%\Claude\ にあります）。

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-connect-api@latest"]
    }
  }
}

@latest を指定すると、サーバーの起動時に uvx が新しいリリースを確認します。指定しない場合、uvx は最初にダウンロードしたバージョンを使い続けます。

3. 質問します。「今週の睡眠はどうでしたか？」「昨日の水泳でペースを維持できましたか？」「夏以降、安静時心拍数はどう変化しましたか？」「直近の筋力トレーニングのセットを表示して、3〜5 セットをダンベルローに変更して」「木曜日に水泳を予定して：イージー 200、次に 25 ヤードプールで休憩 20 秒の 100 自由形を 8 本」。

できること

38 個のツールにはそれぞれ注釈が付いており、クライアントは読み取り専用のツール（24 個）、何かを追加するツール（8 個）、削除または上書きするツール（6 個）を把握して、実行前に確認できます。ワークアウトのステップごとのペース目標に至るまで、すべての引数に説明が付いています。

読み取り	書き込み
種類と日付で絞り込んだアクティビティ	筋力トレーニングのワークアウトを作成してスケジュールし、ウォッチに送信
セットごとの筋力トレーニングの詳細：エクササイズ、回数、重量	目標を設定したランニング、ライド、プールスイムのワークアウトを作成
ランニングとライドのラップ、プールスイムの100 mあたりのペース	完了した筋力トレーニングのセッションを、すべてのセットとともに記録
1 日分のデータを一度に取得：歩数、心拍数、ストレス、ボディバッテリー、睡眠、HRV、レディネス	セッションのセットを修正：エクササイズ、回数、重量
最大 2 年分の推移：12 の指標を日別、週別、月別で表示	体重測定、または詳細な体組成の測定値を記録
名前と単位付きの自己記録	アクティビティの名前または説明を変更
体組成を含むすべての体重測定値	アクティビティ、ワークアウト、体重測定値を削除
予定されているワークアウトとカレンダー
Garmin の 1,527 種類のエクササイズカタログをオフラインで利用

4 つのツールは、エンドポイントをそのまま反映するのではなく、モデル向けに作られています。garmin_status は Garmin に接続せずにログイン状態を確認し、find_exercise は筋トレ種目に対応する Garmin の名称を検索します。また、recent_strength_sessions と week_summary はよくある質問に 1 回の呼び出しで回答します。

完了したワークアウトの記録は、Garmin 独自の開発者プログラムがこれまで一度も提供していない書き込み機能です。セッションをセットメッセージ付きの FIT アクティビティファイルに変換してアップロードするため、Garmin Connect にはエクササイズごとに「筋力トレーニング」アクティビティとして表示されます。

スマートスケールで測定した体組成（体脂肪、水分、骨格筋、骨、BMI、基礎代謝量、内臓脂肪）は、Garmin 独自の Index スケールと同じ方法で、FIT 体重計ファイルとして記録されます。通常の体重測定では、体重のみが記録されます。

出力例

回答は簡潔で、人が読みやすい形に要約されます。以下は、Garmin が返すデータ形式を使った架空のデータです。

「昨日のスイムでペースを維持できた？」という質問では、get_activity_laps を呼び出します。

{
  "sport": "lap_swimming",
  "pool_length": 25.0,
  "pool_unit": "m",
  "summary": {
    "lengths": 80,
    "distance": 2000.0,
    "average_pace": "1:52/100m",
    "first_half_pace": "1:50/100m",
    "second_half_pace": "1:54/100m",
    "by_stroke": {"FREESTYLE": 1800.0, "BACKSTROKE": 200.0},
    "fastest_segment": {"lengths": "5-8", "pace": "1:44/100m"},
    "slowest_segment": {"lengths": "77-80", "pace": "2:01/100m"}
  }
}

「夏から安静時心拍数はどう変化した？」という質問では、長期間のデータを週ごとに集計する get_trend を呼び出します。

{
  "metric": "resting_hr",
  "unit": "bpm",
  "aggregation": "week",
  "summary": {
    "days_with_data": 88,
    "average": 54.2,
    "min": 49.0,
    "max": 61.0,
    "first_period_average": 57.3,
    "last_period_average": 51.6,
    "change": -5.7
  }
}

書き込みを行う前に

• 記録したアクティビティは自動的に共有されることがあります。 Garmin アカウントが Strava などのアプリに接続されている場合、アップロードしたセッションがそちらにも投稿されることがあります。また、Garmin から削除しても、連携先からは削除されません。
• レート制限には十分ご注意ください。 Garmin のログインには Cloudflare とアカウントごとのレート制限が設けられており、ログインに何度も失敗すると、アカウントが 1 日以上ロックされることがあります。このツールはログインを再試行せず、レート制限が発生すると、再試行するのではなく、すべての呼び出し経路を停止します。発生した場合は、しばらくお待ちください。
• エクササイズには Garmin 独自の名称が必要です。たとえば BENCH_PRESS / BARBELL_BENCH_PRESS のような名称を使います。生のワークアウト DTO を除くすべての書き込みでは、まずカタログと照合し、近い候補を提示します。そのため、タイプミスがあっても Garmin の素っ気ない 400 エラーではなく、わかりやすいメッセージが返されます。検索では、一般的なジムでの呼び名も使えます。「rdl」「ohp」「pull ups」「bench presses」などです。
• 記録済みのセッションを修正するには、セットを編集してください。 セットを変更して再度記録すると、別のアクティビティが作成されます。同じセッションをもう一度記録すると、重複として報告されます。
• セッションと体組成の測定値にはタイムゾーンオフセットが必要です。オフセットがないと、午前 7 時の測定値が数時間ずれて記録される可能性があります。オフセットが指定されていない場合、記録は拒否されます。

コマンドライン

garmin doctor                          # setup check, no network
garmin activities --type strength_training --limit 5
garmin sets <activity-id>              # per-set detail
garmin day 2026-10-18                  # one day of health data
garmin exercises "lat pulldown"        # search the catalogue, offline
garmin workout create workout.json     # plan a strength workout
garmin log-session session.json        # log a completed one
garmin encode-session session.json     # build its FIT file without uploading
garmin decode-fit activity.zip         # read sets out of a Garmin export
garmin serve                           # the HTTP API on 127.0.0.1:8765

uvx --from garmin-connect-api garmin ... で実行するか、uv tool install garmin-connect-api でインストールしてください。サンプル仕様： session.json、 workout.json。

ログイン操作をこちらに任せたくない場合は、変換済みのセッションファイルを Garmin Connect のウェブサイトから手動でインポートすることもできます。

Python ライブラリ

from datetime import datetime, timedelta, timezone
from garmin_api.services import activities, health, uploads
from garmin_api.models.workouts import (
    StrengthSessionSpec, StrengthSessionExercise, StrengthSessionSet,
)

for activity in activities.list_activities(limit=5, activity_type="strength_training"):
    sets = activities.get_sets(activity.activity_id)
    print(activity.name, sets.total_volume_kg, "kg")

print(health.day("2026-10-18").steps)

uploads.log_strength_session(StrengthSessionSpec(
    name="Push A",
    start_time=datetime(2026, 10, 18, 7, 0, tzinfo=timezone(timedelta(hours=-4))),
    exercises=[StrengthSessionExercise(
        category="BENCH_PRESS",
        exercise_name="BARBELL_BENCH_PRESS",
        sets=[StrengthSessionSet(reps=10, weight_kg=60.0, rest_s=120)],
    )],
))

レスポンスは Pydantic モデルで、Garmin 固有の不整合を解消しています。単位はグラムではなくキログラム、時刻はタイムゾーン付き、フィールド名はすべてスネークケースです。マッピングされていないデータは、引き続き raw から Garmin 本来のペイロードを確認できます。

HTTP API

garmin serve は 127.0.0.1:8765 で同じ API を実行し、/docs でインタラクティブなドキュメントを利用できます。MCP ツールはこれらのルートから生成されるため、両者にずれは生じません。アカウントに書き込みを行う可能性があるため、このサービスはブラウザーで開いたウェブページからの書き込みと、localhost 以外のホスト名を指定するリクエストを拒否し、DNS リバインディングを防ぎます。localhost の範囲外にバインドするには GARMIN_API_KEY が必要で、クライアントが使用するホスト名を GARMIN_API_HOSTS に登録する必要があります。garmin mcp --http は同じ保護機能のもとで、HTTP 経由で MCP ツールを提供します。

設定

変数	用途
GARMINTOKENS	トークンの保存場所です。デフォルトは ~/.garmin-api/default です。
GARMIN_API_KEY	HTTP サービスを localhost の範囲外にバインドする場合に必要です。
GARMIN_API_HOSTS	HTTP サーバーと MCP サーバーが応答する追加のホスト名を、カンマ区切りで指定します。localhost 以外のホスト名を使う場合に必要です。

Docker

Dockerfile はチェックアウトしたリポジトリから MCP サーバーをビルドします。トークンはコンテナ内の /tokens に保存されます。既存のディレクトリをそこにマウントし、自分のユーザーとして実行すると、更新されたトークンも自分のものとして保持できます。コンテナ内でログインすることもできます。

mkdir -p ~/.garmin-api/default
docker build -t garmin-connect-api .
docker run -it --rm --user "$(id -u):$(id -g)" -v ~/.garmin-api/default:/tokens garmin-connect-api garmin login
docker run -i --rm --user "$(id -u):$(id -g)" -v ~/.garmin-api/default:/tokens garmin-connect-api

開発

git clone https://github.com/happyc0der/garmin-connect-api
cd garmin-connect-api
uv sync
uv run pytest

ネットワークもアカウントも不要なオフラインテストを480件用意しており、Linux、macOS、Windows で実行できます。実際の Garmin レスポンス形式に対するモデル、FIT コーデックの往復変換、FIT プロファイルに対するカタログ収録の全1,527件のエクササイズ、HTTP ルート、そして厳格なクライアントが適用する各 MCP ツールの出力とそのツールが公開するスキーマとの整合性をテストします。

実アカウントに対するテストはオプトイン方式です。データを作成するテストには、さらにもう一段階のオプトインが必要です。

GARMIN_LIVE=1 uv run pytest tests/live                      # read only
GARMIN_LIVE=1 GARMIN_LIVE_WRITE=1 uv run pytest tests/live  # creates, then deletes

非公式な方法を採用する理由

Garmin の公式 Connect Developer Program は企業向けで、完了済みアクティビティをアップロードするエンドポイントがなく、2026年には新規申請の受付を終了しました。このプログラムを利用するアグリゲーターは月額数百ドルかかり、読み取り専用か、プランのみを扱います。そのため、このプロジェクトでは Garmin の公式ウェブサイトが利用するエンドポイントを、控えめに使用しています。ポーリングは行わず、レート制限を受けても再試行しません。

引用

研究でこれを使用する場合は、CITATION.cff のメタデータを使って引用してください。GitHub の「このリポジトリを引用」ボタンで書式を整えられます。

ライセンス

MIT ライセンスです。Garmin および Garmin Connect は Garmin Ltd. の商標です。ここでは、このソフトウェアが対応する対象を示す目的でのみ使用しています。