Local Garmin Coach MCP

Private, single-user Garmin coaching tools for Codex/ChatGPT desktop and Claude. The server is local stdio only: no Cloudflare, Render, public URL, account service, or hosting cost.

The runtime is based on etweisberg/garmin-connect-mcp at commit 87d0ea059fb67f1ce65ac05100df74c3c3777c84. It keeps the upstream AGPL-3.0 license and Taxuspt attribution in NOTICE.

前提条件

• Node.js 20以降

• pnpm 10.14.0

• Garmin Connectアカウントと同期済みのウォッチ

Related MCP server: io.github.matisdsp/fartlek

インストール

cd /home/talvak/Desktop/repos/garmin-coach-mcp
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm build
pnpm auth

pnpm auth は専用の可視Chromeプロファイルを開きます。手動でログインし、MFAを完了してから、ターミナルでEnterを押します。ブラウザセッションは ~/.local/share/garmin-coach/browser-profile に保持されます。実行時のCSRF値は、認証された現在のページから読み取られ、永続化も出力もされません。ディレクトリは 0700、ファイルは 0600 で、パスワード保存は無効になり、ユーザー名/パスワードのファイルは作成されません。

Garminのプロファイル書き込み契約の取得

Garminは安定した心拍数プロファイル書き込みAPIを公開していません。サーバーはそれを推測することを拒否します。

pnpm capture:profile-contract

このコマンドはGarminの現在のアプリモデルを読み込み、変更されていない現在のデフォルトゾーンを保存するよう要求し、配信前に結果の PUT をブロックします。ルートと変更されていない正確な本文を検証し、秘匿化されたメソッド/パス/フィールド形状とサポートされているスコープのみを、モード 0600 で ~/.local/state/garmin-coach/profile-write-contract.json に保存します。

Garminの形状が証明できない場合、契約は保存されず、プロファイル書き込みは無効のままになります。

CodexとChatGPT desktopを接続

最初にビルドし、config/codex.toml.example を ~/.codex/config.toml にコピーするか、ChatGPT desktopの設定 > MCPサーバーから同等のサーバーを追加します。Codex CLI、IDE拡張機能、ChatGPT desktopは、同じホスト上のローカルMCP設定を共有します。

この例では次を使用します:

default_tools_approval_mode = "writes"

両方の適用ツールには、明示的な approval_mode = "prompt" もあります。構成後にクライアントを再起動し、/mcp を使用して接続を確認します。

ChatGPT webはこのローカルstdioプロセスを起動できません。Garminへの書き込みにはChatGPT desktop/Codexを使用してください。

Claudeを接続

config/claude.json.example をClaudeのMCP構成にマージするか、次を実行します:

claude mcp add garmin-coach -- /home/talvak/snap/code/current/.local/share/pnpm/node /home/talvak/Desktop/repos/garmin-coach-mcp/dist/index.js

ファイルシステムロックにより、一度に1つのローカルクライアントだけがGarmin Chromiumプロファイルを所有できます。一方のクライアントでサーバーを停止してから、もう一方を使用してください。

ツール

安全なワークフロー

1. get_coaching_snapshot を呼び出し、Garmin Connectと比較します。

2. preview_hr_profile_update を呼び出します。

3. すべてのフィールドを確認し、正確な正規の提案/ハッシュを承認します。

4. apply_hr_profile_update を呼び出し、その後Garminを同期してウォッチのゾーンを目視で確認します。

5. 日曜日から始まる1週間について preview_training_week を呼び出します。

6. その回復エビデンス、完全なペイロード、警告、ハッシュを確認します。

7. 変更されていない正規の提案/ハッシュを指定して apply_training_week を呼び出します。

8. verify_training_week を呼び出し、月曜日/金曜日が 135-149 bpm であることを確認します。金曜日は固定の 12% 指示が表示される必要があります。

9. 両方の適用呼び出しを再試行して、冪等性を証明します。

痛み/怪我または病気がある場合、ワークアウトの書き込みはブロックされます。回復は維持、削減、またはスキップが可能で、負荷を増やすことはありません。ワークアウトが自動的に削除されることはありません。

Garminは、トレッドミルを構造化ワークアウトのスポーツとしてではなく、ランニングの下のウォッチアクティビティとして公開します。したがって、金曜日は Incline Walk 12% という名前のランニング互換ワークアウトです。ウォッチのトレッドミルアクティビティから開始してください。その 12% の傾斜キューと 135-149 bpm のターゲットは明示されたままです。

承認済み心拍数プロファイル

これらの値は暫定的なものです: 年齢27歳、安静時心拍数55、推定最大心拍数189、手動LTHR 181。自動検出フラグは保持されます。将来の変更には、再度のプレビューと承認が必要です。

検証

通常のテストはオフラインで、Garminを呼び出すことはありません:

pnpm test
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build
git diff --check

動作については spec.md を、信頼境界については docs/architecture.md を参照してください。

ライセンス

AGPL-3.0。 LICENSE と NOTICE を参照してください。