TrainBud

TrainBud

トレーニングデータに話しかけましょう。

TrainBud は、Garmin Connect のフィットネスデータを Claude、Cursor、その他の AI アシスタントに接続するオープンソースの MCP サーバーです。ワークアウト、睡眠、心拍数、回復、体組成について、自然な英語で質問できます。データはプライベートに、ご自身のマシン上で管理できます。

免責事項： TrainBud は非公式のコミュニティプロジェクトです。Garmin Ltd. との提携、同社による推奨、または同社の後援を受けていません。Garmin Connect は Garmin Ltd. の商標です。

試してみる

MCP クライアントに接続したら、次のように質問してみてください。

• 「今日は何をしましたか？」
• 「今週の睡眠はどうですか？」
• 「明日はハードなトレーニングをしても大丈夫なくらい回復していますか？」
• 「安静時心拍数は下がっていますか？」

アイデアについては、examples/prompts.md をご覧ください。

TrainBud を選ぶ理由

• プライベート — 認証情報はローカルの .env に保存され、データはお使いのマシンにキャッシュされます
• ローカル優先 — SQLite キャッシュと、.trainbud/ に保存されるセッショントークンを使用します
• どこでも使えます — Windows、macOS、Linux（Node.js 22.12 以降）
• あらゆる MCP クライアントに対応 — Claude Desktop、Cursor、その他の stdio 対応クライアント
• スマートなデータ取得 — API 呼び出しをまとめて行い、セッションの期限切れ時には自動で再認証します

クイックスタート

npx trainbud setup

セットアップウィザードで、認証情報の設定、認証、Cursor または Claude Desktop への接続を順に行えます。MCP 設定ファイルを編集する必要はありません。その後、MCP クライアントを再起動して、今日何をしたか尋ねてみてください。

毎回 npx を入力せずに trainbud を PATH から実行するには、次のようにします。

npm install -g trainbud
trainbud setup

Node 22.12 以降が必要です。詳しい手順は QUICKSTART.md をご覧ください。

git clone https://github.com/Zsadigzade/trainbud.git
cd trainbud
npm install
npm run build
npm link          # puts `trainbud` on your PATH; undo with `npm unlink -g trainbud`
trainbud setup

Claude Code プラグイン（推奨）

Claude Code プラグインとしてインストールすると、スキルと MCP サーバーを一度に導入できます。

/plugin marketplace add Zsadigzade/trainbud
/plugin install trainbud@trainbud

認証情報を設定してから、Claude Code を再起動してください。

export GARMIN_EMAIL="[email protected]"
export GARMIN_PASSWORD="yourpassword"

プラグインファイルは plugin/ にあります。詳細は plugin/README.md をご覧ください。

Claude Code スキル（リポジトリ内）

このリポジトリには、プラグインをインストールせずに開発するためのプロジェクトスキルも .claude/skills/ に含まれています。

Claude Code でリポジトリを開くと（このディレクトリで claude を実行）、スキルが自動的に読み込まれます。

プラグインを使わず、すべてのプロジェクトでスキルを使うには、スキルを ~/.claude/skills/ にコピーしてください。

セットアップ後、MCP クライアントを再起動し、「今日は何をしましたか？」と尋ねて /trainbud を試してみてください。

ダッシュボード

trainbud serve を実行すると、/dashboard にダッシュボードが表示されます。ペアリングの際、コードを承認するときはスマートフォンを持って時計のそばにいるため、スマートフォンでの利用を優先して設計されています。

ローカルの履歴ストアからデータを読み込むため、すぐに表示され、Connect セッションの有効期限が切れていても機能します。今日のデータを自身の基準値と比較した際の注目点、今週と先週の比較、安静時心拍数と睡眠の自身の30日間の中央値との比較を確認できます。グラフの線が途切れている箇所は、その日の測定値がないことを示しており、ゼロではありません。

また、TrainBud が誰について話すのかを設定する場所でもあります。

利用状況。 TrainBud はご自身の AI プロバイダーのキーを使うため、すべての質問と毎日のインサイトの料金はご自身に請求されます。ダッシュボードには、呼び出しごとのトークン数と料金、当月の累計、30日間のグラフが表示されます。このビルドで料金が公開されていないモデルは、ゼロではなく料金を不明として記録します。料金ゼロの呼び出しがあると、上限が決して適用されなくなるためです。

