WHOOP MCP

whoop-mcp

MCP サーバーです。WHOOP のデータを Postgres に同期し、AI エージェントがクエリできるようにします。

WHOOP の公開 API はレート制限があり、カーソルページネーションを採用していて、一度に 1 件ずつレコードを返します。同期ジョブには問題ありませんが、「今週の HRV はベースラインと比べてどうか？」という質問に答えたいエージェントには不向きです。そのため、このサーバーは処理を 2 つに分けます。

• WHOOP API からサイクル、回復、睡眠、ワークアウト、身体測定値を、文書化された Postgres スキーマに取り込む 同期 パス。型付きカラムとともに、各レコードの生 JSON も保持します。
• Postgres のみを読み取る MCP ツールの クエリ パス。高速で、WHOOP のレート制限にかからず、データの同期後はオフラインでも動作し続けます。

データは自分が所有するデータベースに保存され、任意の SQL クライアントで読めるスキーマに格納されます。WHOOP 自体への呼び出しを除き、データがこのマシンの外に送信されることはありません。

Python 3.12+ · MIT · stdio MCP サーバー + CLI · Postgres ストレージ

---

目次

• ツール
• インストール
• クイックスタート
• 設定
• MCP クライアントへの登録
• 同期の仕組み
• セキュリティモデル
• 開発
• プロジェクト構成
• ライセンス

---

ツール

書き込み側の 2 つのツールは WHOOP API と通信し、それ以外のすべてのツールは Postgres のみを読み取ります。

ツール	引数	処理内容
whoop_auth_url	なし	ブラウザーで開く OAuth 認証 URL を返します。
whoop_connect	code	OAuth コードをトークンと交換して保存し、接続したユーザーを返します。
whoop_sync	days=7、full=false	WHOOP のデータを Postgres に取り込みます。コレクションごとの件数とエラーを返します。
whoop_status	なし	コレクションごとの同期状態：最終同期、ウォーターマーク、行数、最終エラー。
whoop_overview	days=7	最新の回復度とバイタルを 30 日間のベースラインと比較し、昨夜の睡眠、最近のワークアウトと運動負荷を表示します。
whoop_recovery	days=7、limit=50	最近の回復スコア、安静時 HR、HRV、SpO2、皮膚温を表示します。
whoop_sleep	days=7、limit=50	最近の睡眠と昼寝を、睡眠ステージの内訳、必要量、パフォーマンス、効率とともに表示します。
whoop_workouts	days=14、limit=50	最近のワークアウトを、運動負荷、HR、エネルギー、距離、ゾーン別の運動時間とともに表示します。
whoop_cycles	days=7、limit=50	最近の生理学的サイクル（WHOOP の日）を、その日の運動負荷と HR とともに表示します。
whoop_baseline	なし	各バイタルの 30 日間の平均と標準偏差を返します。

days の上限は 365、limit の上限は 200 です。すべてのツールは JSON テキストを返します。

インストール

uv tool install whoop-postgres-mcp      # or: pipx install whoop-postgres-mcp

インストールせずに実行することもできます。

uvx whoop-postgres-mcp --help

Postgres データベース（最近のバージョンであればどれでもよく、14 以降を推奨）と、WHOOP の開発者アプリも必要です。docs/SETUP.md で両方の設定方法を説明しています。

クイックスタート

export WHOOP_CLIENT_ID=...
export WHOOP_CLIENT_SECRET=...
export WHOOP_REDIRECT_URI=http://localhost:8765/callback
export WHOOP_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop

whoop-mcp init-db          # create the `whoop` schema (idempotent)
whoop-mcp auth-url         # print the URL to visit; approve access in a browser
whoop-mcp connect <code>   # paste the `code` from the redirect URL
whoop-mcp sync --all       # first backfill; later runs: whoop-mcp sync --days 7
whoop-mcp                  # serve MCP over stdio

同じ手順を MCP ツール（whoop_auth_url、whoop_connect、whoop_sync）から実行できるため、エージェントがセットアップ全体を進められます。

設定

すべての設定は環境変数で行います。サーバーは起動時に各変数を検証し、未設定の変数名を示すメッセージを表示して終了します。

変数	必須	意味
WHOOP_CLIENT_ID	はい	WHOOP 開発者アプリのクライアント ID。
WHOOP_CLIENT_SECRET	はい	WHOOP 開発者アプリのクライアントシークレット。
WHOOP_REDIRECT_URI	はい	アプリに登録したものと完全に一致するリダイレクト URI。任意の URL を使用できます。サーバーはこの URL をリッスンしません。アドレスバーから code をコピーします。
WHOOP_DB_URL	はい	Postgres DSN。例：postgresql://user:pass@host:5432/db。トークンとデータはここに保存されます。

