coach-mcp

coach-mcp

こだわりのある AI トレーニングコーチを MCP サーバーとして提供します。Garmin Connect から実際のデータを取得し、確かな根拠に基づいて指示します。科学に基づく負荷管理（ACWR）、コードで強制されるケガの制限（LLM が何を言っても、現在有効なケガの制限に反するプランはサーバーが拒否します）、そして継続的なコーチングメモリーにより、判断やその根拠、適応パターンが会話をまたいで引き継がれます。意欲が対応能力を上回っているときは、「いいえ」と伝えます。

健康データと認証情報はすべてお使いのマシンに保存されます。詳しくはセキュリティとプライバシーをご覧ください。

クイックスタート

Python 3.12 以降、無料の Garmin Connect アカウント、MCP クライアント（Claude Code、Claude Desktop、または Cursor）が必要です。

オプション A：uvx（推奨）

インストールは不要です。MCP クライアントが必要に応じてサーバーを起動します。

uvx garmin-coach-mcp

お使いの MCP クライアントを接続するに進み、コマンドとして uvx を使用してください。

オプション B：ソースから

git clone https://github.com/snoozelieb/coach-mcp.git
cd coach-mcp

python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

pip install -r requirements.txt
cp .env.example .env   # then edit: GARMIN_EMAIL, GARMIN_PASSWORD
python server.py

お使いの MCP クライアントを接続する

サーバーには、GARMIN_EMAIL と GARMIN_PASSWORD の 2 つの環境変数が必要です。任意の環境変数として、COACH_DATA_DIR（コーチングデータの保存場所）があります。COACH_TOKEN_DIR、COACH_TRANSPORT、COACH_CODE_MODE については、セキュリティとプライバシーおよび詳細設定をご覧ください。ソースをチェックアウトしている場合は、.env ファイルも使用できます。

ターミナルからサーバーやヘルパーを実行するには、まずそのシェルで 2 つの変数を設定してください。PowerShell と bash では引用符の使い方が異なります。

$env:GARMIN_EMAIL = "[email protected]"
$env:GARMIN_PASSWORD = "your-password"

export [email protected] GARMIN_PASSWORD=your-password

Claude Code

claude mcp add coach-mcp \
  --env [email protected] \
  --env GARMIN_PASSWORD=your_garmin_password \
  -- uvx garmin-coach-mcp

または .mcp.json を使用します（Claude Code はシェル環境から ${VAR} を展開するため、コミットしたファイルに秘密情報は含まれません）。

{
  "mcpServers": {
    "coach-mcp": {
      "command": "uvx",
      "args": ["garmin-coach-mcp"],
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "GARMIN_PASSWORD": "${GARMIN_PASSWORD}",
        "COACH_DATA_DIR": "/path/to/your/coach-data"
      }
    }
  }
}

ソースから実行する場合：claude mcp add coach-mcp -- python /full/path/to/coach-mcp/server.py

Claude Desktop

claude_desktop_config.json（設定 → 開発者 → 設定を編集）で設定します。

{
  "mcpServers": {
    "coach-mcp": {
      "command": "uvx",
      "args": ["garmin-coach-mcp"],
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "GARMIN_PASSWORD": "your_garmin_password",
        "COACH_DATA_DIR": "/path/to/your/coach-data"
      }
    }
  }
}

Cursor

.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）で設定します。

{
  "mcpServers": {
    "coach-mcp": {
      "command": "uvx",
      "args": ["garmin-coach-mcp"],
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "GARMIN_PASSWORD": "your_garmin_password",
        "COACH_DATA_DIR": "/path/to/your/coach-data"
      }
    }
  }
}

uvx ではなく pip install garmin-coach-mcp でインストールした場合は、上記いずれのブロックでも引数を指定せず、"command": "garmin-coach-mcp" を使用してください。

初回実行