このページの情報がマシンの外部に送信されることはありません。情報を送信するエンドポイントもありません。

Garmin ウォッチウィジェット（Connect IQ）

ciq/ の Connect IQ ウィジェットを使って、Garmin ウォッチで回復、睡眠、アクティビティ、ストレス、VO2 max を確認できます。

必要なもの： trainbud serve の実行と HTTPS トンネル（Web AI と同じセットアップ）。

1. サーバーとトンネルを起動します。

   trainbud serve
   cloudflared tunnel --url http://127.0.0.1:3847
   

2. ウィジェットをビルドしてサイドロードします。ciq/README.md を参照してください。
3. Garmin Connect Mobile → Connect IQ → TrainBud の設定を開き、次の項目を設定します。
   • Server URL — トンネルの URL（例：https://abc.trycloudflare.com）
4. ウォッチでウィジェットを開くと、ペアリングコードが表示されます。ダッシュボード（/dashboard?token=YOUR_API_KEY）で承認してセットアップを完了します。ダッシュボードはそのトークンをセッション Cookie に置き換えて URL から削除するため、その後はアドレスバーを安全にスクリーンショットに撮れます。

グランス画面には、直近のキャッシュ済みサマリーから回復と睡眠、または数文字で表した最も重要な検出結果（「RHR +4 bpm」など）が表示されます。ネットワークを待たずに描画され、2時間以上古くなるとその旨が表示されます。ウィジェットを開き、タップまたはスワイプすると、ダッシュボードで有効にしたカードを順に切り替えられます。ウォッチから呼び出すのは GET /api/watch です。これは完全な MCP プロトコルではなく、簡潔な JSON サマリーを返します。

Today カードでは、START（またはタップ）を押すと、検出結果の詳細と該当するルールが表示されます。たとえば「直近3日間はそれぞれ、28日間の中央値である48 bpmを3 bpm以上、標準偏差2つ分上回っています」といった内容です。そこから3日間ミュートできます（POST /api/mute）。Sleep カードには、昨夜の睡眠で自身の通常の夜と比べて変化した内容が表示されます（「Deep 40m (1h24m)」など）。ウィジェットの容量が64 KBの Forerunner 55 では、残りの機能を収めるため、この2つのカードはビルドから除外されます。

検出ルール

すべての検出結果は、確認や変更が可能なルールに基づいています。ダッシュボードの検出ルールセクションでは、各種しきい値を設定できます。安静時心拍数の対象日数・bpm・標準偏差、睡眠負債の時間数、HRV の低下、トレーニング負荷の比率、「複数のシグナルが同時に発生」（安静時心拍数の上昇、HRV の低下、睡眠ストレスの上昇が同時に起きた場合）などが含まれます。どの設定を選んでも、毎日または一日も検出されない状態にならないよう、値には範囲が設定されています。すべての画面で、検出結果が発生したルールと、そのとき適用されていた数値を確認できます。

音声（/voice）

スマートフォンのボタンを長押しして、声に出して質問すると、回答が読み上げられます。 最初に一度だけ https://YOUR-HOST/voice?token=YOUR_API_KEY を開くと、キーが Cookie に交換され、 URL がすっきりした状態にリダイレクトされます。

• Android / Chrome — 音声認識はブラウザー内で行われます。無料で、キーは不要です。
• iPhone / Safari — 音声を録音し、サーバー側で Groq を使って文字起こしします （whisper-large-v3-turbo、音声 1 時間あたり約 $0.04）。ダッシュボードでキーを追加してください。
• 両方 — 回答が読み上げられます。また、今日の予定を読み上げて / 今日の気づきを読み上げて は、すでにあるデータをもとにコードで作成され、費用は一切かかりません。生成されるものではありません。

時計の機能ではなく、時計の機能にすることもできません。Connect IQ はウィジェットに マイクやスピーカーを公開していません。また、ハンズフリーでもありません。モバイルブラウザーではタブが バックグラウンドになるとマイクが一時停止するため、ページを表示したままスマートフォンを起動しておく必要があります。

詳細：docs/VOICE.md

常時稼働（/voice と時計を、ターミナルを見守らずに使う）

ターミナルで実行する trainbud serve は、ターミナルを閉じるまでしか動作しません。再起動後にサーバーと トンネルを自動で再開するには、次のようにします。

