Garmin Local MCP

garmin-local-mcp

分析に適した MCP サーバーを備えた、ローカルファーストの Garmin データウェアハウスです。 一度同期すれば、API が停止していても、いつまでも分析できます。

Garmin アカウントなしで試す

Garmin をお持ちでない場合や、認証情報を渡す前にツールの戻り値を確認したい場合は、合成データでストアを初期化できます。

pip install garmin-local-mcp
garmin-local-mcp --data-dir ~/.garmin-mcp-demo demo
garmin-local-mcp --data-dir ~/.garmin-mcp-demo serve

これにより、すべてのテーブルにわたって 180 日分のデータが生成され、MCP 経由で提供されます。ログインも、ネットワークも、アカウントも不要です。

データは記録されたものではなく生成されたものですが、ランダムではありません。潜在的な回復係数により HRV が上昇すると同時に安静時心拍数が低下し、トレーニング負荷によって翌日の安静時心拍数が上昇します。期間の中ほどには 6 日間の体調不良期間があり、睡眠データが意図的に欠落している夜もいくつかあります。睡眠のタイミングには、埋め込まれたクロノタイプ（MCTQ MSFsc 03:45）が反映されています。目覚ましに合わせた平日の朝と、より遅く、長い自由日の夜があり、睡眠スコアはその自然な起床時刻からのずれに応じて低下します。そのため、分析ツールが有意なパターンを見つけられます。180 日間全体では（トレーニング日は曜日によって決まるため、正確な値は終了日によって多少変わります）：

質問	戻り値
correlate(hrv, resting_hr)	−0.4 ～ −0.6。実際の逆相関です
correlate(training_load, resting_hr, scan_lags=True)	ラグ 0 ではほぼ 0、ラグ 1 では +0.4 ～ +0.65（トレーニング日は 90 ～ 100 日で、スキャンした 15 個のラグを補正した後も有意）：影響は翌日に現れます
anomalies()	体調不良期間を、安静時心拍数、HRV、皮膚温、睡眠スコア、ストレスのすべてで一度に検出します
gaps()	欠落している睡眠データの夜
circadian()	埋め込まれた 03:45 から 10 分以内の MSFsc、07:45 前後の概日上の起床時刻、そして supportive の証拠（2 つのホールドアウト分割で得られる最大値）

分析ツールはデフォルトで直近 30 日間を対象とするため、体調不良期間は含まれません。全期間について質問してください（demo に表示されます）。短い期間ではラグスキャンに十分なデータがなく、15 個すべてのラグを考慮した後に最も強いラグが有意でない場合、correlate はその旨を note に示します。

このようなストアでは sync_status が demo_store: true を返すため、アシスタントが生成された数値を実測値として提示することはありません。ジェネレーターは決定論的です。--seed を指定するとストアを完全に再現でき、--days を指定すると期間を変更できます。demo は、自身が生成したものではないデータベースへの上書きを拒否します。

なぜ新たな Garmin MCP なのか？

ほとんどの Garmin MCP サーバーは、Garmin の非公式 API を呼び出す薄いラッパーにすぎません。 AI アシスタントが質問するたびに、1 回以上の API 呼び出しが発生し、大きな生の JSON データ（睡眠の生データのレスポンスは 1 件で約 230 KB）を返すため、「睡眠とトレーニング負荷にはどのような相関がありますか？」といった数か月にわたるデータについての質問は、コストがかさみます。

しかし、この設計がもはや一般的とは限りません。2026 年 3 月の Garmin の認証変更でエコシステムが数週間にわたって機能しなくなって以来、複数のプロジェクトがローカルストレージを追加し、最大規模のサーバーはトレーニング負荷や HRV の傾向をサーバー側で算出するようになりました。データの所有権とサーバー側の分析は、今や多くのプロジェクトが取り組んでいます。一方、次の 3 点はまだ一般的ではありません。