MCP クライアントへの登録

Claude Code：

claude mcp add whoop -e WHOOP_CLIENT_ID=... -e WHOOP_CLIENT_SECRET=... \
  -e WHOOP_REDIRECT_URI=http://localhost:8765/callback \
  -e WHOOP_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop \
  -- uvx whoop-postgres-mcp

Claude Desktop（claude_desktop_config.json）または stdio コマンドを受け付ける任意のクライアント：

{
  "mcpServers": {
    "whoop": {
      "command": "uvx",
      "args": ["whoop-postgres-mcp"],
      "env": {
        "WHOOP_CLIENT_ID": "...",
        "WHOOP_CLIENT_SECRET": "...",
        "WHOOP_REDIRECT_URI": "http://localhost:8765/callback",
        "WHOOP_DB_URL": "postgresql://whoop:whoop@localhost:5432/whoop"
      }
    }
  }
}

同期の仕組み

WHOOP のコレクションエンドポイントは、レコードが最後に変更された日時ではなく、発生した日時でフィルタリングします。また、レコードは作成後に変更されます（睡眠は PENDING_SCORE として作成され、後からスコアが付与されます）。そのため、同期では次の処理を行います。

1. 常に直近 days 日分を再取得し、後からの再スコア付与を捕捉します。
2. コレクションごとのウォーターマーク（whoop_sync_state の newest_updated_at）を追跡します。前回の同期が days 日より前の場合は、ウィンドウをウォーターマークから2日分さかのぼって延長し、同期の空白によるデータの抜けを防ぎます。
3. 自然キー（id、またはリカバリーの場合は cycle_id）を使ってすべてのレコードをアップサートするため、ウィンドウが重複しても問題はなく、再実行しても安全です。
4. コレクションごとのエラーを whoop_sync_state に記録し、実行を中断する代わりに、ほかのコレクションの処理を続行します。

full=true（または whoop-mcp sync --all）を指定すると、下限をなくし、アカウントの全履歴を取得します。身体測定値は現在の値が1件だけで、同期のたびに更新されます。

トークンの更新は有効期限の5分前に先行して行われ、Postgres のアドバイザリロックを使って直列化されます。そのため、MCP サーバーと cron で実行する whoop-mcp sync は、競合することなく同じトークン行を共有できます。

データモデルの全容は docs/SCHEMA.md に記載されています。

セキュリティモデル

• データベースへのアクセスはトークンへのアクセスを意味します。 OAuth トークンは whoop.whoop_tokens に平文で保存されます。このテーブルを読み取れる人は、リフレッシュトークンが無効化されるまで、あなたとして WHOOP API を呼び出せます。データベースの権限を適切に制限し、WHOOP_DB_URL を秘密情報として扱ってください。
• 読み取りツールはネットワークに接続しません。 WHOOP と通信するのは whoop_connect と whoop_sync のみです。そのほかの処理はすべて、データベースに対する SQL クエリです。
• Postgres の外部には何も書き込みません。 ファイルも、キャッシュも、テレメトリーもありません。
• スコープは読み取り専用です。 アプリはリフレッシュトークン用の offline と、read:* スコープを要求します。WHOOP アカウントの内容を変更することはできません。
• アクセスを取り消すには、whoop_tokens から行を削除し、WHOOP アカウントの設定からアプリを削除してください。

開発

git clone https://github.com/cunicopia-dev/whoop-mcp
cd whoop-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

ruff check .
mypy src
pytest                       # pure-logic tests
WHOOP_TEST_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop pytest   # + live DB tests

ライブテストでは、各テストの前にスキーマを適用し、対象データベースのすべてのテーブルを空にします。テストには使い捨てのデータベースを指定してください。

ローカルテスト用の使い捨て Postgres：

docker run -d --rm --name whoop-pg -e POSTGRES_USER=whoop -e POSTGRES_PASSWORD=whoop \
  -e POSTGRES_DB=whoop -p 5432:5432 postgres:16-alpine

プロジェクト構成

src/whoop_mcp/
  config.py     environment variables, validated at startup
  auth.py       OAuth2 flow, token persistence, locked refresh
  client.py     httpx client: pagination, backoff, Retry-After
  schema.sql    the Postgres DDL (applied by `whoop-mcp init-db`)
  db.py         connection + schema helpers
  sync.py       incremental sync with per-collection watermarks
  queries.py    read-side SQL behind the MCP tools
  server.py     MCP server over stdio + CLI entry point
docs/
  SETUP.md      WHOOP app registration, OAuth walkthrough, DB init, first sync
  SCHEMA.md     column-by-column data model
tests/          config, schema, client, auth, sync, and stdio protocol tests

ライセンス

MIT。詳細は LICENSE をご覧ください。