.\scripts\install-always-on.ps1 -Hostname trainbud.example.com

これにより、サーバーのスケジュールタスクと、5 分ごとに両方を確認する監視プロセスが登録されます。 応答するトンネルが、応答するサーバーとは限らないためです。背後に何もないトンネルは、ステータスコード 200 のまま 独自のエラーページを返すため、リンクは正常に見えても、時計には HTTP -400 と表示されます。systemd、launchd、Docker Compose の設定例はガイドにあります。

詳細（Cloudflare のネームドトンネルを含む）：docs/ALWAYS-ON.md

Claude Desktop に接続する

claude_desktop_config.json を編集します。

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "trainbud": {
      "command": "node",
      "args": ["C:/path/to/trainbud/dist/index.js", "start"],
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "GARMIN_PASSWORD": "yourpassword"
      }
    }
  }
}

trainbud が PATH 上にある場合（npm install -g trainbud を実行するか、クローンから npm link を実行します）は、 パスではなくコマンドをクライアントに指定します。

{
  "mcpServers": {
    "trainbud": {
      "command": "trainbud",
      "args": ["start"]
    }
  }
}

MCP クライアントを再起動して、質問を始めてください。

ツール

CLI

trainbud setup          # Interactive first-time setup (recommended)
trainbud serve          # Remote HTTP MCP for web AI (claude.ai, ChatGPT)
trainbud check          # Live diagnostics against all tools
trainbud doctor         # What the watch would see: public URL, AI key, history depth
trainbud backfill       # Pull Garmin history into the local store (resumable)
trainbud findings       # What stands out against your own baselines, and the rule each fired on
trainbud rederive       # Rebuild sleep measurements (deep, REM, awakenings) from the local archive — no Garmin requests
trainbud start          # Start the MCP server (stdio)
trainbud auth           # Force re-authentication
trainbud cache clear    # Clear cached data
trainbud devices        # List paired watches
trainbud devices revoke <id>   # Take one watch's access away
trainbud rotate status  # Which secrets are set, and whether their two homes agree
trainbud rotate api-key # Replace TRAINBUD_API_KEY, and say what that invalidates
trainbud rotate ai-key  # Replace the AI key in BOTH .env and app.db
trainbud status         # Show session and cache status
trainbud --version      # Print version

rotate ai-key は意図的に両方の保存先へ書き込みます。AI キーは .env と app.db の両方に保存されます。実際に読み込まれるのはデータベース内のコピーです。ファイルだけを手動で編集すると、 キーをローテーションしても反映されません。

これらのコマンドはすべて、インストールせずに npx trainbud <command> としても実行できます。

トラブルシューティング：trainbud: command not found

npx trainbud <command> を使うか、npm install -g trainbud でグローバルにインストールしてください。クローンから実行する場合は、 リポジトリのルートで一度 npm link を実行するか、ビルド後（npm run build）、node dist/index.js doctor で ビルド済みのエントリーポイントを直接呼び出してください。

設定

セキュリティとプライバシー

• 認証情報はローカルの .env ファイル内にのみ保存され、第三者に送信されることはありません
• .trainbud/session.json 内のセッショントークンは、パスワードと同様に機密性の高い情報です
• ツールのエラーは、AI クライアントに渡る前にサニタイズされます
• 非公式の garmin-connect npm パッケージを使用しています（Garmin のエンタープライズ OAuth API は使用していません）
• MFA は基盤となるライブラリでサポートされていません。MFA を無効にするか、アプリ固有のパスワードを使用してください
• デフォルトではサーバーは 127.0.0.1 にバインドされます。トンネルを接続しない限りインターネットからアクセスできず、/health 以外のすべてのルートには API キーが必要です
• ダッシュボードは /dashboard?token=… でキーを一度だけ受け取り、それを HttpOnly セッション Cookie と交換して、URL をクリーンな状態にリダイレクトします。そのため、キーがアドレスバー、履歴、スクリーンショットに残ることはありません
• **ペアリング済みのウォッチは、そのウォッチに限定されたトークンを保持します。**ペアリング時に発行され、サーバーには SHA-256 ハッシュとして保存されます。trainbud devices で一覧表示でき、trainbud devices revoke <id> で取り消せます。ダッシュボード、/mcp、その他のウォッチからログアウトする必要はありません。0.5.2 より前にペアリングしたウォッチは API キー自体を保持しているため、スコープ付きトークンに切り替えるには再ペアリングしてください
• 401 を含むすべてのレスポンスには、Content-Security-Policy、X-Content-Type-Options、X-Frame-Options、Referrer-Policy が含まれます。HSTS は実際に TLS 経由で届いたリクエストにのみ送信されるため、ループバックのダッシュボードには引き続きアクセスできます

