garmin-mcp

Garmin MCP

トレーニングの本当の調子を、AI アシスタントに尋ねてみましょう。 Garmin MCP は、Garmin Connect のデータを扱う非公式のオープンソース MCP サーバーです。公開されているスポーツ科学文献の手法と引用をもとに、トレーニング負荷、コンディション、朝の準備状態をお使いのマシン上で算出します。Garmin の API をそのまま映すのではなく、アスリートが尋ねる質問を想定した 20 個のツールを備えています。質問に必要なデータだけをダウンロードするローカル SQLite キャッシュや、回答から Garmin のカレンダーとウォッチへ送れる構造化ワークアウトも利用できます。また、アクティビティ、健康、睡眠、トレーニングステータス、体組成、ギア、デバイス、ワークアウトライブラリも読み取ります。

Claude Code、Claude Desktop、Codex、Antigravity CLI、opencode、およびその他すべての MCP クライアント（stdio または streamable HTTP）で動作します。

ドキュメント：endurancetools.github.io/garmin-mcp（クライアントごとの導入方法、質問例、設定、トラブルシューティング）。貢献と開発については、DEVELOPMENT.md をご覧ください。

非公式プロジェクトです。Garmin および Garmin Connect は Garmin Ltd. またはその子会社の商標です。このプロジェクトは Garmin と提携しておらず、Garmin による承認も受けていません。トレーニング分析（get_load、get_readiness）はトレーニングに関する情報であり、医療上の助言ではありません。

Garmin MCP を選ぶ理由

• 確認できる回答。 パワー、ペース、心拍数、セッション RPE に基づくトレーニング負荷（TSS）、フィットネス、疲労、コンディション（CTL/ATL/TSB）、ACWR、強度分布、そしてご自身の基準値と比較した HRV、安静時心拍数、睡眠、負荷に基づく朝の準備状態を、公開されているスポーツ科学文献の手法と引用を用いて算出します。すべての回答には、使用した値とルールが示され、変更することもできます。手法とエビデンス
• API のミラーではなく、設計されたツール。 「今週のトレーニングを振り返って」や「今日は強度の高いトレーニングをしてもいい？」といった質問を想定した 20 個のツールを備えており、1 回の呼び出しで 1 つの質問に答えます。ツール一覧全体がモデルのコンテキストで消費するトークンは約 7,800 個で、42 件のツール選択シナリオすべてで、最初のツール呼び出しが適切でした。設計されたツール
• ローカルでプライベート。 Garmin の公式ページでサインインするため、パスワードがツールを経由することはありません。ダウンロードされたデータはお使いのコンピューター上のローカルデータベースに保存され、回答は数ミリ秒で返されます。Garmin に負荷をかけないようダウンロード頻度を調整し、ツールの回答は接続先の AI クライアントにのみ送信されます。データの保存場所
• 回答からウォッチへ。 「木曜日に 400 m を 6 本、レスト 90 秒」と尋ねると、まず手順と推定所要時間が表示されます。承認するまで保存されず、承認後に Garmin のカレンダーへ追加され、ウォッチと同期されます。ワークアウトとカレンダー

はじめに

必要条件：Node.js 22 以降、Garmin Connect アカウント、およびサインイン画面用の Chrome、Edge、Brave、または Chromium（ターミナルでの代替手段もあります）。

1. 一度サインインします。 ブラウザーで Garmin 独自のサインインページが開きます。パスワードがツールを経由することはありません。保存されるのは Garmin が発行するトークンのみで、保存先は ~/.garmin-mcp です。

npx -y garmin-mcp-cli login

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

クライアント	設定
Claude Code	claude mcp add garmin -- npx -y garmin-mcp-server
Claude Desktop	GitHub リリースから garmin-mcp-<version>.mcpb をインストールするか、claude_desktop_config.json に追加します：{"mcpServers":{"garmin":{"command":"npx","args":["-y","garmin-mcp-server"]}}}
Codex	~/.codex/config.toml：[mcp_servers.garmin] command = "npx" args = ["-y", "garmin-mcp-server"]
Antigravity CLI	agy mcp add garmin npx -y garmin-mcp-server
opencode	opencode.json：{"mcp":{"garmin":{"type":"local","command":["npx","-y","garmin-mcp-server"],"enabled":true}}}
その他のクライアント	コマンド npx、引数 -y garmin-mcp-server、トランスポート stdio

3. 質問します。 質問に必要になるまで、データはダウンロードされません。たとえば：

• 「今週の睡眠はどうでしたか？」または「夏の間、HRV はどのように推移しましたか？」
• 「今週のトレーニングを振り返って」または「2026-08-04 から 2026-09-28 までのトレーニング期間を要約して」
• 「疲労していますか？今のコンディションはどうですか？」
• 「次のレースはいつですか？」または「今週の予定は何ですか？」
• 「木曜日に、90 秒休憩を挟む 400 m を 6 本のメニューを作って」（まずステップが表示され、同意するまで保存されません）
• 「アクティビティ 21001 の名前を Parkrun PB に変更して」