• 検証してから提示する睡眠タイミングのアドバイス。 circadian は、時計に記録された睡眠時刻（ミュンヘン・クロノタイプ質問票の、睡眠負債を補正した睡眠中間時刻）からクロノタイプと、それに合った起床時刻を推定します。それぞれに 80％区間を示し、妥当な別の設定を使った場合に推定結果がどれほど変わるかも確認します。さらに、その時刻に近い時間に起きることで Garmin のスコアが実際に高くなったかを、モデルが参照していない夜のデータで検証します。睡眠時間とスケジュールの規則性で説明できる範囲を超えた効果があるかを調べ、効果がなかった場合はそのことも明確に伝えます。クロノタイプ自体は新しいものではありません。ウェアラブルの睡眠データから MCTQ 形式のクロノタイプを報告するツールは、少なくとも 1 つの MCP サーバーを含め、ほかにもあります。推定の不確実性を示したり、アウトオブサンプルで検証したりするものは、ほかに見つけられていません。睡眠タイミングとクロノタイプをご覧ください。
• ログイン不要の取り込み。 Garmin の文書化されていないウェルネス FIT メッセージ（睡眠スコア、HRV、皮膚温、睡眠ステージ、昼寝）をデコードするスタンドアロンのデコーダーは、認証情報なしで、手動でエクスポートしたバンドルを読み込みます。ほかのサーバーは FIT のアクティビティファイルを解析しますが、ウェルネスのエクスポートをデコードするものは、ほかに見つけられていません。Garmin の認証に問題が起きても機能し続ける、唯一の取り込み方法です。
• ラグを考慮した相関。 任意の 2 つの指標について、-7 日から +7 日までのラグを走査しながら、ピアソン相関とスピアマン相関を算出するため、「トレーニング負荷が翌日の安静時心拍数を上げるか」という問いにも答えられます。

それ以外の設計も、自分のデータを手元に保管することを前提としています。

• 一度同期すれば、いつまでも分析できます。 所有するディレクトリ内のローカルウェアハウスに、変更のあったデータだけを同期します。変更不可能な生 JSON スナップショットと SQLite データベースを保存します。
• コンパクトなレスポンス。 傾向、相関、ベースライン、異常検出をローカルで算出し、小さなカラム型テーブルとして返します。通常のレスポンスは 2 KB 未満で、最も情報量の多い circadian でも 3 KB 未満に収まるため、モデルのコンテキストを圧迫しません。
• オフラインでも安心。 API に問題が起きると、新たな同期が一時停止するだけです。同期済みの履歴に対するクエリはすべて引き続き機能し、FIT のインポートでデータの欠損も補完できます。
• 厳選されたツール。 110 個ではなく、組み合わせて使える 13 個のツールを提供します。

	garmin-local-mcp	その他の Garmin MCP の多く
認証不要の取り込み方法	あり（ウェルネス FIT バンドルのインポート）	なし
ラグを考慮した相関（-7 日～+7 日）	あり	なし
クロノタイプと起床時刻のアドバイスを未学習の夜で検証	あり（区間、安定性チェック、ローリング・ホールドアウト）	クロノタイプを報告するものはいくつかありますが、検証するものは見つかっていません
レスポンスサイズの制御	コンパクトなカラム型テーブル。通常 2 KB 未満	生データ。最大規模のサーバーは、50～500 KB の詳細エンドポイントをスキップするようドキュメントに記載
API の問題発生後もオフラインで動作	あり。分析と FIT の取り込みに対応	サーバーによって異なります。一部はローカルキャッシュを保持します
自分で所有するローカルデータストア	あり（生 JSON + SQLite）	現在は複数のサーバーが対応
ツール数	厳選した 13 個	18～148 個

クイックスタート

Python 3.12 以降が必要です。

pip install garmin-local-mcp

または、uv を使ってインストールせずに実行できます。

uvx garmin-local-mcp --help

1. 一度ログインします（MFA に対応しています。トークンはローカルに保存されるため、次回以降の実行でパスワードを求められることはありません）。

garmin-local-mcp login