TrainBud ではないもの

• **ホステッドサービスではありません。**TrainBud アカウントも TrainBud サーバーもありません。ご自身のマシンで、ご自身の Garmin 認証情報を使って実行します
• **Garmin の公式連携ではありません。**Connect の Web API に対して非公式ライブラリを使用します。Garmin は予告なく API を変更する可能性があり、実際に変更しています
• **MFA に対応していません。**Connect アカウントで MFA が有効な場合、ログインできません
• **無料で利用できるわけではありません。**AI 機能はご自身の Anthropic キーを使って実行され、料金はご自身に請求されます。ダッシュボードではすべての呼び出しが計測され、設定した上限を超えると拒否されることがあります

トラブルシューティング

Docker

プッシュのたびに CI でビルドとテストを実施する公開済みイメージです。放置されて使えなくなるようなものではありません。

docker pull ghcr.io/zsadigzade/trainbud:latest

または、このリポジトリから自分でビルドできます。

docker build -t trainbud .

何よりも重要なのは、/app/.trainbud にボリュームをマウントすることです。 ここには SQLite の履歴、キャッシュされたセッション、ログが保存されます。マウントしないと、コンテナを再起動するたびにダウンロード済みの履歴が失われ、最初から再認証が必要になります。

デスクトップクライアントの MCP サーバーとして

デフォルトのエントリーポイントは stdio 経由で MCP と通信するため、クライアントがコンテナを起動します。

{
  "mcpServers": {
    "trainbud": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GARMIN_EMAIL", "-e", "GARMIN_PASSWORD",
        "-v", "trainbud-data:/app/.trainbud",
        "trainbud"
      ]
    }
  }
}

-i は必須です。指定しないとコンテナに標準入力がなく、クライアントには接続後すぐに応答しなくなるサーバーが表示されます。値を指定しない 2 つの -e フラグは、変数を自身の環境から引き継ぐため、認証情報を設定ファイルに記述せずに済みます。

ウォッチアプリまたはウェブクライアント用の HTTP サーバーとして

docker run --rm -p 3847:3847 \
  -e GARMIN_EMAIL -e GARMIN_PASSWORD \
  -e TRAINBUD_API_KEY \
  -e TRAINBUD_HOST=0.0.0.0 \
  -v trainbud-data:/app/.trainbud \
  --entrypoint node trainbud dist/index.js serve

コンテナ内では TRAINBUD_HOST=0.0.0.0 が必要です。サーバーはデフォルトで 127.0.0.1 にバインドします。これはノートパソコンでは適切なデフォルト設定ですが、コンテナの外部からはアクセスできません。

履歴の補完

trainbud setup は対話型で、ターミナルがあることを前提としています。そのため、Docker では一度限りのバックフィルを直接実行してください。

docker run --rm -e GARMIN_EMAIL -e GARMIN_PASSWORD \
  -v trainbud-data:/app/.trainbud \
  --entrypoint node trainbud dist/index.js backfill

同じ方法で doctor、check、devices も実行できます。

開発

npm install
npm run build
npm test          # the whole suite, via the Node test runner
npm run lint
npm run dev       # Start with auto-reload

Node 22 には nvm/fnm で .nvmrc を使用してください。npm run test:coverage は Node 独自のテストランナーを使ってカバレッジをレポートし、npm run test:watch は変更時にテストを再実行します。

アーキテクチャと設計に関するメモについては、CONTRIBUTING.md と docs/VAULT.md（このリポジトリ外の Obsidian vault）を参照してください。

ロードマップ

• VO2 最大値の推移
• ストレスレベル
• トレーニングに関する分析
• ワークアウトの比較
• Docker イメージ — ghcr.io/zsadigzade/trainbud で公開

ライセンス

MIT — LICENSE を参照してください。

Garmin Connect は Garmin Ltd. の商標です。このプロジェクトは Garmin Ltd. と提携していません。