任意：範囲を事前に読み込むと、最初の質問にもすぐに回答できます。

npx -y garmin-mcp-cli sync --scope all --from 2026-07-01 --to 2026-09-30

データの取得方法

ログイン時にもサーバーの起動時にも、データはダウンロードされません。質問に必要な日付がローカルデータベースにない場合、ツールは該当範囲だけをダウンロードし、最大 20 秒待ってから回答します。残りのダウンロードはバックグラウンドで続行され、回答にはその旨が示されます（meta.source は partial です）。ダウンロードしたデータはすべてローカルデータベースに保存されるため、保存済みの日付は --force を指定しない限り再ダウンロードされず、同じ質問を繰り返しても費用はかかりません。

Garmin への負荷を抑えるため、長い期間は 7 日単位のチャンクに分け、新しい順に取得します。実際にデータをダウンロードしたチャンクの後にはランダムな 1～11 秒の間隔を設け、リクエスト数は 1 日あたり最大 600 件です。429 エラーまたは Cloudflare チャレンジが発生すると、すべてのダウンロードが 6 時間停止します。同期が中断された場合は、中断した箇所から再開します。

GARMIN_AUTO_FETCH=false の場合、garmin sync または garmin_sync ツールを実行しない限り、データはダウンロードされません。この場合、読み取りツールは不足している範囲を meta.sync_hint に返し、モデルが先に確認します。

実際のアカウントで 90 日間同期した後の測定結果（約 1 時間で 433 件のリクエスト）：回答はローカルデータベースから 1～110 ms で取得されます。

ツール

ツール	目的
get_activities	カーソルページングに対応した詳細なアクティビティ一覧です。type には Garmin のタイプキー（garmin://activity-types にあるすべてのキー）を指定します
get_activity	1 件のアクティビティを取得します。summary、splits、hr_zones、power_zones、weather、exercise_sets（筋力トレーニングのセット）、または full（すべてのセクションと、生データストリーム。50 KB 単位のページ）を指定できます
update_activity	名前、タイプ、説明、RPE、体感を更新します
download_activity_file	FIT（解凍済み）、GPX、TCX、KML、CSV をダウンロードディレクトリ（GARMIN_FIT_DOWNLOAD_DIR）にダウンロードします
query_health	歩数（1 日の距離を含む）、安静時心拍数（1 日の最小／最大心拍数を含む）、HRV（ステータスとベースラインを含む）、睡眠、ストレス、ボディバッテリー、呼吸数、SpO2、運動強度時間、カロリー（消費量、および食事ログがリンクされている場合は摂取量）、階数を取得します。日単位または週単位で、7 日／28 日の傾向も取得できます
get_sleep	1 晩分の睡眠ステージ、または平均値を含む期間を取得します
get_training_status	VO2max、トレーニング準備度、回復時間、Garmin ステータス、負荷と負荷の重点、garmin_load_model（Garmin のトレーニング負荷から算出した CTL／ATL／TSB。日別データも指定可能）、レース予測、持久力／登坂スコア、フィットネス年齢、自己記録、順化を取得します
get_body_composition	体重測定値を kg 単位で取得し、傾向を表示します
get_period_summary	週、月、または最大 366 日間の任意の from..to 範囲について、スポーツ別の運動量、心拍ゾーン、休息日、最長／最も負荷の高いアクティビティ、期間末の garmin_load_model、健康とエネルギーの平均値を取得します
list_workouts, get_workout	ワークアウトライブラリ、予定されているワークアウト、カレンダーのレースやイベントを任意の日付範囲で取得します（デフォルトは今後 60 日間）。手順も確認できます
create_workout, schedule_workouts	プリセット（ランニングのインターバル、ウォーキング／ランニング、イージー Z2、筋力トレーニングのサーキット）または入力した定義（入れ子にできる反復、心拍数／ペース／パワーの目標）からワークアウトを作成します。create_workout に dry_run: true を指定すると、保存せずに手順と推定所要時間を表示します。schedule_workouts はワークアウトをカレンダーに登録し、登録を解除します
get_gear, get_devices	距離を含むギアと、最終同期日時および設定を含むデバイスを取得します
garmin_sync	進捗通知を表示しながら、対象範囲（all/activities/health/training/reference）と日付範囲を指定して明示的にダウンロードします
get_load	独自の負荷モデルを取得します（日付ごとに有効な閾値を使い、パワー、ペース、心拍数、または RPE からアクティビティごとの TSS を算出）。CTL／ATL／TSB、ACWR 7:28、単調性と負担、上書き可能な閾値によるフラグ、スポーツ別の ISO 週、3 ゾーンの強度配分を取得します。日別データ、アクティビティごとの TSS／IF／負荷の算出元／EF、月別 EF の傾向も指定できます
get_readiness	HRV、安静時心拍数、睡眠時間、負荷から朝の GO／MODIFY／REST を判定します。Garmin のトレーニング準備度、ボディバッテリー、ストレス、睡眠スコアも表示されますが、判定には加算されません。rules は上書き可能で、各シグナルの値、基準、評価を確認できます
get_thresholds, set_threshold	日付ごとの閾値履歴（スポーツ別の LTHR、LT1、HRmax、FTP、VO2max など。Garmin プロフィールの変更は自動記録）、Garmin プロフィールに基づくスポーツ別の心拍ゾーンとパワーゾーンを取得し、テスト結果をローカルにのみ記録します