2. 履歴をバックフィルします。 同期は再開可能で、中断しても安全です。また、Garmin のサーバーに配慮してリクエストの頻度を抑えます。1 年分の履歴では約 1,800 件のリクエストが発生します。長期間のバックフィルを行う場合は、開始してそのまま実行させてください（一晩かけて実行するのがおすすめです）。レート制限がかかったり中断されたりした場合は、同じコマンドを再実行すると、中断した箇所から再開します。

garmin-local-mcp sync --from 2026-01-01

3. MCP サーバーをクライアントに登録します（Claude Desktop、Cursor、その他のクライアントについてはクライアントの設定を参照してください）。

claude mcp add --scope user garmin -- garmin-local-mcp serve

4. 質問します。 Claude はローカルのデータウェアハウスから、1～2 回のツール呼び出しで次のような質問に答えられます。

• 「睡眠スコアは翌日の安静時心拍数とどのように相関していますか？」
• 「今四半期に異常な HRV の日があったのはいつですか？」
• 「過去 3 か月の週ごとのトレーニング負荷と睡眠を表示してください。」

クライアントの設定

このサーバーは stdio で通信するため、どの MCP クライアントでも使用できます。まず pip install garmin-local-mcp を実行してください（または、uv 以外にインストールするものがない、以下の uvx を使った方法を利用してください）。

Claude Code

claude mcp add --scope user garmin -- garmin-local-mcp serve

Claude Desktop（ワンクリック）： 最新リリースから garmin-local-mcp-x.y.z.mcpb をダウンロードします。次に Claude Desktop で「Settings」>「Extensions」>「Advanced settings」を開き、「Install Extension…」をクリックしてファイルを選択します。PATH に uv が必要です。この拡張機能は uvx 経由で PyPI からサーバーをインストールして実行するため、手動で Python を設定する必要はありません。インストールダイアログで Python >=3.12 が見つからないという警告が表示されても、無視できます。uv が独自のインタープリターを用意します。

Claude Desktop（手動）（「Settings」、「Developer」、「Edit Config」の順に開き、claude_desktop_config.json に追加します）。

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-local-mcp",
      "args": ["serve"]
    }
  }
}

Cursor（~/.cursor/mcp.json、またはプロジェクト内の .cursor/mcp.json）。

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-local-mcp",
      "args": ["serve"]
    }
  }
}

その他の stdio クライアント／ローカルにインストールしない場合（uv が必要です）。

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-local-mcp", "serve"]
    }
  }
}

注：login と初回のバックフィル sync は CLI の手順です（クイックスタートを参照してください）。MCP サーバー自体が認証情報を求めることはありません。

13 個のツール

ツール	機能
auth_status	保存済みの Garmin Connect トークンがあるかを確認します（同期前、または認証エラー後に使用します）。
sync	Garmin Connect から最大 60 日分のデータをローカルストアに取得します（デフォルトでは昨日までの直近 30 日分です。大規模な過去データの取得には CLI を使用してください）。
sync_status	テーブルごとのローカルデータの網羅状況、最終同期時刻、未処理の同期エラーを確認します。
get_day	1 日分の統合ビューを表示します。ウェルネス、睡眠、HRV、トレーニングステータス、パフォーマンススコア、アクティビティ、データ品質フラグが含まれます。
query_metrics	2 つの日付間における 1 つ以上の指標の列形式時系列データを、日次／週次／月次の集計とオプションの統計情報付きで取得します。
correlate	2 つの指標間の Pearson／Spearman 相関を、日単位のラグ指定と、ラグ -7〜+7 の任意スキャンに対応して計算します。
baselines	指標ごとに、直近期間（デフォルト 28 日間）の個人平均 ± 標準偏差の範囲を表示し、このユーザーにとっての通常値を判断できるようにします。
anomalies	外れ値の日（z スコアによる偏差）と、継続的な連続期間（平均の片側に 5 日以上連続する期間）を表示します。
list_activities	新しい順に並べた最近のアクティビティをコンパクトなテーブルで表示します。種類、日付範囲、最小距離で絞り込めます。
get_activity	1 件のアクティビティについて、保存された完全な概要行を取得します（概要フィールドのみで、GPS やサンプルストリームは含まれません）。
gaps	テーブルごとの欠落日と未解決の同期エラーを表示し、結論を出す前に再同期する価値のある欠落を見つけます。
import_fit	手動でエクスポートした Garmin ウェルネス FIT バンドルを、認証なしでオフライン取り込みします。
circadian	クロノタイプ（MCTQ）、睡眠必要量、推定起床時間帯を、それぞれ 80% 区間とともに表示します。また、その時間帯と Garmin スコアの上昇との関連性について、サンプル外のエビデンスも示します。睡眠時刻とクロノタイプを参照してください。