1. プロフィールを作成します。 対話型ウィザードを実行します（インストール済みの場合はコンソールスクリプトを使用できます。ソースをチェックアウトしている場合はスクリプトを実行します）。

   garmin-coach-setup                 # pip / uvx install
   python scripts/setup_wizard.py     # source checkout
   

   プロフィールが作成されるまでは、サーバーはセットアップモードで動作します。プラン、プログラム、プッシュの書き込みに対して setup_required と応答し、検索したデータディレクトリを示します。

   データディレクトリに、アスリートプロフィール、トレーニング設定、空のプラン／メモリーファイルが作成されます。代わりに、必須の 2 つのファイルを手動で作成し、残りは会話を通じてコーチに設定してもらうこともできます。

   echo '{"personal":{"name":null},"injury_history":[],"life_constraints":{}}' > data/athlete.json
   echo '{"events":[],"current_block":{"phase":"base"}}' > data/training_config.json
   

2. Garmin のベースラインを取得します。 MCP クライアントで、次のように伝えます。

   「refresh_athlete_baseline を実行して、トレーニングの設定をしてください。」

   コーチは Garmin から氏名、体重、年齢、心拍数データ、トレーニング能力を取得し、その後、目標、制約、ケガの履歴、レース予定についてのオンボーディング会話を開始します。

3. Garmin の MFA／セッションの期限切れ。 Garmin のログイン情報はトークンとしてキャッシュされます。ツールが AUTH_REQUIRED を返すようになった場合は、次の手順で復旧してください。

   garmin-coach-login                 # pip / uvx install
   python scripts/garmin_login.py     # source checkout
   

   認証情報を使って新たにログインし、Garmin から求められた場合は MFA コードの入力を促して、新しいトークンを保存します。その後、MCP サーバーを再起動してください。

仕組み

1. まずスナップショットを取得 — コーチングの会話はすべて get_coaching_snapshot() から始まります。現在の時間のコンテキスト、7日間の週グリッド（休養日を明示）、フィットネス指標、計画の遵守状況、未解決の異常、ケガ、睡眠の判定が含まれます。
2. 処方の前に負荷の階層を確認 — 全体の ACWR（ケガの判定基準、理想範囲は0.8～1.3）、次にスポーツ別 ACWR（急増の検出）、その後スポーツ別 CTL（レースへの準備状況）の順に確認します。
3. 厳格な判定基準はコードで適用し、感覚には頼りません — update_weekly_plan と push_plan_to_garmin は、活動制限が設定されたケガに違反するセッションを拒否します。また、休養日以外のすべてのセッションには purpose が必要で、指定がない場合は保存されません。複数週のプログラム（training_program）は、開始時の能力が実際の履歴と矛盾する場合、拒否されます。
4. 実際に行ったことに基づきます — 処方はテンプレートの数値ではなく、直近のセッションから確認できるスポーツごとの能力を基準にします。週間計画がその履歴を超える場合は、grounding_warnings が返されます。
5. 記憶を活用した問いかけ — 計画と実績の異常（セッションの未実施、種目の不一致、休養日の活動）は、ライフサイクル（未解決 → 質問済み → 解決済み）とともに一度だけ登録されます。コーチは黙って推測するのではなく、何が起きたのかを尋ねます。
6. すべてを保持 — 判断、承認、適応パターン、シーズンのライフサイクル（レースの振り返り、フェーズの移行）はローカルの JSON に保存され、セッションをまたいで引き継がれます。

MCP の機能

51個のツールがあります。直接呼び出す必要はなく、コーチが会話中に使用します。

カテゴリ	ツール
コーチングの中核	get_coaching_snapshot（標準、セクション別）、get_compliance_report、get_coaching_score
計画	get_weekly_plan、update_weekly_plan、push_plan_to_garmin、training_program（action=get/set。複数週のプログラム、能力を基準とし、ケガの判定基準を適用）、get_week_constraints、get_weekly_prescription、get_periodization_status、update_phase
Garmin データ	query_metrics（kind=fitness/sport_history/intensity/daily/readiness/personal_records）、get_activities_range
アスリート	get_athlete、update_athlete、set_ftp、set_threshold_pace、analyze_ftp_test、refresh_athlete_baseline、refresh_fitness_history、backfill_history、get_onboarding_guide
方法論	get_methodology、update_methodology
レース	races（action=list/add/update/research）、remove_race
筋力トレーニング	sync_strength_session、get_strength_baseline、approve_progression、set_exercise_preference、generate_strength_workout、add_exercise
ケガ	diagnose_injury、research_injury、update_injury_status
調査	research_exercise、list_exercises、research_sport
メモリ	log_coaching_decision、get_active_decisions、update_decision_status、record_athlete_response、get_response_patterns、resolve_anomaly
承認	propose_coaching_action、list_pending_approvals、approve_proposal、reject_proposal
対話機能	generate_smart_brief、interactive_check_in

