OwnMetrics

ownmetrics-mcp

Claude、ChatGPT、またはMCP対応のAIアプリに、自分のGarminデータについて質問できます。睡眠、HRV、ストレス、Body Battery、心拍数、アクティビティなどに対応しています。Garminの公式 Personal APIを使用し、お使いのコンピューター上で動作します。読み取り専用です。

非公式プロジェクトです。 Garminとは提携しておらず、Garminによる承認やサポートも受けていません。 「Garmin」と「Garmin Connect」は、Garmin Ltd.またはその子会社の商標です。 結果は情報提供を目的としており、医療上の助言ではありません。

ステータス：v0.2（プレビュー）。 9つのデータツールと4つの分析ツール（トレーニングの概要、期間比較、傾向、トレーニングと睡眠）を備えています。次はFITファイルの分析に対応する予定です。

質問できること

• 「今週の睡眠はどうでしたか？最も悪かった夜とその理由は？」
• 「過去30日間のHRVを表示してください。低下傾向にありますか？」
• 「昨日のストレスとBody Batteryはどうでしたか？」
• 「今月のランニングを、距離と平均ペース付きで一覧表示してください。」
• 「直近の長距離ライドを、パワー、心拍数、トレーニング効果に分けて分析してください。」
• 「安静時心拍数は9月以降どう変化しましたか？」
• 「今年最もよく眠れた月と、その月のトレーニング量を教えてください。」
• 「今年10月と昨年10月の睡眠とトレーニングを比較してください。」
• 「夕方のテニスは睡眠の質の低下につながっていますか？」
• 「Garminとの接続は正常に動作していますか？」

最も簡単な方法：Claude Desktopにワンクリックでインストール

1. Garmin Personal APIキーを作成します。WebでGarmin Connectにサインインし、 設定 → Personal APIを開き、 Create Keyを選択してGarminの規約に同意し、有効期間を選んでキーをコピーします。
2. 最新リリースから ownmetrics-mcp-<version>.mcpbをダウンロードします。
3. ダブルクリックします。Claude Desktopが開き、インストールを確認するので、求められたらキーを貼り付けます。 Claude Desktopではキーはマスクされます。（ownmetrics-mcp authですでにキーを保存している場合は、 フィールドを空欄のままにしてください。）
4. Claudeに「Garminとの接続は正常に動作していますか？」と質問します。

このバンドルはまだ署名されていないため、インストール前にClaude Desktopが警告を表示する場合があります。 初回起動時にはいくつかのPythonパッケージをダウンロードするため、インターネット接続が必要で、少し時間がかかることがあります。

他のアプリ向けのセットアップ（約10分）

Claude Code、ChatGPTデスクトップ、Cursorなど、MCPサーバーに対応したアプリで使う場合や、 Claude Desktopの設定ファイルを使いたい場合は、以下の手順に従ってください。

1. uvをインストールする（初回のみ）

uvを使うと、手動でセットアップせずにPythonツールを実行できます。

• macOS / Linux： ターミナルを開いて、次を実行します。 curl -LsSf https://astral.sh/uv/install.sh | sh
• Windows： PowerShellを開いて、次を実行します。 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Garmin Personal APIキーを作成する

1. WebでGarmin Connectにサインインし、 設定 → Personal APIを開きます。
2. Create Keyを選択してGarminの規約を確認・承諾し、キーの有効期間を選びます （30日から1年まで選択できます）。
3. キーをコピーします。Garminでキーが表示されるのは一度だけです。

3. キーを保存する

uvx ownmetrics-mcp auth

キーを求められたら貼り付けます（入力内容は非表示です）。Garminで検証された後、 ホームフォルダーの~/.config/garmin/connect-personal-api-keyに保存されます。macOSとLinuxでは このファイルを読み取れるのは自分だけです。Windowsではユーザープロファイルフォルダーに保存され、 Windowsアカウントによって保護されます。

4. AIアプリに追加する

Claude Desktop： 「Settings → Developer → Edit Config」を開き、次を追加します。

{
  "mcpServers": {
    "ownmetrics": {
      "command": "uvx",
      "args": ["ownmetrics-mcp"]
    }
  }
}

Claude Desktopを再起動します。

Claude Code：

claude mcp add ownmetrics -- uvx ownmetrics-mcp

その他のアプリ： コマンドuvxを、引数ownmetrics-mcpとともに使用します。

更新

uvxは最初にダウンロードしたバージョンを保持します。最新リリースに更新するには、 uvx ownmetrics-mcp@latest --versionを実行してから、AIアプリを再起動します。

続けて、「Garminとの接続を確認してから、過去1週間の睡眠とHRVを要約してください。」と質問します。

