whoop-mcp について
whoop-mcpは、WHOOP v2のフィットネスデータをMCPクライアントに提供するローカルの読み取り専用MCPサーバーです。直接OAuth認証とローカルSQLiteキャッシュを使い、記録の照会、同期、エクスポートに対応します。
主な機能
- 01WHOOPのプロフィールとフィットネス記録を読み取る
- 02データをローカルのSQLiteにキャッシュ
- 03記録をオンデマンドまたは増分同期
- 04MCPリソースからキャッシュデータを参照
- 05CSV、JSONL、Parquet形式で記録をエクスポート
活用シーン
- 01毎日の睡眠、回復、ワークアウトを確認
- 02APIを呼び出さずにキャッシュ記録を検索
- 03WHOOP記録の更新を追跡
- 04分析用にワークアウトデータをエクスポート
MCP 対応
MCPクライアントにWHOOPデータの読み取り専用ツールと、キャッシュ記録のJSONリソースを提供します。WHOOPに直接認証し、取得データをローカルのSQLiteキャッシュに保存します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
uvx whoop-mcpWHOOP_CLIENT_IDClient ID from your WHOOP developer app (https://developer-dashboard.whoop.com/apps/create).WHOOP_CLIENT_SECRETシークレットClient secret from your WHOOP developer app. Used for OAuth token refresh.WHOOP_REDIRECT_URIOAuth redirect URI. Defaults to http://localhost:8000/callback — only change if you registered a different URI.WHOOP_LOG_LEVELLog level (DEBUG / INFO / WARNING / ERROR). Default INFO.WHOOP_LOG_FILEPath to the rotating log file. Set to empty string to disable file logging. Default ~/.whoop-mcp-server/logs/whoop-mcp.log.WHOOP_LOG_JSONStructured JSON logs (true) vs human-readable (false). Default true.ローカルサーバーにはマシン上の実行環境(Node.js 18 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
WHOOP MCP サーバー
LLM に WHOOP のフィットネスデータへの読み取り専用アクセスを提供する、ローカルの Model Context Protocol(MCP)サーバーです。認証には、ご自身の WHOOP 開発者アプリを使った直接 OAuth を使用します。通信経路にサードパーティのプロキシはありません。すべてのレコードはローカルの SQLite キャッシュ ~/.whoop-mcp-server/whoop.db にミラーリングされ、認証済みのサーバー自身が WHOOP v2 API に行う呼び出しを除き、データがマシンの外に出ることはありません。
現在のバージョン:0.8.5 — CHANGELOG.md をご覧ください。
1.0 以前のステータス。 API の仕様(ツール名、レスポンス形式、エラーコード)は安定しつつありますが、まだ確定していません。dogfooding 期間中は、
0.xのマイナーバージョン更新で破壊的変更が入る可能性があります。パッチバージョンの更新(0.8.x)はバグ修正のみです。実際の利用で 2 週間以上仕様が安定した時点で、1.0.0 をリリースします。この上に構築する場合は、CI でマイナーバージョンを固定してください。
まず試してみたい方へ。 docs/AGENT_INSTALL_PROMPT.md のプロンプトをコピーして、Claude Code / Claude Desktop / Cursor / Windsurf に貼り付けてください。エージェントがインストールを最初から最後まで実行します。
このリポジトリを基に構築する方へ。 AGENTS.md と docs/ARCHITECTURE.md から始めてください。ここには重要な規約と、システム全体を示す 1 ページのマップが記載されています。
目次
- 概要
- インストール(uvx で 1 行)
- エージェントを使ったインストール
- ソースからインストール
- 分析スキル:whoop-insights
- クイックスタート
- ツール一覧
- MCP リソース
- データモデル
- 同期モデル
- イベントフィード
- エクスポート
- サポート対象外
- 更新
- 運用
- セキュリティとプライバシー
- 開発
- このリポジトリを基に構築するエージェント向け
- バージョン管理
概要
WHOOP MCP Server は、stdio 経由で MCP を利用する小規模な Python プロセスです。WHOOP v2 のデータ(プロフィール、身体測定値、サイクル、リカバリー、睡眠、ワークアウト)を、MCP 対応クライアント(主に Claude Desktop と Claude Code)に公開します。サーバーは読み取り専用です。ご自身で登録した OAuth アプリを使って WHOOP に認証するため、トークンがサードパーティのサーバーを経由することはありません。取得した WHOOP のレコードはローカルの SQLite キャッシュ(モード 0o600)に書き込まれるため、以降の読み取りは通信不要で、キャッシュファイルがマシンの外に出ることもありません。
インストール(uvx で 1 行)
# 1. Create a WHOOP developer app (one-time, free, self-serve):
# https://developer-dashboard.whoop.com/apps/create
# Redirect URI: http://localhost:8000/callback
# Scopes: read:profile read:body_measurement read:recovery
# read:cycles read:sleep read:workout offline
# 2. One-shot OAuth — opens browser, catches callback, saves encrypted tokens.
WHOOP_CLIENT_ID="<your client id>" \
WHOOP_CLIENT_SECRET="<your client secret>" \
uvx --from whoop-mcp whoop-mcp-oauth
# 3. Register with Claude Code. The --env flags are required so the
# server can refresh tokens when the 1-hour access token expires.
claude mcp add whoop --scope user \
--env WHOOP_CLIENT_ID="$WHOOP_CLIENT_ID" \
--env WHOOP_CLIENT_SECRET="$WHOOP_CLIENT_SECRET" \
-- uvx --from whoop-mcp whoop-mcp
リポジトリのクローンも、仮想環境も、絶対パスも不要です。uv をまだインストールしていない場合は、一度だけインストールしてください:curl -LsSf https://astral.sh/uv/install.sh | sh(または brew install uv)。
エージェントを使ったインストール
docs/AGENT_INSTALL_PROMPT.md のプロンプトを、MCP 対応エージェント(Claude Code、Claude Desktop、Cursor、Windsurf、Zed、Aider)に貼り付けてください。エージェントがインストールを代行します。
ソースからインストールする(開発用)
git clone https://github.com/AshwanthramKL/whoop-mcp.git
cd whoop-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
.venv/bin/pytest -q # 183 tests, ~6s, all respx-mocked
次に、-- /abs/path/to/whoop-mcp/.venv/bin/python /abs/path/to/whoop-mcp/src/whoop_mcp_server.py を指定して登録します。
Claude Desktop では、同等のエントリーを
~/Library/Application Support/Claude/claude_desktop_config.json(macOS)に追加し、
command が仮想環境の Python を、args が src/whoop_mcp_server.py を指すようにします。
インストール経路を最初から最後までクリーンな環境でスモークテストしたい場合は
(ブラウザーの OAuth フローを除く)、./scripts/fresh_install_check.sh を実行してください。
クイックスタート
サーバーを登録したら、次のプロンプトを試してください。
- キャッシュを同期する。 「過去 30 日間の WHOOP データを同期してください。」
Claude は
sync_whoop()を呼び出し、リソースごとの件数を報告します。 - 特定の日を確認する。 「昨日の WHOOP 日次サマリーを表示してください。」
Claude は
get_whoop_daily_summary(date="YYYY-MM-DD")を呼び出し、 サイクル+リカバリー+主要な睡眠+ワークアウトを結合したレコードを表示します。 - エクスポートする。 「キャッシュされたワークアウトをすべて
~/whoop-workouts.csvにエクスポートしてください。」 Claude はexport_whoop(kind="workouts", format="csv", path="...")を呼び出します。
分析スキル:whoop-insights
このリポジトリに同梱されています:skills/whoop-insights。
インストール(ワンコマンド):
whoop-mcp-install-skills # writes to ~/.claude/skills/
これにより、このリポジトリの main ブランチから最新のスキルを取得し、
Claude Code(および Cursor/Windsurf/Zed)がユーザースコープのスキルとして自動検出する場所に配置します。MCP クライアントのセッションを再起動して、次のように尋ねてください。
「調子はどうですか? whoop-insights スキルを実行してください。」 「週次 WHOOP レポートを作成してください。」 「オーバートレーニングになっていますか?過去 30 日間を確認してください。」
このスキルはキャッシュから過去 30 日間のデータを取得し、個人ベースライン (HRV、リカバリー、睡眠、ストレイン)を計算して、根拠とともに異常を検出します。さらに、 相関関係を 2 つ(睡眠→翌日のリカバリー、ストレイン→翌日のリカバリー)調べ、 必要に応じて Chart.js のビジュアライゼーションを含む、自己完結型の HTML ダッシュボードを生成します。すべての主張には特定の日付と具体的な数値が引用されます — このスキルは、決して情報を捏造しないよう指示されています。
スキル自体を反復開発するリポジトリ内で開発する方は、
whoop-mcp-install-skills --source ./skills を実行すると、GitHub ではなく
ローカルの作業ツリーからインストールできます。
ツールカタログ
17 個のツールがあります。すべての一覧取得ツールは start/end を ISO-8601 形式で受け取り、自動的にページネーションします。
すべての読み取りツールは fresh: bool = False を受け取ります。キャッシュを迂回して WHOOP API にアクセスし、キャッシュにも書き込んで最新のレスポンスを返すには、True を指定してください。エラーは構造化された {"error": {...}} エンベロープで返され、ツールが例外を送出することはありません。
| ツール | 説明 | 主なパラメーター |
|---|---|---|
get_whoop_auth_status | OAuth トークンの状態を報告します。他のツールが AUTH_FAILED を返した場合は、最初に呼び出してください。 | — |
get_whoop_profile | 認証済みユーザーの WHOOP プロフィール(名前、メールアドレス)を返します。 | fresh |
get_whoop_body_measurement | 最新の身体測定値(身長、体重、最大心拍数)を返します。 | fresh |
list_whoop_cycles | 指定期間の生理学的サイクルを返します。 | start、end、limit、fresh |
get_whoop_cycle | 整数 ID で指定した 1 件のサイクルを返します。 | cycle_id、fresh |
get_whoop_cycle_sleep | 指定したサイクルに関連付けられた睡眠記録を返します。 | cycle_id、fresh |
get_whoop_cycle_recovery | 指定したサイクルに関連付けられた回復記録を返します。 | cycle_id、fresh |
list_whoop_recoveries | 指定期間の回復データ(HRV/RHR/回復スコア)を返します。 | start、end、limit、fresh |
list_whoop_sleeps | 指定期間の睡眠アクティビティ(昼寝を含む)を返します。 | start、end、limit、fresh |
get_whoop_sleep | UUID で指定した 1 件の睡眠アクティビティを返します。 | sleep_id、fresh |
list_whoop_workouts | ゾーンごとの継続時間(秒)を含むワークアウトを返します。 | start、end、limit、fresh |
get_whoop_workout | UUID で指定した 1 件のワークアウトを返します。 | workout_id、fresh |
get_whoop_daily_summary | UTC の日付について、サイクル、回復、主要な睡眠、ワークアウトを結合して返します。 | date |
sync_whoop | WHOOP API からキャッシュを更新します。冪等で、デフォルトでは増分同期を行います。 | full、since、resources |
get_whoop_events | キャッシュ済みリソース全体から、時系列順の「新着情報」フィードを返します。 | since、until、resources、limit |
export_whoop | キャッシュ済みレコードを CSV/JSONL/Parquet に出力します。 | kind、format、path、start、end、overwrite |
health_check | 複合ステータス(認証、API、キャッシュ、スキーマ)を返します。例外を送出することはありません。 | live |
エラーコード:AUTH_FAILED、RATE_LIMITED、NOT_FOUND、UPSTREAM_ERROR、
VALIDATION_ERROR、CACHE_ERROR、CACHE_EMPTY、FILE_EXISTS、
EXPORT_ERROR、SYNC_ERROR。
MCP リソース
キャッシュは読み取り専用の MCP リソースとしても公開されるため、クライアントはツールを呼び出さずに日付範囲を参照できます。
| URI | 内容 |
|---|---|
whoop://db/cycles/{start}/{end} | [start, end) 内のキャッシュ済みサイクル(日付は YYYY-MM-DD)。 |
whoop://db/recoveries/{start}/{end} | キャッシュ済みの回復データ。 |
whoop://db/sleeps/{start}/{end} | キャッシュ済みの睡眠データ(昼寝を含む)。 |
whoop://db/workouts/{start}/{end} | キャッシュ済みのワークアウト。 |
whoop://db/profile | 最新のプロフィールスナップショット。 |
whoop://db/body_measurement | 最新の body_measurement スナップショット。 |
whoop://db/sync_runs/{limit} | 直近の同期監査レコード。 |
whoop://db/events/{since} | since 以降のイベントフィード。until は現在時刻です。 |
whoop://db/events/{since}/{until} | 明示的に指定した期間のイベントフィード。 |
すべてのリソースは application/json を返します。不正な入力には、ツールと同じ {"error": {"code","message"}} エンベロープが返されます。
データモデル
レスポンスはフラット化されています。WHOOP の score ラッパーは展開され、ミリ秒は秒(*_seconds、小数点以下 1 桁)に、キロジュールはカロリー(calories、整数に丸め)に変換され、心拍数のキーは avg_hr_bpm/max_hr_bpm に変更されます。睡眠ステージは deep_sleep_seconds、rem_sleep_seconds、light_sleep_seconds、awake_seconds、in_bed_seconds という名前になります。user_id、v1_id、レコードごとの created_at は除外されます。
score_state の規則。 WHOOP のスコアは常に計算されるとは限りません。score_state != "SCORED"(例:PENDING_SCORE、UNSCORABLE)の場合、導出されたスコアフィールドはすべて null となり、呼び出し側が理由を把握できるよう、トップレベルの score_state は保持されます。
リソースごとにフラット化されたレコードが 1 件あります。
// Cycle
{
"id": 123456,
"start": "2026-04-20T04:00:00.000Z",
"end": "2026-04-21T04:00:00.000Z",
"timezone_offset": "+00:00",
"score_state": "SCORED",
"strain": 12.4,
"avg_hr_bpm": 62,
"max_hr_bpm": 168,
"calories": 2810
}
// Recovery
{
"cycle_id": 123456,
"sleep_id": "bb68db7b-...",
"score_state": "SCORED",
"recovery_score": 74,
"resting_heart_rate_bpm": 48,
"hrv_rmssd_ms": 87.3,
"spo2_pct": 97.4,
"skin_temp_c": 33.1,
"user_calibrating": false
}
// Sleep
{
"id": "bb68db7b-...",
"cycle_id": 123456,
"start": "2026-04-20T03:10:00.000Z",
"end": "2026-04-20T10:42:00.000Z",
"nap": false,
"score_state": "SCORED",
"sleep_performance_pct": 88.0,
"in_bed_seconds": 27120.0,
"light_sleep_seconds": 12540.0,
"rem_sleep_seconds": 5280.0,
"deep_sleep_seconds": 6840.0,
"awake_seconds": 1080.0
}
// Workout
{
"id": "a91f...",
"start": "2026-04-20T17:00:00.000Z",
"end": "2026-04-20T17:48:00.000Z",
"sport_name": "Running",
"score_state": "SCORED",
"strain": 9.3,
"avg_hr_bpm": 142,
"max_hr_bpm": 176,
"calories": 511,
"distance_meter": 8030.0,
"zone_durations_seconds": {
"zone_zero": 0.0, "zone_one": 120.0, "zone_two": 900.0,
"zone_three": 1440.0, "zone_four": 420.0, "zone_five": 0.0
}
}
同期モデル
- キャッシュ優先の読み取り。 すべての一覧取得/取得ツールは、デフォルトで SQLite から読み取ります。 ウィンドウが空の場合は、対象を絞って透過的に同期し、再度読み取ります。
fresh=Trueはキャッシュをバイパスして WHOOP API にアクセスし、結果をキャッシュにライトスルーして、ライブレスポンスを返します。- 増分同期では、リソースごとの
MAX(updated_at)をカーソルとして使用します。 新しい DB では、直近 90 日間にフォールバックします。sync_whoop(full=True)はすべてのリソースについて 2010-01-01 以降を取得します(新しいキャッシュでは一度だけ実行してください)。 - 冪等性。 新しい上流データがない状態で
sync_whoopを再実行しても、何も行いません。スナップショットのハッシュによる重複排除(後述)と組み合わせることで、イベントフィードは静かなまま保たれます。 - スナップショットのハッシュによる重複排除。
profileとbody_measurementは単一のスナップショットです。書き込み前に、サーバーは正規化された生ペイロードの SHA-256 を、保存済みの blob と比較します。バイト単位で同一のペイロードではupdated_atが更新されないため、不要なイベントは生成されません。
イベントフィード
get_whoop_events(since, until=None, resources=None, limit=500) は、キャッシュされたすべてのリソースを対象とする時系列フィードです。キャッシュの読み取りのみで、API 呼び出しは行いません。ウィンドウは両端を含みません。
updated_at > since AND updated_at < until。since の境界は厳密なため、返されたカーソルを次の since として渡しても、同じ行が再表示されることはありません。
各イベントはフラットなレコードをラップします。
{"resource": "sleeps",
"id": "bb68db7b-...",
"updated_at": "2026-04-20T14:12:33.123Z",
"record": { "...flat sleep..." }}
レスポンス:
{"status": "success", "count": 17,
"since": "...", "until": "...",
"events": [...],
"next_cursor": null | "<opaque-base64>"}
next_cursor は、最後に返されたイベントの updated_at|resource|id を Base64 でエンコードした不透明な値です。続きの取得には、これを since として渡します。3 つの値すべてを同順位時の下限として使用するため、ページネーションの境界で updated_at が同じイベントが飛ばされることはありません。since に通常の ISO-8601 文字列を指定する方法も引き続き利用できます(M5 との互換性)。
MCP リソースとしても公開されています。上記の MCP リソースの表を参照してください。
エクスポート
export_whoop(kind, format, path, start=None, end=None, overwrite=False)
は、フラット化されたキャッシュ内のレコードをディスクに書き込みます。データレイヤーのみで処理され、API にはアクセスしません。
先に sync_whoop() を実行してください。
kind:cycles|recoveries|sleeps|workouts|all。"all"を指定すると、指定したディレクトリにリソースごとのファイル(cycles.*、recoveries.*、…)を書き込みます。format:csv(RFC 4180、ヘッダーはアルファベット順にソート、ネストされた値は JSON エンコード)、jsonl(1 行につき 1 レコード、キーをソート)、またはparquet(pyarrow、snappy)。overwrite:デフォルトはFalseです。保存先に内容がある場合は、FILE_EXISTSを返します。Trueを指定すると、確認なしで置き換えます。
ウィンドウが空でもファイルは生成されます(ヘッダーのみの CSV/空の JSONL/空の Parquet)。そのため、後続のツールは常に一貫した成果物を取得できます。
サポート対象外
Issue が無駄に作成されないよう、明記しています。
| 要望 | 対応していない理由 |
|---|---|
claude.ai(ウェブアプリ) | このプロジェクトは stdio MCP(ローカルのサブプロセス)として提供しています。claude.ai ではリモート HTTPS MCP が必要です。ホスト型のデプロイでは、シングルユーザー/ローカル限定の脅威モデルも損なわれます。 |
| モバイル版 Claude アプリ | 同じ stdio の制約があるためです。 |
| WHOOP への書き込み(アクティビティの記録、体重の更新など) | 設計上、読み取り専用です。書き込み機能を追加するには、WHOOP の安定した v2 API の範囲外にある、リバースエンジニアリングされたエンドポイントが必要になります。不安定であり、利用規約上のリスクもあります。必要な場合は jd1207/whoop-mcp をご覧ください。 |
| マルチユーザー/共有サーバー | 1 ユーザー、1 つの WHOOP アカウント、1 台のマシンを想定しています。キャッシュと暗号化されたトークンは ~/.whoop-mcp-server/ に保存され、テナントモデルはありません。 |
| WHOOP の開発者アプリあたり 10 人を超えるユーザー | WHOOP の開発者アプリは、アプリレベルの承認を受けるまでユーザー数が 10 人に制限されます。各ユーザーが自分の開発者アプリを作成してください。無料で、自分で手続きできます。 |
| プッシュ通知/Webhook | イベントフィードは、キャッシュからのポーリングによって取得します。先回りしたアラートが必要な場合は、お使いのスケジューラーで sync_whoop と get_whoop_events を cron で実行してください。 |
| Python < 3.10 | コードでは X | Y のユニオン構文を使用しています。古いバージョンの Python では pip install が拒否されます。 |
| Windows 固有のインストールパス | コードは動作しますが、OAuth コールバック(localhost:8000)とパス処理は Windows 上で十分にテストされていません。現在テスト済みの環境は Ubuntu と macOS です。 |
更新
MCP サーバーは自動更新されません。インストールした時点のバージョンに固定されます。 新しいリリースを適用する方法は、インストール方法によって異なります。
| インストール方法 | 更新方法 |
|---|---|
uvx --from whoop-mcp whoop-mcp | uvx --refresh --from whoop-mcp whoop-mcp を実行するか、uv cache clean whoop-mcp を実行してから再度呼び出します |
uvx --from whoop-mcp@latest whoop-mcp | 次回のキャッシュミス時に更新されます(手動操作は不要です) |
pipx install whoop-mcp | pipx upgrade whoop-mcp |
pip install whoop-mcp | pip install --upgrade whoop-mcp |
| Git クローン+venv | git pull && pip install -r requirements.txt |
その後、health_check() を実行してください。その pypi_update_available コンポーネントで、MCP クライアントが現在実行しているバージョンと、新しいバージョンが公開されているかどうかを確認できます。
破壊的変更に関するポリシー:プロジェクトが 0.x の間は、マイナーバージョンの更新(0.8.x → 0.9.0)に破壊的変更が含まれる場合があります。変更は必ず CHANGELOG.md の ### Changed セクションに記載します。パッチバージョンの更新(0.8.3 → 0.8.5)はバグ修正のみです。1.0.0 のリリース後は、破壊的変更にはメジャーバージョンの更新が必要です。変更に対応できない場合は、動作確認済みの 0.x.y に固定してください。
運用
- ログ。 標準エラー出力(常時、構造化 JSON)に加えて、ローテーションされるファイルを
~/.whoop-mcp-server/logs/whoop-mcp.logに出力します(1 ファイルあたり約 1 MB、バックアップ 5 個)。環境変数による上書き:WHOOP_LOG_LEVEL(デフォルトはINFO)、WHOOP_LOG_FILE(パス。空文字列を指定するとファイルハンドラーが無効になります)、WHOOP_LOG_JSON(デフォルトはtrue)。 health_check(live=True)は、5 つのコンポーネントチェック(auth、api_reachable、cache_readable、cache_writable、schema_version)と、全体の判定healthy | degraded | unhealthyを含む辞書を返します。live=Falseの場合はネットワークプローブを省略します。- トークンの更新。 アクセストークンの有効期限が切れるまで 5 分以内になると、リフレッシュトークンが自動的に使用されます。複数の進行中のリクエストが同じ期限切れトークンを検出した場合に、更新が殺到するのを非同期更新ロックで防ぎます。復旧できない状態まで更新に失敗した場合は、
pip installの後にwhoop-mcp-oauthを再実行するか、ソースから.venv/bin/python src/setup_direct_oauth.pyを実行してください。 - レート制限。 クライアントは 429 応答の
Retry-Afterを尊重し、指数バックオフで再試行します。再試行回数の上限に達すると、呼び出しはRATE_LIMITEDとして返されます。ツールが例外を送出することはありません。
セキュリティとプライバシー
すべてローカルで実行されます。OAuth トークンは、キー
~/.whoop-mcp-server/.encryption_key を使用して
~/.whoop-mcp-server/tokens.json に保存時暗号化されます。SQLite キャッシュファイルは
モード 0o600 で作成されます。サードパーティサービスは一切使用しません。外部へのネットワーク
呼び出しは api.prod.whoop.com への直接接続のみです。ログにトークン、
リフレッシュトークン、クライアントシークレット、生の WHOOP レスポンス本文が含まれる
ことはありません。サーバーが読み取り、書き込み、送信、ログに記録する内容の完全な一覧と、
すべてのデータを削除する方法については、PRIVACY.md を参照してください
(rm -rf ~/.whoop-mcp-server)。
開発
# Run the full test suite (183 tests).
.venv/bin/pytest -q
# Re-record fixtures (live calls, requires creds in env).
.venv/bin/python tests/record_fixtures.py
# Fresh-install smoke test (clones current HEAD into a tempdir and
# verifies the install path end-to-end, minus the browser OAuth flow).
bash scripts/fresh_install_check.sh
新しいツールの追加。 実装を src/whoop_mcp_server.py
に @mcp.tool() デコレーターとともに追加します。レスポンスの形が新しい場合は
src/whoop_models.py に Pydantic モデルを、リソースを永続化する場合は
src/whoop_store.py にキャッシュテーブルを追加し、tests/ にテストを追加します。エラーエンベロープ
(_error_payload / _map_error)は維持してください。ツールが例外を送出することはありません。
リリース手順。 src/__version__.py を更新します(唯一の情報源)→
Keep-a-Changelog 形式で CHANGELOG.md に新しいセクションを追加します →
whoop_mcp_server.py の SERVER_VERSION が新しい値を取得していることを確認します(test_version_import
テストで不一致を防止します)→ pyproject.toml の version を更新します → main に
vX.Y.Z のタグを付けます。
このリポジトリを基盤に構築するエージェント向け
まずはこちらを確認してください。
- AGENTS.md — 重要な規約です。ファイル構成、 エラーエンベロープの取り扱い、TDD のサイクル、避けるべきこと、リリース手順が記載されています。 編集を始める前に読んでください。
- docs/ARCHITECTURE.md — 1 ページのシステム マップです。4 層の図、読み取り/書き込み/同期/イベントの経路、不変条件を記載しています。
- docs/AGENT_INSTALL_PROMPT.md — エンドユーザーがインストールを依頼する際にエージェントに渡す、コピーして貼り付けられるプロンプトです。
人間のコントリビューター向けの簡易版は CONTRIBUTING.md を参照してください。
テストスイートは約 6 秒で実行できます(.venv/bin/pytest -q)。すべての HTTP
呼び出しは respx でモックされるため、オフラインで作業を進められます。
バージョン管理
現在のバージョン:0.8.5(src/__version__.py を参照)。セマンティック
バージョニングを採用しています。全履歴は CHANGELOG.md を参照してください。
クレジット
RomanEvstigneev/whoop-mcp-server
(v0.1.x)からフォークしました。v0.2.0 以降、大幅に書き直し、WHOOP の OAuth への直接接続
(サードパーティのプロキシなし)、WHOOP v2 API、Pydantic でフラット化した
レスポンス、増分同期に対応したローカル SQLite キャッシュ、キャッシュ優先の
読み取り、イベントフィード、エクスポート(CSV/JSONL/Parquet)、health_check
ツール、構造化 JSON ログ、190 件以上のテスト(0.8.5 時点で 190 件)を導入しました。MIT ライセンスです。両方の著作権表示については
LICENSE を参照してください。
mcp-name: io.github.AshwanthramKL/whoop-mcp
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。