各ツールには MCP アノテーション（読み取り専用／破壊的／冪等／オープンワールド）が付与され、テストによって適用されます。

6つのプロンプト：weekly_planning、morning_brief、injury_assessment、 week_review、onboarding、race_program。

6つのリソース：coach://athlete/profile、coach://plan/current、 coach://config/training、coach://coaching/decisions、coach://context/now、 coach://coaching/doctrine（詳細なコーチング指針）。

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

すべてのデータはお使いのマシン内にとどまります。

• 認証情報：GARMIN_EMAIL／GARMIN_PASSWORD は、MCP クライアントの設定またはローカルの .env に保存されます。Garmin OAuth トークンはローカルのトークンストアにキャッシュされます（ソースチェックアウトでは .garth/、インストール済みのコピーではユーザーごとの garmin-tokens ディレクトリ。COACH_TOKEN_DIR で上書きできます）。
• 健康データ：すべてのコーチングデータ（プロフィール、プラン、フィットネス履歴、睡眠、コーチングメモリー）は、データディレクトリ内のローカル JSON です。バックエンド、テレメトリー、分析機能はありません。
• マシンの外部に送信されるもの：Garmin 独自の API へのリクエスト（認証情報／トークン。Garmin にのみ送信されます）、会話の一部として MCP クライアントが LLM に送信する内容、コーチがレース、けが、運動について調べる際に任意で取得する公開ウェブページです。それ以外は何もありません。更新確認のために PyPI にアクセスする FastMCP の起動バナーは無効になっています。
• 設計上、1 つのデータディレクトリにつきアスリートは 1 人です。複数のアスリートを扱う場合は、別々の COACH_DATA_DIR を指定して、個別のサーバーインスタンスを起動してください。

詳細および問題の報告方法については、SECURITY.md をご覧ください。

データディレクトリ

解決順序は、COACH_DATA_DIR 環境変数 → ソースチェックアウト内の data/ → ユーザーごとのデータディレクトリ（インストール済みパッケージの初回実行時に作成）です。パッケージに同梱されるファイルは methodology.json（安全規則、レーステンプレート、ペルソナ）のみです。個人に関するデータはすべてローカルで作成され、コミットされることはありません。

詳細

# HTTP transport (streamable-http) instead of stdio
COACH_TRANSPORT=streamable-http FASTMCP_PORT=8000 garmin-coach-mcp

# Code Mode (search/execute meta-tools instead of 50 individual tools)
pip install fastmcp[code-mode]
COACH_CODE_MODE=1 garmin-coach-mcp

# Standalone morning audit
python scripts/daily_loop.py          # ingest + audit yesterday + template brief (exit 1 if unverified)

# Tests (1,546 tests; clean checkouts use committed sanitized fixtures)
pip install -r requirements-dev.txt
python -m pytest -q

アーキテクチャ

coach/server.py は coach/ パッケージのツール（11 個のツールモジュール、純粋なパーサー、型付きの pydantic ストレージレイヤー、CTL／ATL／ACWR のフィットネス計算、トークン優先認証を備えた Garmin クライアント、構造化ワークアウトをウォッチに送信するワークアウトビルダー）を登録します。このプロジェクトは、認証の再構築、スキーマレイヤー、厳格なゲート、セクション分割されたスナップショット、パッケージ化という 5 段階のモダナイゼーションを経てきました。その経緯と理由の全容は、docs/UPGRADE_ROADMAP.md に記載されています。開発規約については CLAUDE.md をご覧ください。

謝辞

Garmin Connect へのすべてのアクセス（ログイン、MFA、トークン処理、アクティビティと健康データ、ワークアウトのアップロード）は、Ron Klinkien（@cyberjunky）およびコントリビューターによる python-garminconnect（MIT）を利用しています。これがなければ coach-mcp は存在し得ません。

ライセンス

MIT