WHOOP Health Signals

mcp-server-whoop

WHOOP 向けのローカル優先、読み取り専用のModel Context Protocolサーバーです。ホスト型の第三者サービスに WHOOP の認証情報を送信することなく、MCP 対応 AI クライアントに、回復、睡眠、負荷、HRV、心拍数、ワークアウト、身体測定の簡潔なシグナルを提供します。

このサーバーを選ぶ理由

• ローカル MCP サーバーに対応するあらゆるクライアントで使用できる、stdio による標準的な MCP
• 各ユーザー自身の WHOOP 開発者アプリケーションを使ったローカル WHOOP OAuth フロー
• アクセストークンとローテーションするリフレッシュトークンは、ユーザーのマシン上に保持されます
• 大量の API データをそのまま出力する代わりに、用途を絞った読み取り専用ツールを 5 つ提供
• レコードごとのローカルタイムスタンプにより、移動しても睡眠やワークアウトの日付がずれません
• processing ステータスを明示し、新しい睡眠データの処理中に以前の回復データで代用しません
• スコア由来の指標は SCORED レコードにのみ表示されます。現在のサイクルのリアルタイムの負荷は provisional_strain としてラベル付けされます
• 人が把握しやすい時間、分、カロリー、心拍ゾーンの時間
• ツールの出力に生の識別子、OAuth シークレット、生の連続心拍数データの断定的な主張は含まれません
• ホスト型リレー、テレメトリ、データベース、汎用 HTTP ツール、生の SQL、インストール時のライフサイクルスクリプトはありません
• 再現可能な tarball セキュリティ監査、CycloneDX SBOM、CodeQL、Gitleaks、依存関係レビュー、OpenSSF Scorecard

これは独立したコミュニティプロジェクトです。WHOOP との提携や、WHOOP による推奨を受けているものではありません。WHOOP のデータはコーチングの参考情報であり、医療上の助言ではありません。

必要条件

• Node.js 18 以降
• WHOOP アカウント
• WHOOP Developer Dashboardの無料アプリケーション
• MCP 対応 AI クライアント

クイックスタート

1. WHOOP 開発者アプリケーションを作成し、http://127.0.0.1:8765/callback を登録します。
2. 以下に記載されている 5 つの読み取りスコープと offline を有効にします。
3. ターミナルで npx -y [email protected] auth を実行し、WHOOP へのアクセスを承認します。
4. npx -y [email protected] status を実行して、ローカルに認可情報が存在することを確認します。
5. npx -y [email protected] の stdio コマンドを AI クライアントの MCP 設定に追加します。
6. クライアントを再起動または再読み込みしてから、次のように尋ねます。Use WHOOP to summarize my recovery and sleep from the last 7 days.

認可コマンドと AI クライアントは同じオペレーティングシステムユーザーとして実行する必要があります。または、両方で WHOOP_CREDENTIALS_FILE に同じプライベートファイルを設定してください。このパッケージから、WHOOP のトークンを AI との会話に貼り付けるよう求めることはありません。

ドキュメントでは、レビュー済みの特定バージョンをデフォルトで固定しています。今後のリリースを事前にレビューせずクライアントに追従させたい場合に限り、@latest を使用してください。

1. WHOOP アプリケーションを作成する

WHOOP Developer Dashboard でアプリケーションを作成し、次のリダイレクト URL を正確に登録します。

http://127.0.0.1:8765/callback

次のスコープを有効にします。

offline
read:recovery
read:cycles
read:sleep
read:workout
read:body_measurement

WHOOP のアクセストークンは有効期限が切れ、WHOOP がリフレッシュトークンをローテーションするため、offline が必要です。

2. ローカルで認証する

次を実行します。

npx -y [email protected] auth

このコマンドは WHOOP のクライアント ID の入力を求め、クライアントシークレットをマスクしたうえで、ブラウザーで WHOOP の同意画面を開き、OAuth の state を検証して、取得した認可情報をローカルに保存します。

認証情報は次の場所に保存されます。