delete_activity、delete_workout、delete_weigh_in、および保存済みワークアウトの上書き（workout_id を指定した create_workout）は、GARMIN_ENABLE_DESTRUCTIVE=true の場合にのみ利用できます。

リソース：garmin://profile、garmin://gear、garmin://devices、garmin://activity-types、garmin://sync-status、および ID 補完に対応したテンプレート garmin://activity/{id} と garmin://workout/{id}。プロンプト：weekly_review、plan_next_week。

すべてのレスポンスは JSON テキストおよび outputSchema に一致する structuredContent として、{ data, meta: { source: cache|live|partial|local, fetched_at, coverage?, sync_hint? } } の形式で返されます。失敗時は { error: { code, message, hint } } の形式で返されます。

分析ツールの数式、デフォルト値、制限については、docs/analytics.md を参照してください。対象となる Garmin Connect データと、未対応のデータについては、docs/coverage.md を参照してください。

CLI

garmin-mcp-cli はサーバーとコアを共有しており、セットアップや確認に便利です。

garmin login [--strategy auto|browser|curl|fetch] [--email] [--token-path]
garmin import-tokens <file>          # garmin_tokens.json from python-garminconnect 0.3.x
garmin status [--json]
garmin sync [--scope ...] [--from --to] [--force] [--pause <s>]   # default: last 7 days
garmin activities [--from --to --type --limit --json]
garmin health <metric> [--from --to --week --json]
garmin load [--from --to] [--source auto|hrtss|garmin_load] [--flags <file.json>] [--series] [--activities] [--efficiency] [--by-sport] [--json]
garmin readiness [date] [--rules <file.json>] [--json]          # GO / MODIFY / REST for the morning
garmin thresholds [--date --param --history --json]             # LTHR, LT1, HRmax ... in effect, per sport
garmin thresholds add <date> <param> <value> [--source test|manual] [--note]
garmin thresholds export [--out <file.csv>]                     # date,param,value,source,note
garmin thresholds import <file.csv>
garmin import-activities <file.csv...>                          # Garmin Connect "Activities" CSV exports
garmin doctor                        # TLS strategy, hosts, permissions, tokens, SQLite driver
garmin serve [--transport stdio|streamable-http] [--port]
garmin logout

load、readiness、thresholds は、get_load、get_readiness、get_thresholds ツールと同じ結果を出力します。デフォルトでは Markdown テーブルを、--json を指定するとツールの { data, meta } エンベロープを出力します。ローカルデータベースのみを読み取り、ダウンロードは行いません。データがない日については、そのデータを補完する garmin sync コマンドを記載した注記を返します。import-activities は、同期済みのアクティビティではカバーされていない日付のアクティビティを、Garmin Connect の CSV エクスポート（英語またはポーランド語のヘッダー）から追加します。また、thresholds export／import を使うと、閾値の履歴を CSV ファイルに保存できます。

npx -y garmin-mcp-cli <command> で実行するか、グローバルにインストールします（npm i -g garmin-mcp-cli）。

サインイン

garmin login は、インストール済みの Chrome、Edge、Brave、Chromium で Garmin の正式なサインインページを開きます（一時プロファイルを使用し、終了後に削除します）。そこでサインインします。Garmin から求められた場合は、MFA または CAPTCHA にも対応してください。このツールが取得するのは、サインイン後に Garmin がリダイレクトするワンタイムチケットのみで、そのチケットをトークンに交換します。Cloudflare からは実際のブラウザーとして認識されます。ブラウザーが見つからない場合は、GARMIN_BROWSER_PATH を設定してください。

