durely insights MCP for Garmin

durely garmin-insights-mcp

Garmin の自分のデータについて AI アシスタントに質問できます。トレーニング履歴全体、健康状態、回復状況を分析します。

durely insights は、Garmin の公式 Personal API を通じて、Garmin Connect アカウントを AI アシスタント（Claude、Cursor、GitHub Copilot、Gemini CLI、Codex など、あらゆる MCP クライアント）に接続するMCP サーバーです。履歴のコピーを自分のマシンに保存するため、1 回のランニングから何年分ものトレーニングまで、すぐに質問して回答を得られます。

開発初期段階です。 以下の機能はすべて動作しますが、バージョン 1.0 までにツールやオプションが変更される可能性があります。

非公式プロジェクトです。Garmin との提携や、Garmin による推奨を受けていません。

質問できること

アクティビティ

• 「今週は何をしましたか？」／「直近のランニングを 10 件表示して」
• 「昨日のランニングについて教えて」：スプリット、心拍数、トレーニング効果、負荷
• 「火曜日のライドのインターバル中に、パワーと心拍数はどのように変化しましたか？」
• 「直近 2 回のトライアスロンのバイク区間を、ラップごとに比較して」
• 「いつもの火曜日のランニングで、体力は向上していますか？」

トレーニング

• 「過去 3 か月間で、トレーニング負荷とフィットネスはどのように変化しましたか？」
• 「土曜日のライドを分析して」：ゾーン別の時間、デカップリング、ベストエフォート
• 「年ごとのランニング、ライド、スイムの距離を教えて」

健康と回復

• 「今週の睡眠と HRV はどうでしたか？」
• 「ハードなトレーニングをした翌朝は、HRV に影響がありますか？」
• 「今年の月ごとの安静時心拍数と睡眠スコアを比較して」
• 「昨日の心拍数と Body Battery を表示して」

特長

• 公式 API を使用し、パスワードは不要です。 Garmin Connect で作成でき、いつでも無効にできる Personal API キーを使用します。スクレイピングは行わないため、Garmin のログイン方法が変わっても動作に影響しません。
• 履歴全体をすぐに利用できます。 すべてのデータを一度ローカルデータベースに同期し、その後も最新の状態に保つため、数か月から数年にわたる傾向についての質問にも待たずに回答できます。
• 秒単位の詳細データに対応しています。 ラップ、スイムの距離、心拍数、パワー、ケイデンスなどは、各アクティビティの元の FIT ファイルから取得します。デバイスで記録されている場合は、VO2max、回復時間、乳酸閾値も含まれます。
• 分析機能を内蔵しています。 ゾーン別の時間、トレーニング負荷、フィットネス／疲労／フォーム、有酸素デカップリング、ベストエフォート、回復の傾向、類似セッションの比較に対応しています。それ以外の質問には、アシスタントがデータに対して読み取り専用の SQL を実行できます。
• デフォルトでプライバシーを保護します。 データは自分のマシンに保存されます。名前、アカウント ID、GPS 位置情報は、ルートを尋ねない限り回答に含まれません。
• 読み取り専用です。 Garmin アカウントの情報を変更することはできません。

クイックスタート

Garmin Connect、MCP クライアント（Claude Code、Claude Desktop、Cursor など）、そして Node.js 24 以降またはDockerが必要です。

1. Personal API キーを作成する

1. Web 版の Garmin Connect で、設定 → Personal API Token を開きます。

2. キーを作成し、有効期間（30 日から 1 年）を選択します。Garmin がキーを表示するのは一度だけなので、コピーしてください。

3. 自分のターミナルで次のコマンドを実行して保存します。

   npx -y @durely/garmin-insights-mcp auth
   

   キーの入力を求められます（入力内容は表示されません）。Garmin による確認後、~/.config/garmin/connect-personal-api-key に保存されます。このファイルを読み取れるのは自分だけです。Garmin がキーを拒否した場合、何も保存されません。サーバーはこのファイルからキーを読み込むため、クライアントの設定にキーを記載する必要はありません。

   Docker を使う場合（Node.js 不要）は、次のファイルに自分で保存してください。

   mkdir -p ~/.config/garmin && chmod 700 ~/.config/garmin
   pbpaste > ~/.config/garmin/connect-personal-api-key    # macOS; elsewhere, paste it into this file with an editor
   chmod 600 ~/.config/garmin/connect-personal-api-key
   

AI アシスタントとのチャットにキーを貼り付けないでください。

2. 実行方法を選択する

**Node.js を使う場合（npx）：**インストールは不要です。サーバーのコマンドは次のとおりです。

npx -y @durely/garmin-insights-mcp

初回実行時に npx が npm パッケージ をダウンロードし、その後は新しいリリースを自動的に取得します。npx -y @durely/garmin-insights-mcp auth --check でキーを確認できます。固定のインストールを希望する場合は、npm install -g @durely/garmin-insights-mcp を実行すると、garmin-insights コマンドを使えるようになります。

または Docker を使う場合（Node.js は不要ですが、Docker の起動が必要です）。サーバーのコマンドは次のとおりです。

docker run -i --rm \
  -v ~/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro \
  -v garmin-mcp-data:/data \
  -e GARMIN_MCP_TIMEZONE=Europe/Brussels \
  ghcr.io/durely/garmin-insights-mcp