データを書き込むのは sync と import_fit のみで、書き込み先はデータディレクトリ内に限られます。サーバーがプロンプトを表示することはありません。認証の問題は、ログイン CLI を案内するヒントを含む構造化エラーとして返されます。

利用可能な指標名には、resting_hr、sleep_score、hrv、steps、stress_avg、body_battery_high、skin_temp_dev_c、vo2max、fitness_age、achievable_fitness_age、training_load、endurance_score、hill_score、readiness_score、race_5k_s、睡眠時刻の指標 sleep_onset_min、wake_time_min、mid_sleep_min（起床日の午前 0 時からの分数で、23:00 の就寝時刻は −60）など、ほかに約 35 種類があります。認識できない名前をツールに渡すと、指標の全一覧が返されます。

パフォーマンススコア

Garmin の定期的なフィットネススコアは、独自の performance テーブルに格納されます。持久力スコア、ヒルスコア（持久力と筋力のサブスコアを含む）、トレーニングレディネス（スコア、レベル、回復時間）、5 km、10 km、ハーフマラソン、フルマラソンのレース予測（すべて秒単位）が含まれます。

これらは毎日ではなく Garmin 独自の頻度で更新されるため、performance は意図的に gaps の対象から除外されています。新しい持久力スコアが記録されていない日は正常であり、欠落ではありません。レース予測とヒルスコアは、条件を満たすランニングアクティビティの後にのみ変動するため、主にハイキング、サイクリング、筋力トレーニングを行うユーザーでは、長期間 null が続くことが予想されます。

睡眠タイミングとクロノタイプ

circadian は、ストアに保存されている睡眠開始時刻と終了時刻から、「体内時計が望む起床時刻はいつか？」を推定します。週単位のブロックブートストラップによる80％区間とともに、個別の3つの量を返します。

1. クロノタイプ（msf_sc）。 ミュンヘン・クロノタイプ質問票の指標です。休日の睡眠中央時刻から、平日の睡眠不足を補うために余分に眠った時間を補正した値です。early（03:30より前）、intermediate、late（04:30より後）に分類されます。区分はおおよその目安で、主な値は数値です。
2. 睡眠必要量。 sleep_need_min を指定しない場合は、休日の夜の平均睡眠時間です。クロスチェックとして、Garminのスコアが横ばいになる範囲も併記されます。
3. 概日リズムに適合する起床時間帯。 msf_sc + sleep_need / 2 です。これは推定値で、MCTQの出力ではありません。睡眠負債の返済がなければ、平均的な休日の起床時刻になります。睡眠負債の返済がある場合は、返済分の半分だけその時刻を早めた値になります。

続いて、この推定を実際の結果と照合します。

