mcpField
W
whoop-mcp

whoop-mcp

ローカル
github.com/AshwanthramKLヘルスケア026 週間前に更新

whoop-mcp について

whoop-mcpは、WHOOP v2のフィットネスデータをMCPクライアントに提供するローカルの読み取り専用MCPサーバーです。直接OAuth認証とローカルSQLiteキャッシュを使い、記録の照会、同期、エクスポートに対応します。

主な機能

  1. 01WHOOPのプロフィールとフィットネス記録を読み取る
  2. 02データをローカルのSQLiteにキャッシュ
  3. 03記録をオンデマンドまたは増分同期
  4. 04MCPリソースからキャッシュデータを参照
  5. 05CSV、JSONL、Parquet形式で記録をエクスポート

活用シーン

  1. 01毎日の睡眠、回復、ワークアウトを確認
  2. 02APIを呼び出さずにキャッシュ記録を検索
  3. 03WHOOP記録の更新を追跡
  4. 04分析用にワークアウトデータをエクスポート

MCP 対応

MCPクライアントにWHOOPデータの読み取り専用ツールと、キャッシュ記録のJSONリソースを提供します。WHOOPに直接認証し、取得データをローカルのSQLiteキャッシュに保存します。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
"mcpServers": {
"ashwanthramkl-whoop": {
"command": "uvx",
"args": [
"whoop-mcp"
],
"env": {
"WHOOP_CLIENT_ID": "<WHOOP_CLIENT_ID>",
"WHOOP_CLIENT_SECRET": "<WHOOP_CLIENT_SECRET>",
"WHOOP_REDIRECT_URI": "<WHOOP_REDIRECT_URI>",
"WHOOP_LOG_LEVEL": "<WHOOP_LOG_LEVEL>",
"WHOOP_LOG_FILE": "<WHOOP_LOG_FILE>",
"WHOOP_LOG_JSON": "<WHOOP_LOG_JSON>"
}
}
}
}
起動コマンドuvx whoop-mcp
設定が必要な環境変数
WHOOP_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 以上など)が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
pypiwhoop-mcp0.8.5

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

WHOOP MCP サーバー

CI PyPI Python 3.10+ License: MIT MCP Tests

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 ページのマップが記載されています。

目次

概要

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 を実行してください。

クイックスタート

サーバーを登録したら、次のプロンプトを試してください。

  1. キャッシュを同期する。 「過去 30 日間の WHOOP データを同期してください。」 Claude は sync_whoop() を呼び出し、リソースごとの件数を報告します。
  2. 特定の日を確認する。 「昨日の WHOOP 日次サマリーを表示してください。」 Claude は get_whoop_daily_summary(date="YYYY-MM-DD") を呼び出し、 サイクル+リカバリー+主要な睡眠+ワークアウトを結合したレコードを表示します。
  3. エクスポートする。 「キャッシュされたワークアウトをすべて ~/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_statusOAuth トークンの状態を報告します。他のツールが 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_sleepUUID で指定した 1 件の睡眠アクティビティを返します。sleep_id、fresh
list_whoop_workoutsゾーンごとの継続時間(秒)を含むワークアウトを返します。start、end、limit、fresh
get_whoop_workoutUUID で指定した 1 件のワークアウトを返します。workout_id、fresh
get_whoop_daily_summaryUTC の日付について、サイクル、回復、主要な睡眠、ワークアウトを結合して返します。date
sync_whoopWHOOP 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-mcpuvx --refresh --from whoop-mcp whoop-mcp を実行するか、uv cache clean whoop-mcp を実行してから再度呼び出します
uvx --from whoop-mcp@latest whoop-mcp次回のキャッシュミス時に更新されます(手動操作は不要です)
pipx install whoop-mcppipx upgrade whoop-mcp
pip install whoop-mcppip install --upgrade whoop-mcp
Git クローン+venvgit 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

コメント

MCP は初めてですか?

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。