ブラウザーを使えない環境（ヘッドレスサーバー、Docker）や、--strategy curl|fetch を指定した場合は、ターミナルでメールアドレス、パスワード、MFA の入力を求め、Garmin のモバイルログイン API に接続します。まず curl-impersonate（オプションの cuimp パッケージを使用し、初回実行時にバイナリーをダウンロード）を試し、次に通常の fetch を試します。こちらもブロックされる場合は、Python でログインしてトークンをインポートしてください。正確なコマンドは garmin doctor が表示します。

uvx --with "garminconnect>=0.3" python <path>/python-login.py ~/.garmin-mcp/garmin_tokens.json
garmin import-tokens ~/.garmin-mcp/garmin_tokens.json

トークンとデータベースは、アクセス許可が 0700 のディレクトリ内に 0600 で保存されます。アクセス許可がこれより緩い場合、サーバーは起動を拒否します。

リモート接続と Docker

Streamable HTTP：GARMIN_MCP_TRANSPORT=streamable-http GARMIN_MCP_HTTP_TOKEN=<secret> npx -y garmin-mcp-server を実行すると、Authorization: Bearer <secret> を指定した POST /mcp を提供します。トークンを指定しない場合は、127.0.0.1 のみで待ち受けます。Host または Origin が localhost、127.0.0.1、[::1] 以外のリクエストには 403 を返します（DNS リバインディング対策）。パブリックホスト名の背後で実行する場合は、GARMIN_HTTP_ALLOWED_HOSTS=mcp.example.com で追加してください。

このサーバーは、stdio と HTTP の両方で、通常の initialize ハンドシェイクを通じて MCP 2026-07-28（server/discover、一覧結果は 1 時間キャッシュ）および 2025 年の各リビジョンに対応しています。そのため、古い MCP SDK を使うクライアントも変更せずに接続できます。

Docker：docker build -t garmin-mcp . && docker run -i -v garmin-data:/data garmin-mcp（docker run -it -v garmin-data:/data garmin-mcp login でログインします）。

設定

優先順位：CLI フラグ > 環境変数 > <data dir>/config.json > デフォルト。~、$HOME、${HOME} は常に展開されます。

変数	デフォルト
GARMIN_DATA_DIR	~/.garmin-mcp	トークン、データベース、config.json
GARMIN_TOKENS_FILE	$GARMIN_DATA_DIR/tokens.json
GARMIN_EMAIL、GARMIN_PASSWORD		初回ログイン時のみ
GARMIN_REGION	global	cn にすると、3 つすべてのホストが切り替わります
GARMIN_SSO_STRATEGY	auto	auto（インストール済みならブラウザー、そうでなければターミナル）、browser、curl、fetch、import
GARMIN_BROWSER_PATH	検出されたパス	サインインウィンドウに使用する Chrome／Edge／Brave／Chromium
GARMIN_ENABLED_TOOLS、GARMIN_DISABLED_TOOLS		カンマ区切りの許可／拒否リスト
GARMIN_ENABLE_DESTRUCTIVE	false	削除ツールとワークアウトの上書き
GARMIN_AUTO_FETCH	true	読み取りツールが不足データを自動でダウンロードします。false の場合：明示的な同期のみ
GARMIN_FIT_DOWNLOAD_DIR	$GARMIN_DATA_DIR/downloads
GARMIN_MCP_TRANSPORT、GARMIN_MCP_PORT、GARMIN_MCP_HOST、GARMIN_MCP_HTTP_TOKEN	stdio、8000、127.0.0.1、
GARMIN_HTTP_ALLOWED_HOSTS		カンマ区切りのホスト名（ポートなし、IPv6 は角括弧で囲む）。localhost、127.0.0.1、[::1] に加えて、Host／Origin で許可するホスト名を指定します。それ以外は 403 が返されます
GARMIN_LOG_LEVEL	info	stderr に出力する pino JSON
GARMIN_TIMEZONE	システム	「今日」に使用する IANA タイムゾーン
GARMIN_CONCURRENCY	4	並列の connectapi リクエスト数
GARMIN_MIN_REQUEST_INTERVAL_MS	250	リクエスト開始間隔（ジッター ±25 %）
GARMIN_SYNC_CHUNK_DAYS / GARMIN_SYNC_PAUSE_S / GARMIN_SYNC_MAX_REQUESTS_PER_DAY	7 / 1-11 / 600	同期のペース設定。休止時間は秒単位で、ランダムな範囲または固定値を指定します
GARMIN_DI_CLIENT_IDS、GARMIN_APP_VERSION、GARMIN_APP_USER_AGENT	組み込み値	Garmin がモバイルアプリの識別情報を変更した場合に使用します

詳細

• DEVELOPMENT.md：モノレポの構成、テスト、ツールリストの予算、評価、リリース。
• docs/coverage.md：Garmin Connect のすべての読み取りと書き込み、およびそれに対応するツール。
• CHANGELOG.md。
• ライセンス：MIT。作者：Marcin Milewicz（LinkedIn）。