• 安定性。 90日、180日、365日の各期間、睡眠中央時刻の平均値と中央値、3種類の移動フィルター幅を使って、推定を再計算します。通常、stability: low はスケジュールが変化したことを意味します。変化後の start を指定してください。
• エビデンス。 ローリング方式のホールドアウト（120日間で学習し、次の30日間でテスト）を使い、睡眠時間のみのモデルと、概日リズムに適合する起床時刻からのずれを加えたモデルを比較します。また、スケジュールの規則性を考慮した別のモデルペアでも比較します。レベルは consistent、supportive、suggestive、unsupported のいずれかです。これらは、未確認の夜にパターンがどれほど一貫して当てはまったかを表します。統計的有意性を示すものではなく、エビデンスの評価には少なくとも180日分の履歴が必要です。
• 示せないこと。 リカバリーと睡眠スコアはGarmin独自の複合スコアであり、生理学的な測定値ではありません。導ける最も強い結論は、モデルが参照していない夜において、起床時刻が推奨時間帯に近いことが、睡眠時間と規則性から予測される範囲を超えて、Garminスコアの高さと 関連していた というものです。起床時刻が生理機能を変化させることを示すものではありません。

計算式による推定と過去のスコアが30分以上食い違う場合、ツールは両方を残し、それらの平均を取るのではなく、両者の間で21夜にわたる実験を行うことを提案します。休日はデフォルトで土曜日と日曜日の朝ですが、free_days で変更できます。休日にもアラームを設定している場合、クロノタイプは体内時計よりも早い時刻になります。期間内の夏時間の変更は、設定された timezone またはホストのタイムゾーンを使って一覧表示されます。主な睡眠が日中の交代勤務者には、リズムとクロノタイプを提示しますが、起床時間帯は提示しません。

データの配置と所有権

すべてのデータは、ユーザーが所有する1つのディレクトリに保存されます（デフォルトは ~/.garmin-mcp。環境変数 GARMIN_MCP_DATA_DIR または --data-dir で上書きできます）。

~/.garmin-mcp/
├── config.toml                                  # optional settings
├── tokens/                                      # Garmin Connect session tokens
├── raw/daily/YYYY/YYYY-MM-DD/<endpoint>.json    # immutable raw API snapshots
├── raw/activities/<activity_id>.json            # one snapshot per activity
└── garmin.db                                    # SQLite warehouse

未加工のJSONスナップショットが信頼できる唯一のデータであり、上書きされることはありません。SQLiteデータベースは、そこから生成され、再構築可能なインデックスです。garmin-local-mcp reparse を実行すると、未加工のスナップショットから完全にオフラインで再構築されます。これは、スキーマの進化やパーサーの修正にいつでも使える手段です。データがマシンの外部に送信されることはありません。

データ品質に関する注意

Garmin のウォッチは、デバイス上で暫定的な安静時心拍数を報告します。サンプリングがまばらな夜には、この値が Garmin Connect の確定値と大きく異なることがあります。実際に、ウォッチでは 69 bpm と報告された一方、後に Garmin Connect では同じ夜の値が 56 bpm に確定されたケースがありました。

このプロジェクトでは、次の 2 つの方法で対処します。

• API 同期では、Garmin Connect の確定値を保存します。
• FIT インポーターでは、デバイス上の暫定値を夜間の心拍数の最低値と照合します。安静時心拍数が夜間の最低サンプルより 10 bpm を超えて高い場合、その心拍数はウォッチが実際に観測したことのない値です。そのため、フラグ（rhr_far_above_hr_floor）を付けて保留し、誤解を招く数値を保存する代わりに、API による後からの補完に任せます。

睡眠ステージの記録がまばらな場合も同様にフラグ（sparse_sleep_stage_logging）が付き、get_day にフラグが表示されるため、分析レイヤーでどの数値を信頼すべきか判断できます。

オフライン／フォールバック手順書

Garmin の非公式 API が再び動作しなくなった場合（以前にも発生しています）：

1. 分析機能はすべて引き続き動作します。 クエリ、相関、ベースライン、異常、ギャップに関するすべてのツールは、すでに同期済みのローカル履歴を使って動作します。一時停止するのは新しい同期のみです。
2. 認証なしでデータの取り込みを続けます。 Garmin Connect のウェブサイトから日単位の FIT バンドルをダウンロードし、ローカルにインポートします（詳しい手順は以下を参照してください）。 garmin-local-mcp import-fit <folder> は認証なしでバンドルをデコードし、欠落日を補完します。--force を指定しない限り、FIT 由来の行が API 由来の行を上書きすることはありません。
3. コミュニティが対応したら再開します。 修正状況を python-garminconnect プロジェクトで確認し、アップグレードしてから、再度 garmin-local-mcp sync を実行します。同期状態が再開可能なため、停止した位置から正確に再開できます。

