Garmin MCP

プロジェクト状態 (2026-08-23): 個人用トンネル実装。ローカルスモークテストは合格。 友人アクセスや公開 MCP イングレスを有効にしないでください。実際の Garmin 認証情報は、 オペレーターが公開する HTTPS link-web トンネルを明示的に承認し、ライブテスト チェックリスト PERSONAL_TUNNEL_RUNBOOK.md を完了するまでブロックされたままです。

マルチユーザー対応の読み取り専用 MCP リソースサーバーで、 cyberjungky/python-garminconnect をラップします。 ツールの引数としてユーザー ID を受け取らずに、認証済み Garmin データを公開します。

セキュリティモデル

以下の箇条書きは、当初の設計意図を説明しています。これらは現在の実装ではまだすべてが証明されているわけでは ありません。既知のギャップと受け入れテストは、 DESIGN_DRAFT.md に記録されています。

• MCP ベアラートークンは Garmin 認証とは別に検証されます。本番 OIDC では、 署名、発行者、オーディエンス、有効期限、必要なスコープを検証し、検証済みの sub クレームを使用します。

• Garmin のメールアドレス、パスワード、MFA コードは、リクエスト中のみに存在します。それらは保存もログ記録も されません。Uvicorn のアクセスログは無効です。

• 保存されるのは python-garminconnect のシリアル化されたセッション JSON のみで、AES-256-GCM で暗号化され、 所有者としての符号に対して認証されるため、暗号文をユーザー間で移動することはできません。

• MFA クライアントはプロセスローカルで、単回使用、所有者バインド、5分で失効します。

• 接続 URL は署名済みのワンタイム状態をフラグメントに配置します。外部 JavaScript がフラグメントをクリアし、 状態を POST ボディに移動して、HTTP とプロキシのアクセスログから除外します。

• 切断すると、ローカルの暗号化トークンが削除されます。これは Garmin が発行済みのトークンを取り消すものでは ありません。不正利用が疑われる場合は、Garmin アカウントのセキュリティ設定でアクセスを取り消してください。

Related MCP server: garmin-mcp

個人用 ChatGPT トンネルモード

個人設定では、意図的に2つのリスナーを使用します:

• SERVER_ROLE=mcp — ループバックポート 3000 で動作します。OpenAI がこのポートに到達できるのは Secure MCP Tunnel のみです。

• SERVER_ROLE=link-web — ループバックポート 3001 で動作します。MCP エンドポイントを公開せずに、 別の HTTPS トンネルがこのリスナーのみを公開し、端末から Garmin 認証情報を入力できるようにします。

AUTH_MODE=tunnel は設定済みの TUNNEL_PRINCIPAL_ID を1つ持ちます。これはマルチユーザーモードではありません。トンネルは認証境界であり、コンテナ分離が明示的に有効でない場合、 サーバーは複合モードや非ループバックバインドを拒否します。構成のエンドツーエンドの手順は、 PERSONAL_TUNNEL_RUNBOOK.md を参照してください。

ローカルでの実行

Python 3.12+、PostgreSQL 17、uv が必要です。

cp .env.example .env
# Fill secrets, then for local-only bearer authentication set AUTH_MODE=development.
uv sync --all-extras
psql "$DATABASE_URL" -f migrations/001_initial.sql
uv run garmin-mcp

または、.env を作成した後で docker compose up --build を実行します。Compose は両ポートを 127.0.0.1 にのみ公開し、PostgreSQL は公開しません。MCP ポートは /mcp、ヘルスチェックポートは /healthz です。開発モードでは、ベアラー値そのものがローカルユーザー ID です。開発モードを ループバック以外に公開しないでください。

MCP ツール

• *get_connection_status

• *connect_garmin — 10分間の、一度限りのブラウザ URL を返します

• *get_profile

• *disconnect_garmin

現在の Garmin データツールは読み取り専用です。disconnect_garmin は、保存されたセッションを削除して、 ローカルの接続状態のみを変更します。アカウント認証はブラウザのリンクページでのみ入力され、 MCP ツールの引数として提供されることはありません。ヘルス/アクティビティツールはまだ実装されていません。

検証

uv run ruff check .
uv run mypy src
uv run pytest
uv build
uv run pip-audit

実際の Garmin 認証情報を CI に入れないでください。将来のライブテストでは、専用アカウントと 明示的な統合テストマーカーを使用する必要があります。