garmin-mcp

ローカルMCPサーバーで、Garmin Connectのアクティビティ、健康、トレーニングデータ（アクティビティ、HRV、睡眠、心拍数、ストレス、Body Battery、トレーニングレディネス、心拍数/パワーゾーン、乳酸閾値、FTP、VO2max、自己ベスト、ワークアウト、予定されたワークアウト、トレーニングプラン）をClaude Desktop内のツールとして公開します。

garminconnectライブラリを介して、Garmin ConnectのライブAPIと直接通信します。データは読み取り専用です。Garminに書き戻されることは一切ありません。

認証の仕組み

Garminのログインは、意図的に2つの別々の場所で行われます：

• scripts/setup_auth.py — ターミナルで自分で実行する対話型スクリプト。メールアドレスとパスワードでログインし、Garminから要求された場合はMFAコードを求め、その結果のセッショントークンを~/.garmin_mcp/tokensに保存します。

• MCPサーバー（src/garmin_mcp/server.py）はClaude Desktopによってヘッドレスで起動され、キャッシュされたトークンを読み込んで静かに更新するだけです。MFAのプロンプトを表示することはありません。Claude Desktopにはプロンプトを表示するターミナルがないため、そこでstdinをブロックするとツール呼び出しがハングします。キャッシュされたセッションがないか期限切れの場合は、setup_auth.pyを再実行するように指示するエラーでツール呼び出しが失敗します。

GarminパスワードはmacOSキーチェーン（項目/サービスgarmin-mcp、キーチェーンアクセスで表示可能）に保存され、ファイルに書き込まれることはありません。保存されるのはGarminのログインメールアドレス（機密ではありません）だけで、~/.garmin_mcp/config.jsonに保存されます。

セットアップ

1. 依存関係をインストールします：

   cd garmin_mcp
   uv sync

2. 一度だけの対話型ログインを実行します：

   uv run python scripts/setup_auth.py

   Garmin Connectのメールアドレスとパスワードを入力します（パスワードは次回のためにキーチェーンに保存されます）。プロンプトが表示されたらMFAコードを入力します。成功すると、確認メッセージとトークンキャッシュのパスが表示されます。

3. Claude Desktopにサーバーを登録するには、~/Library/Application Support/Claude/claude_desktop_config.jsonを編集し、（他のmcpServersエントリに加えて）以下を追加します：

   {
     "mcpServers": {
       "garmin": {
         "command": "uv",
         "args": ["run", "--project", "/Users/felix.guiony/Code/Perso/garmin_mcp", "garmin-mcp"]
       }
     }
   }

4. Claude Desktopを完全に終了し（ウィンドウを閉じるだけでなくCmd+Q）、再度開きます。ツール/ハンマーアイコンにgarminツールが表示されるはずです。

ツール

すべての日付パラメータはYYYY-MM-DD形式で、デフォルトは今日です。

トラブルシューティング

ツール呼び出しで "Garmin session error" / "run setup_auth.py" というメッセージが返される。 キャッシュされたリフレッシュトークンの有効期限が切れたか、失効しています（これはまれに発生します。たとえばパスワード変更後や長期間の未使用後など）。再実行してください：

uv run python scripts/setup_auth.py

レート制限。 Garmin Connectはまれに短時間の大量リクエストをレート制限することがあります。基盤となるライブラリは一時的な障害を自動的に再試行しますが、レート制限エラーが表示される場合は、少し待ってから再試行してください。

Claude Desktopの外部でサーバーを直接検証する：

uv run mcp dev src/garmin_mcp/server.py

を実行するとMCP Inspectorが開き、各ツールを手動で呼び出して、その出力/スキーマを確認できます。

プロジェクト構成

garmin_mcp/
  pyproject.toml
  src/garmin_mcp/
    auth.py      # keychain + token-cache helpers
    server.py    # FastMCP server and tool definitions
  scripts/
    setup_auth.py  # interactive one-time/occasional login