ウェルネスバンドルをダウンロードする手順

1. 任意のブラウザーで connect.garmin.com にサインインします。

2. 次のページに直接アクセスします。 https://connect.garmin.com/app/settings/accountInformation （または、右上のアバターをクリックし、Settings、左サイドバーの Account Information の順に選択します）。

3. ページ下部にある Export Wellness Data セクションまでスクロールします（「特定の日のウェルネス FIT ファイルをダウンロードします。歩数、睡眠、ストレス、HRV などのデータが含まれます。」）。

4. Date フィールドで日付を選び、Export をクリックします。ブラウザーがその 1 日分の小さな ZIP ファイルをダウンロードします。ZIP には、約 12～15 個のバイナリ .fit ファイル（*_WELLNESS.fit、*_SLEEP_DATA.fit、*_HRV_STATUS.fit、*_SKIN_TEMP.fit、*_METRICS.fit など）が含まれています。

5. 展開してフォルダーに保存し、次を実行します。

   garmin-local-mcp import-fit "path/to/unzipped/folder"
   

6. 欠落している日ごとに繰り返します（日付ごとに 1 つのバンドル）。どの日を補完する必要があるかは、gaps ツールまたは garmin-local-mcp status で確認できます。

知っておくとよい点が 2 つあります。

• 夜間の睡眠は、起床した日付に属します。 今朝まで眠っていた場合、昨夜の睡眠を取得するには、昨日ではなく、起床した日付をエクスポートしてください。
• この日単位のエクスポートはすぐに完了し、Garmin のアカウント全体のエクスポート（同じページにある「Data Management」リンク）とは別です。後者は一括アーカイブで、メールで届くまで数日かかることがあり、import-fit が想定しているものではありません。

設定

データディレクトリ内に任意で配置する config.toml：

キー	デフォルト	説明
timezone	システムのタイムゾーン	同期範囲の「昨日」の計算に使用する IANA 名（例：America/Denver）
units	metric	metric または statute
request_delay_seconds	1.0	同期中の API リクエスト間の遅延
baseline_window_days	28	baselines ツールのデフォルトの直近期間

環境変数：

変数	説明
GARMIN_MCP_DATA_DIR	データディレクトリを上書きします（デフォルトは ~/.garmin-mcp）
GARMINTOKENS	トークン保存場所を上書きします（デフォルトは <data_dir>/tokens）
GARMIN_EMAIL / GARMIN_PASSWORD	対話なしで再ログインする場合に任意で指定します。設定すると、garmin-local-mcp login は入力を求めません（アカウントで必要な場合は MFA の入力を求められることがあります）

開発

python -m venv .venv
.venv/bin/pip install -e .[dev]     # Windows: .venv\Scripts\pip install -e .[dev]
pytest
ruff check .

テストスイートは、サニタイズ済みの JSON フィクスチャと小さな FIT サンプルを使用して完全にオフラインで実行されます。CI が実際の API にアクセスすることはありません。

免責事項

このプロジェクトは Garmin Ltd. と提携、承認、またはサポートを受けていません。 コミュニティの python-garminconnect ライブラリを使用し、ご自身の認証情報でご自身のデータにアクセスします。Garmin の API は 非公式であり、いつでも変更されたり動作しなくなったりする可能性があります。その場合も、同期済みの 履歴は引き続きすべて利用でき、FIT のインポート経路も引き続き機能します。

すべてのデータはお使いのマシンに保存されます。外部への通信は一切ありません。テレメトリーも、 サードパーティーサービスも、クラウドもありません。データディレクトリは個人の 健康記録として扱い、リポジトリにコミットしないでください。

ライセンス

MIT