~/.config/mcp-server-whoop/credentials.json

Linux と macOS では、使用前にすべてのパスの親ディレクトリを確認します。直接のディレクトリは現在のユーザーが所有し、モードは 0700 である必要があります。また、ファイルはリンク数が 1 の通常ファイルで、現在のユーザーが所有し、モードは 0600 である必要があります。パスを変更する場合は、すべての親ディレクトリが信頼でき、シンボリックリンクではないことを確認してから、WHOOP_CREDENTIALS_FILE で上書きしてください。

ネイティブ Windows では、永続的な OAuth 認証情報は安全側に倒して使用できないようにしています。Node.js のファイルモードでは、Windows のプライベート ACL を強制できず、標準のファイル API では再解析ポイントを安全に扱った認証情報の書き込みを保証できないためです。ネイティブ Windows のユーザーは、MCP プロセスの環境変数で有効期間の短い WHOOP_ACCESS_TOKEN を指定できますが、ネイティブの認証情報バックエンドが利用可能になるまでは、自動認証とリフレッシュトークンの永続化には WSL、Linux、または macOS が必要です。

ヘッドレス環境では、auth の実行前に、環境変数として WHOOP_CLIENT_ID、WHOOP_CLIENT_SECRET、必要に応じて WHOOP_REDIRECT_URI を指定してください。

OAuth コールバックは、引き続き auth を実行しているマシンに届く必要があります。SSH 経由で認証する場合は、まずワークステーションからループバックトンネルを作成します。

ssh -L 8765:127.0.0.1:8765 user@your-server

その後、その SSH セッションで auth を実行し、表示された WHOOP の URL をワークステーションのブラウザーで開きます。シェルの履歴やプロセス一覧に表示される可能性があるため、クライアントシークレットをコマンドライン引数として渡さないでください。

シークレットを表示せずにセットアップを確認します。

npx -y [email protected] status

ローカルの認可情報を削除します。

npx -y [email protected] logout

連携を使わなくなった場合は、WHOOP アカウント設定からアクセス権を取り消すこともおすすめします。

3. AI クライアントに追加する

Claude Desktop

Claude Desktop の設定で mcpServers の下に追加し、その後 Claude Desktop を完全に再起動してください。

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Claude Code

claude mcp add --transport stdio whoop -- npx -y [email protected]

Cursor、Windsurf、Gemini Code Assist、およびその他の mcpServers 対応クライアント

クライアントの MCP JSON にサーバーを追加します。Gemini Code Assist は ~/.gemini/settings.json を使用します。他のクライアントでは、それぞれの設定パスを使用してください。

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

VS Code

プロジェクト用に .vscode/mcp.json を作成するか、VS Code の MCP: Add Server コマンドを使用します。

