garmin-mcp

Claude Desktop から Garmin Connect のランニング、筋力トレーニング、カロリーデータに読み取り専用でアクセスできる小さな MCP サーバーです。3 つのツールがあり、セットアップには約 15 分かかります。

これを構築した理由は、進捗を追跡したり、自分のトレーニングデータを分析したり（例：イージーランのペースがどう変わったか、ランニングもした日に何を持ち上げたか）する際に、手動で CSV をエクスポートしなくて済むようにするためです。Garmin の Connect API に直接通信するため、間にサードパーティのサービスはなく、データがアップロードされることもありません。

ツール

• list_runs(limit, start)：日付、ランの種類、距離、時間、平均ペース、平均および最大心拍数、ケイデンス、気温。トレッドミルランも対象。

• list_strength(limit, start)：日付、セッション名、時間、セット数、レップ数、総カロリーとアクティブカロリー、平均および最大心拍数。

• daily_calories(days, end)：1 日あたりの合計、アクティブカロリー、基礎代謝カロリー、歩数、安静時心拍数。

start は行オフセット、end は日付なので、Claude は最新の数エントリだけでなく、何年分もの履歴をページ送りできます。

すべて読み取り専用です。下位のライブラリ（garth-ng）は書き込みエンドポイントも公開していますが、ここではそれらを一切呼び出していません。これが唯一の安全性の保証であり、トークン自体はアカウントへのフルアクセスを許可するからです。

必要条件

Python 3.12 以上、uv、Claude Desktop、および Garmin Connect アカウント。以下のコマンドは Unix シェル（macOS または Linux）を想定しています。Windows でも動作しますが、パスが異なります。Claude Desktop 自体は macOS、Windows、Linux（Ubuntu および Debian でベータ版）で動作します。これは Claude モバイルアプリや claude.ai では動作しません。ローカルの stdio サーバーには接続先の URL がないためです。

セットアップ

1. Garmin のパスワードを、他では使用していないものに変更します。これからスクリプトに入力するためです。

2. クローンしてインストール：

git clone https://github.com/SuvirRathore/garmin-mcp-public.git
cd garmin-mcp-public
uv sync

3. 一度だけ認証を行います。これにより、パスワードが ~/.garth に保存された OAuth トークンと交換され、その後パスワードは不要になります：

cd garmin-mcp-public
uv run auth_setup.py

プロンプトが表示されたら MFA コードを入力します。OAuth1 トークンは約 1 年間有効で、OAuth2 トークンは自動更新されるため、これはほぼ年に一度の作業です。~/.garth は資格情報として扱ってください。これを保持している人は誰でも Garmin アカウント全体を読むことができます。

4. Claude を使う前に、ツールを直接テストします。ここでの失敗は MCP の問題ではなく、認証またはエンドポイントの問題であり、Desktop のログよりもはるかに迅速にデバッグできます：

cd garmin-mcp-public
uv run python -c "import server; print(server.list_runs(3))"
uv run python -c "import server; print(server.list_strength(3))"
uv run python -c "import server; print(server.daily_calories(7))"

5. 設定に必要な 2 つの絶対パスを見つけます：

cd garmin-mcp-public
which uv
pwd

6. Claude Desktop の設定ファイルを作成または編集し、以下のブロックを貼り付け、2 つのパスを手順 5 の出力で置き換えます。実際のパスを貼り付けると、YOUR_USERNAME の両方のインスタンスも削除されます。ファイルは macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json にあります。Linux ベータ版では、現在の場所について Anthropic の Claude Desktop ドキュメントを確認してください。

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/path/to/garmin-mcp-public",
               "run", "server.py"]
    }
  }
}

両方のパスは絶対パスである必要があります。Desktop は最小限の PATH でサーバーを起動するため、シェルでは動作しても裸の uv は失敗します。既に他のサーバーを設定している場合は、オブジェクトを置き換えるのではなく、garmin エントリをそれらと一緒に追加してください。このファイルを TextEdit で編集する場合は、まずスマート引用符をオフにしてください。引用符が曲がっていると JSON が無効になります。

7. Claude Desktop を完全に終了し（Cmd+Q、ウィンドウを閉じるだけではない）、再度開きます。設定は起動時にのみ読み込まれます。次に、"最近のラン 5 件と今週のカロリー消費を表示して" などと依頼し、ツール呼び出しを承認します。

動作しない場合

まず JSON を検証し、次にサーバーの stderr を読みます。以下は macOS のパスです。プラットフォームに合わせて調整してください：

cd garmin-mcp-public
uv run python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
tail -50 ~/Library/Logs/Claude/mcp-server-garmin.log

すべての呼び出しでエラーが発生する場合、通常はトークンの期限切れを意味します。auth_setup.py を再実行してください。Claude 内の "カスタムコネクタを追加" ダイアログはここでは関係ありません。これはリモートの HTTPS URL を想定しているからです。

拡張する方への注意

Garmin の Connect API はドキュメント化されておらず、フィールド名が変わることがあるため、何かが空で返ってきた場合は、推測するのではなく、実際のオブジェクトを 1 つ調べてください。以下をリポジトリに probe.py として保存し、uv run probe.py で実行します。シェルに貼り付けないでください：

import garth

garth.resume("~/.garth")
a = garth.connectapi(
    "/activitylist-service/activities/search/activities",
    params={"start": 0, "limit": 1},
)[0]
print(sorted(a))

ツールを追加する前に知っておくべき動作が 2 つあります。activityType フィルターは親カテゴリのみを受け入れます。running は機能し、treadmill_running を暗黙的に含みますが、strength_training は HTTP 400 を返すため、fitness_equipment としてリクエストし、Python でフィルタリングする必要があります。また、各アクティビティには約 100 のフィールドがあるため、必要な少数にマッピングしてください。生の Garmin JSON を返すと、呼び出しのたびにコンテキストウィンドウが溢れてしまいます。

同じ理由で、ツールの数は少なく保ってください。説明的なドキュメント文字列を持つ 3 つの焦点を絞ったツールは、12 の曖昧なツールよりも効果的に機能します。なぜなら、ドキュメント文字列は Claude がどのツールを呼び出すかを選択する際に読み取るものだからです。

MIT ライセンス。