Europe/Brussels を自分のタイムゾーンに置き換えてください。キーを確認するには、同じコマンドの末尾に auth --check を付けて実行します。イメージは Intel と ARM（Apple シリコン、Raspberry Pi）で動作します。Docker のヒントについては、仕組みをご覧ください。

**またはソースから実行する場合：**リポジトリをクローンし、npm または Docker でビルドします。仕組みをご覧ください。

**更新：**npx の場合は、クライアントを再起動してください。Docker の場合は、docker pull ghcr.io/durely/garmin-insights-mcp を実行します。同期済みのデータは保持されます。

3. AI クライアントに追加する

Claude Code：

claude mcp add garmin --scope user -- npx -y @durely/garmin-insights-mcp

Docker の場合：

claude mcp add garmin --scope user -- docker run -i --rm \
  -v ~/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro \
  -v garmin-mcp-data:/data \
  -e GARMIN_MCP_TIMEZONE=Europe/Brussels \
  ghcr.io/durely/garmin-insights-mcp

--scope user を指定すると、すべてのプロジェクトで利用できるようになります。

Claude Desktop：［設定 → 開発者 → 設定を編集］を開き、次の内容を追加して Claude Desktop を再起動します。

{
  "mcpServers": {
    "garmin": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@durely/garmin-insights-mcp"]
    }
  }
}

デスクトップアプリからはシェルの PATH が見えないため、npx のフルパスを指定してください（which npx で確認できます）。ログに node が見つからないと表示される場合は、"env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" } を追加し、which node で確認したフォルダーを先頭に指定してください。

{
  "mcpServers": {
    "garmin": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/you/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro",
        "-v",
        "garmin-mcp-data:/data",
        "-e",
        "GARMIN_MCP_TIMEZONE=Europe/Brussels",
        "ghcr.io/durely/garmin-insights-mcp"
      ]
    }
  }
}

{
  "servers": {
    "garmin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@durely/garmin-insights-mcp"]
    }
  }
}

gemini mcp add garmin npx -- -y @durely/garmin-insights-mcp

codex mcp add garmin -- npx -y @durely/garmin-insights-mcp

4. 試してみる

新しいセッションを開始して、 「Garmin への接続を確認して。」 と尋ねます。connected と報告されるはずです。

最初の質問をすると、バックグラウンドで同期が始まります。数秒以内にアクティビティが表示され、残りの履歴も数分以内に反映されます。その後、データが 1 時間以上古くなると自動的に更新されます。

知っておくとよいこと

• キーの有効期限に注意してください。 Garmin の API は、キーの有効期限をサーバーに通知しません。クライアント設定で GARMIN_API_KEY_EXPIRES（例：2027-10-24）を設定すると、garmin_status が期限前に通知します。Docker の場合は、代わりにコンテナに渡してください。docker run の引数に -e GARMIN_API_KEY_EXPIRES=2027-10-24 を追加します。キーのファイルを置き換えるだけで十分です。再起動は必要ありません。
• 少なくとも数か月ごとに同期してください。 Garmin は約 4～5 か月後に、日中の心拍数や夜間の HRV 測定値などの詳細な日中データを削除します。サーバーが同期したデータは、ローカルコピーに残ります。
• 現時点ではデスクトップクライアントとコマンドラインクライアントのみです。 サーバーはお使いのマシン上で動作するため、現時点ではウェブ版やモバイル版の claude.ai では動作しません。
• データは AI クライアントに送信されます。 サーバーが通信するのは Garmin のみですが、サーバーが返す回答は、使用する MCP クライアントとモデルに送られます。

トラブルシューティング

ツール

これらを自分で呼び出す必要はありません。アシスタントが選択します。参考までに：

プロンプトに対応したクライアント（多くの場合、スラッシュコマンドとして対応）では、weekly_review、activity_deep_dive、recovery_check を使ってガイド付き分析を開始できます。

設定

すべて任意です。クライアント設定で環境変数として設定してください。

Docker では、キーファイルとデータディレクトリはそれぞれ /run/secrets/garmin_api_key と /data です。

プライバシーとセキュリティ

• キーはお使いのマシンから外に出ません。 キーは24時間有効なトークンに交換され、所有者のみがアクセスできる権限でキャッシュされます。サーバーがキー自体を書き込むことはありません。アクセスを取り消すには、Garmin Connect でキーを削除してください。
• テレメトリーはありません。 サーバーは Garmin の Personal API とのみ通信します。
• 同期データは機密情報です。 ローカルデータベースと FIT ファイルには、GPS トラックを含む健康およびアクティビティの履歴が保存されます。データディレクトリを読み取れるのはお客様のみです（Docker では garmin-mcp-data ボリューム内に保存されます）。
• 回答に個人情報や位置情報が含まれることはありません。 保存前に、名前、プロフィール画像、アカウント ID が削除されます。GPS 位置情報は、ルートや位置の分析を依頼した場合、または SQL でアクティビティの開始地点と終了地点を照会した場合にのみ返されます。

詳細

• 仕組み：ローカルキャッシュと同期、FIT ファイル、数値の計算方法、Docker の詳細、開発

ライセンス

Apache-2.0。LICENSE と NOTICE を参照してください。

データは Garmin デバイスから Garmin Connect を通じて提供されます。分析結果は、Garmin デバイス由来のデータに基づく分析情報です。Garmin および Garmin Connect は、Garmin Ltd. またはその子会社の商標です。本プロジェクトは Garmin と提携しておらず、Garmin による推奨も受けていません。