Garmin Read-Only MCP

Hermes Agentとローカルで使用するための、意図的に機能を限定したGarmin Connect統合ツールです。 選択したGarminサマリーを所有者のみがアクセス可能なSQLiteキャッシュに同期し、3つの読み取り専用MCPツールを通じて正規化されたキャッシュのみを提供します。

このプロジェクトはコミュニティ保守のpython-garminconnectクライアントと、文書化されていないGarmin Connectエンドポイントを使用しています。Garminとの提携やサポートはありません。エンドポイントは変更される可能性があり、自動アクセスはアカウントや利用規約上のリスクを伴う場合があります。承認されたビジネス統合には、公式のGarmin Connect Developer Programが推奨される方法です。

セキュリティモデル

設計上、ネットワークアクセスとMCPプロセスを分離しています：

1. garmin-readonly-authはローカルターミナルで1回限りの対話型ログインを実行します。パスワードとMFA入力は非表示になり、コマンド引数として受け付けられることはありません。

2. garmin-readonly-syncは再利用可能なローカルセッション情報を読み込み、限定された日付範囲を取得し、上流のフィールドを除去して、正規化されたサマリーをSQLiteに書き込みます。

3. garmin-readonly-mcpはGarminクライアントもセッション情報もインポートしません。正規化されたSQLiteキャッシュのみを読み取り、シンボリックリンク、通常ファイル以外、現在のユーザーが所有していない、またはグループ/その他のユーザーがアクセス可能なキャッシュを拒否します。

デフォルトの状態ディレクトリは次のとおりです：

~/.local/share/garmin-readonly-mcp/
├── tokens/          # Garmin session material, mode 0700/0600
└── cache.sqlite3    # normalized cache, mode 0600

別のルートを使用するには、非機密のGARMIN_READONLY_HOME環境変数を設定してください。状態ディレクトリをリポジトリ内に配置しないでください。

Related MCP server: garmin-mcp-local

データ範囲

キャッシュとMCPが公開するのは以下のみです：

• 1日の総カロリー、アクティブカロリー、BMR/安静時カロリー

• 利用可能な場合の歩数と安静時心拍数

• アクティビティの種類、開始時間、期間、距離、カロリー

• 利用可能な場合の睡眠時間/スコア、Body Battery、夜間HRV/ステータス、トレーニングレディネス

以下は意図的に除外されています：

• Garminプロフィールとソーシャルデータ

• アカウント識別子とアクティビティID

• デバイスの詳細

• GPS座標、ルート、FIT/GPX/TCXファイル

• 体重と体組成

• 生のGarminレスポンス

• アップロード、更新、スケジュール、削除操作

• 汎用的または任意のGarmin APIアクセス

Garminのカロリー値は活動コンテキストであり、食事摂取量を増やす指示ではありません。

要件

• プライベートファイル権限を持つLinuxまたはその他のUnix系環境

• Python 3.12+

• uv

• Garmin Connectアカウント

インストール

git clone https://github.com/alexpomsft/garmin-readonly-mcp.git
cd garmin-readonly-mcp
uv sync --frozen

ローカルで認証

Telegram、チャット、シェル履歴、共有画面ではなく、プライベートなローカルターミナルでこれを実行してください：

uv run garmin-readonly-auth

このコマンドはローカルでメールアドレス、非表示のパスワード、およびGarminが必要とする場合は非表示のMFAを尋ねます。パスワードではなく、再利用可能なセッション情報を保存します。

同期

デフォルトでは今日と昨日を同期します：

uv run garmin-readonly-sync

限定された過去の期間を要求することもできます：

uv run garmin-readonly-sync --end-date 2026-08-18 --days 14

--daysは1から31の間で指定する必要があります。プロバイダエラーは固定の公開メッセージに置き換えられるため、生のGarminレスポンスや認証詳細は表示されません。

MCPサーバーの実行

少なくとも1回の同期が成功した後：

uv run garmin-readonly-mcp

stdioサーバーは以下を正確に公開します：

• get_daily_activity(date: YYYY-MM-DD)

• get_recent_activities(days: 1..31 = 7)

• get_recovery_summary(date: YYYY-MM-DD)

ツールスキーマは宣言されていない引数を拒否します。

Hermes Agentへの接続

config.yamlを手動で編集するのではなく、HermesのMCPコマンドを使用してください：

hermes mcp add garmin-readonly \
  --command /absolute/path/to/garmin-readonly-mcp/.venv/bin/garmin-readonly-mcp
hermes mcp test garmin-readonly

サーバーを追加した後、Hermesを再起動してツールを認識させてください。認証情報やセッショントークンのパスはMCP設定に渡されません。プライベートなデフォルトの状態ルートを使用します。GARMIN_READONLY_HOMEをカスタマイズする場合は、hermes mcp add ... --env GARMIN_READONLY_HOME=/private/pathでその非機密設定のみを渡してください。

開発と検証

uv sync --frozen
uv run pytest --cov=garmin_readonly_mcp --cov-report=term-missing
uv run ruff check .
uv run mypy src tests
uv run pip-audit

実装は最初に失敗するテストを書いて開発されました。CIは同じテスト、リンター、型チェック、依存関係監査のゲートを実行します。

制限事項

• Garmin Connectエンドポイントはリバースエンジニアリングされたものであり、予告なく変更される可能性があります。

• Garminは自動化クライアントに対してレート制限、チャレンジ、ロックをかける場合があります。

• 一部のリカバリフィールドは一部のデバイスや日付で利用できず、nullを返します。

• ローカルキャッシュはスナップショットです。より新しいデータが必要な場合は、garmin-readonly-syncを別途スケジュールしてください。

• このプロジェクトはカロリー目標を自動的に変更したり、医学的アドバイスを提供したりしません。

認証情報の取り扱いと脆弱性の報告については、SECURITY.mdを参照してください。