{
  "servers": {
    "whoop": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Codex

次を実行するか、

codex mcp add whoop -- npx -y [email protected]

~/.codex/config.toml に次を追加します。

[mcp_servers.whoop]
command = "npx"
args = ["-y", "[email protected]"]

ChatGPT

stdio に対応するローカルの Codex および ChatGPT デスクトップクライアントは、上記の Codex 設定を使用できます。ChatGPT web はコンピューター上のコマンドを起動しません。別途、セキュリティを確保したリモートブリッジまたはトンネルと、ワークスペースプラグインが必要です。このリポジトリでは、公開のヘルスデータ中継サービスを意図的に提供も運用もしていません。

クライアントのメニューや設定パスは、時間とともに変わります。標準のローカル stdio MCP に対応しているクライアントであれば、移植可能な値は常に次のとおりです。

command: npx
arguments: -y [email protected]

接続を確認する

クライアントを再起動した後、次の 5 つのツールだけが検出されることを確認します。

whoop_latest_overview
whoop_recovery_history
whoop_sleep_history
whoop_cycle_strain_history
whoop_workout_history

便利なプロンプト：

• Use WHOOP to review today's recovery, latest sleep, current strain, and latest workout.
• Compare my recovery, HRV, and resting heart rate over the last 14 days.
• Show my last 7 days of sleep, including naps, and flag anything still processing.
• Summarize my workout strain and heart-rate zones for the last 30 days.
• Use WHOOP as context for today's training, but do not treat it as medical advice.

ツールを呼び出すタイミングはモデルが判断します。一般的な回答ではなくライブデータが必要な場合は、Use WHOOP と明示してください。

ツール

ツール	用途
whoop_latest_overview	保留中のデータに関する安全策を備えた、現在のコーチング概要
whoop_recovery_history	リカバリー、HRV、安静時心拍数、SpO2、皮膚温の推移
whoop_sleep_history	主な睡眠と任意の仮眠、睡眠ステージ、必要量、質、タイミング
whoop_cycle_strain_history	日々の負荷、カロリー、平均／最大心拍数
whoop_workout_history	スポーツ、時間、負荷、心拍数、カロリー、距離、ゾーン別の運動時間

すべてのツールは読み取り専用で、非破壊的かつ冪等としてマークされています。

ツールを意図的に5つに絞っている理由

ヘルスデータ向けの MCP では、ツールの数が増えるほど、利用可能な機能の範囲も広がります。このサーバーでは認証をエージェントの外部に置き、モデルには必要な5つのヘルスデータ読み取り機能のみを提供します。

意図的に、次の機能は備えていません。

• WHOOP の書き込み、取り消し、トークン管理、認可コードの各ツール
• プロフィール、メールアドレス、氏名のスコープ
• 生レコード、生 ID、任意のエンドポイント、SQL、ファイル、シェルの各ツール
• ホスト型 OAuth リレー、テレメトリーサービス、ヘルスデータキャッシュ、データベース
• 最新の睡眠データの処理中に古いリカバリーを代わりに返す機能

目的は WHOOP API を最大限に網羅することではありません。リカバリーを考慮した AI に必要な、実用上最小限の権限境界を設けることです。

データの意味

WHOOP は、睡眠、サイクル、ワークアウトのレコードに絶対時刻と timezone_offset を返します。このサーバーは各レコード固有のオフセットを適用し、次のように、すでにローカル時刻に変換されたタイムスタンプのみを返します。

2026-07-07 18:02:22 +04:00

過去のレコードにマシンの現在のタイムゾーンを適用することはありません。

WHOOP はアクティビティの種類とワークアウトのスポーツを公開していますが、公開 API ではワークアウトが自動検出されたのか、手動で開始されたのかは示されません。このサーバーは推測しません。

最新の主な睡眠データがまだ PENDING_SCORE の場合、最新の概要は次を返します。

{
  "status": {
    "state": "waiting_for_whoop",
    "current_recovery_available": false
  },
  "recovery": null
}

古いリカバリーを現在のものとして提示することはありません。

環境変数

変数	用途
WHOOP_CLIENT_ID	WHOOP OAuth クライアント ID
WHOOP_CLIENT_SECRET	WHOOP OAuth クライアントシークレット
WHOOP_REDIRECT_URI	OAuth コールバック。デフォルトは http://127.0.0.1:8765/callback
WHOOP_CREDENTIALS_FILE	ローカルの認証情報ファイルのパスを上書き
WHOOP_ACCESS_TOKEN	任意の短期間有効なアクセストークンによる上書き
WHOOP_REFRESH_TOKEN	任意のリフレッシュトークンによる上書き
WHOOP_TOKEN_EXPIRES_AT	任意の ISO 形式のトークン有効期限による上書き

WHOOP_CLIENT_ID、WHOOP_CLIENT_SECRET、WHOOP_REDIRECT_URI によるクライアント設定は、ファイルの値より優先されます。トークンの環境変数はヘッドレス環境のセットアップに使用できますが、リフレッシュトークンがローテーションされると、認証情報ファイルに保存された新しいトークンが優先されます。シークレットをコマンドライン引数に直接指定したり、ソース管理にコミットしたりしないでください。

トラブルシューティング

Missing WHOOP ...

AI クライアントを起動する OS ユーザーと同じユーザーで、npx -y [email protected] status を実行してください。認証情報が別の場所にある場合は、クライアントの MCP 環境で WHOOP_CREDENTIALS_FILE を設定してください。

WHOOP からリダイレクトの不一致が報告される

Developer Dashboard のリダイレクト URI と、このパッケージで使用する値は完全に一致させる必要があります。デフォルトは http://127.0.0.1:8765/callback です。スキーム、ホスト、ポート、パスも一致させてください。

ブラウザーが開かない

ターミナルに表示された認可 URL をコピーして、手動で開いてください。コールバックリスナーは5分後に期限切れになります。必要に応じて auth を再実行してください。

ポート 8765 がすでに使用されている

http://127.0.0.1:9876/callback のような別のループバック URL を登録し、WHOOP_REDIRECT_URI にその値を正確に設定してから、auth を再実行してください。

リカバリーが null

返された status.state を確認してください。値が waiting_for_whoop または waiting_for_recovery の場合、WHOOP は最新の睡眠データのスコアリングをまだ完了していません。このサーバーは古いリカバリーを現在のものとして扱わないようにしているため、WHOOP の処理完了後に再試行してください。

クライアントにツールが表示されない

ターミナルで npx -y [email protected] --help を実行し、Node.js と npm でパッケージを起動できることを確認してから、AI クライアントを再起動し、MCP ログを確認してください。出力を確認するためにサーバーを単独で対話的に実行しないでください。stdio は MCP プロトコルメッセージ専用です。

開発

git clone [email protected]:Yadheedhya06/mcp-server-whoop.git
cd mcp-server-whoop
npm ci --ignore-scripts
npm run check

ローカルのソースサーバーを実行します：

npm run dev

正確な npm 成果物をビルドして確認します：

npm pack --dry-run

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

このプロジェクトは、どのパッケージも完全に安全であると主張するのではなく、根拠を公開しています。完全なセキュリティポリシーと再現可能なセキュリティの根拠をご覧ください。

• すべてのユーザーが、自身の WHOOP 開発者アプリと OAuth 許可を管理します。
• 認証情報はローカルに保持され、MCP ツールを通じて返されることはありません。
• このパッケージには、WHOOP への書き込み、汎用ネットワーク、シェル、ファイルシステム、または生 API のパススルーを行うツールはありません。
• 対応する POSIX ストレージでは、認証情報ファイルとそのすべての親ディレクトリについて、シンボリックリンク、安全でない所有者または権限、過大な入力、予期しないフィールドがないか確認します。トークンの更新ローテーションでは、PID を信用しないハートビートリース、排他的な一時ファイル、アトミックな置換、書き込み後の検証、ディスク同期を使用します。ネイティブの Windows 永続化では、安全性を確保できない場合に処理を拒否します。
• WHOOP と OAuth の応答はサイズに上限を設け、構造を検証します。プロバイダーの応答本文が MCP エラーにコピーされることはありません。
• 直接依存関係には正確なバージョンを指定しています。直接のランタイム依存関係は 2 つのみで、パッケージのインストール時に実行されるライフサイクルスクリプトはありません。
• CI では Node 18、20、22、24 で完全なテストスイートを実行し、macOS と Windows のプラットフォームセキュリティジョブを追加で実行します。また、ソースと、コンパイル済みの正確な npm ランタイムの両方を監査し、npm レジストリの署名を検証し、CycloneDX SBOM を生成します。
• 独立したワークフローで、CodeQL、Gitleaks、依存関係レビュー、OpenSSF Scorecard を実行します。
• 公開ワークフローでは一度だけパッケージを作成し、その正確な tarball を npm Trusted Publishing と Sigstore provenance を通じて公開します。GitHub はその tarball と CycloneDX SBOM の整合性を別途証明します。長期間有効な npm トークンは使用しません。

これらの対策によりリスクは軽減されますが、有料の侵入テストでも、安全性を保証するものでもありません。制限事項は SECURITY-EVIDENCE.md に明記しています。

ライセンス

MIT