ツール

ツール	返される内容
get_daily_overview	1日分：歩数、距離、階数、心拍数、ストレス、Body Battery、カロリー、運動強度分、睡眠
get_sleep	1晩分：睡眠時間、深い睡眠／浅い睡眠／レム睡眠／覚醒、スコア、Garminからのフィードバック、心拍数、呼吸数
get_hrv	1晩分：昨夜のHRVと週間平均、5分間の最高値、ステータス、ベースライン
get_stress_and_body_battery	1日分：ストレスレベル、各ストレス帯の時間、Body Batteryの最高値／最低値／充電量／消費量
get_heart_rate	1日分：安静時、最低、最高、7日間の安静時平均心拍数、心拍ゾーン
list_activities	日付範囲内のアクティビティ。種類で絞り込むこともできます。運動時間、距離、心拍数も含まれます
get_activity	1つのアクティビティ：ペース、速度、パワー、ケイデンス、トレーニング効果と負荷、スプリット
get_body_metrics	体重測定値、BMI、体脂肪率、水分量、Pulse Ox、フィットネス年齢
get_account_status	キーが有効か、最終日に警告が表示されるか、上記のどのデータ領域が応答するか

インサイトツールは、最大1年分のデータを1回の呼び出しで取得し、計算も行います。

ツール	回答する内容
training_summary	週別または月別のトレーニング：セッション数、時間、週あたりの時間、夜のセッション、スポーツ別の内訳
compare_periods	2つの期間を並べて比較：睡眠、HRV、安静時心拍数、ストレス、Body Battery、歩数、トレーニングと、変化量および変化率
recovery_correlations	トレーニングの翌晩に睡眠とHRVが良くなるか、悪くなるかを、サンプル数と相関の強さとともに示します。相関であり、因果関係ではありません。
trend	指標を日別、週別、月別に表示し、傾向（上昇、下降、横ばい）と30日あたりの変化量を示します

睡眠とHRVの日付は、Garminと同様に、その晩が明けた朝（woke_up_on）の日付です。 ペースはランニング、ウォーキング、ハイキングで表示され、その他のスポーツでは速度が表示されます。筋力トレーニングやピラティスなど、距離が該当しないスポーツでは、距離は「該当なし」と表示されます。

すべてのフィールド名には単位が含まれています（resting_hr_bpm、distance_km、sleep_score_0_100）。 Garminに値がない場合、そのフィールドにはゼロではなく、**「記録なし」**と表示されます。

GarminのPersonal APIで提供されない情報

• **読み取り専用：**ウォッチへのデータ送信や、Garmin Connectへの書き込みはできません。
• **利用不可：**トレーニングレディネス、トレーニングステータス、急性／慢性負荷、VO2 max、ギア、デバイス。推測で補わず、「GarminのPersonal APIでは提供されていません」と表示します。
• データツールは1回の問い合わせにつき最大90日分、インサイトツールは最大366日分を対象とします。サーバーはGarmin独自の制限内に収まるよう、リクエストを分割します。

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

• お使いのコンピューター上で動作します。通信先はGarminのみです。データベースもテレメトリーもありません。
• AIアプリは、プロバイダーの規約に従ってツールの結果をAIモデルに送信します。
• キーがツールの結果、ログ、エラーに表示されることはありません。
• Garmin Connectでいつでもキーを削除し、アクセスを即座に遮断できます。

詳細：PRIVACY.md · THREAT_MODEL.md · 脆弱性の報告：SECURITY.md

GarminのAPIの利用にはGarminの規約が適用されます。キーは個人専用であり、共有してはいけません。

トラブルシューティング

• **「Garmin rejected your Personal API key」：**有効期限が切れているか、削除されています。新しいキーを作成し、手順3をもう一度実行してください。Garminはキーの有効期限が切れる約1週間前にリマインダーをメールで送信します。
• **AIアプリにツールが表示されない：**アプリを完全に終了して再起動してください。macOSでuvxが見つからない場合は、フルパス（ターミナルでwhich uvxを実行）をcommandとして指定してください。
• 接続を自分で確認する： uvx ownmetrics-mcp status

構築方法

このプロジェクトは、仕様駆動開発で構築されています。SPEC.mdには、番号付きの要件と譲れないルールが記載されています。すべての要件はTRACEABILITY.mdのテストに対応しており、CIによって変更のたびに再生成され、チェックされます。コントリビューションも同じ手順に従います。CONTRIBUTING.mdをご覧ください。

Garmin公式の connect-personal-api-pythonクライアントと Model Context Protocol Python SDKを基盤としています。

ライセンス

MIT