WHOOP MCP サーバー

Claude があなたの WHOOP 健康データ（回復、睡眠、負荷、ワークアウト、プロフィール）を WHOOP の公式 OAuth 2.0 REST API（v2）経由で照会できるようにする MCP（Model Context Protocol）サーバーです。

このサーバーを使用する各ユーザーは、自身の WHOOP アカウントに対して自分のコピーを実行します。WHOOP で無料のデベロッパーアプリを登録し、トークンや認証情報はマシン上のローカルファイルに保持されます（gitignore 対象）。データが共有されたり、あなたのマシンと WHOOP の API 以外に送信されることはありません。

git clone https://github.com/vaibhavgoel63-arch/Whoop-MCP.git
cd Whoop-MCP

1. WHOOP API 認証情報を取得する

1. WHOOP デベロッパーダッシュボード にアクセスし、サインインします。

2. アプリを作成（または開く）します。

3. アプリの API 設定で、リダイレクト URI を次のように正確に設定します。

   http://localhost:8080/callback

4. クライアント ID と クライアントシークレット をコピーします。これらは、以下の手順 3 で .env に貼り付けます。

Related MCP server: Whoop MCP Server

2. 前提条件

• Node.js 18+（組み込みの fetch API に必要）。node --version で確認してください。

3. インストールと設定

npm install
cp .env.example .env

.env を開き、手順 1 で取得したクライアント ID とクライアントシークレットを貼り付けます。

WHOOP_CLIENT_ID=your-client-id-here
WHOOP_CLIENT_SECRET=your-client-secret-here
WHOOP_REDIRECT_URI=http://localhost:8080/callback

⚠️ WHOOP_CLIENT_ID と WHOOP_CLIENT_SECRET は手動で入力する必要があります。これらが設定されるまで、サーバーは OAuth フローを開始しません。

4. ビルドとログイン（初回のみ）

npm run build
npm run login

これにより、以下の処理が行われます。

1. http://localhost:8080 に一時的なローカルサーバーを起動します。

2. ブラウザで WHOOP の同意画面を開きます（回復、睡眠、サイクル、ワークアウト、プロフィール、身体測定、オフライン/更新スコープを要求）。

3. 承認後、WHOOP は認証コードとともに localhost:8080/callback にリダイレクトします。

4. スクリプトがそのコードをアクセストークンと更新トークンに交換し、プロジェクトルートの token.json（gitignore 対象）に保存します。

この手順は一度だけ実行すれば十分です。MCP サーバーは、アクセストークンの有効期限が切れたときに更新トークンを使用して自動的にアクセストークンを更新します（WHOOP のアクセストークンは約 1 時間有効）。更新トークンが失効または期限切れになった場合は、npm run login を再実行してください。

5. Claude Desktop に接続する

Claude Desktop の設定ファイルを開きます。

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

注：Microsoft Store から Claude Desktop をインストールした場合、上記のファイルは単なるスタブである可能性があります。アプリは実際には %LOCALAPPDATA%\Packages\<Claude パッケージフォルダー>\LocalCache\Roaming\Claude\claude_desktop_config.json を読み取ります。以下の手順を実行してもツールが表示されない場合は、そちらを確認してください。

mcpServers の下に whoop エントリを追加します。以下のパスを、このプロジェクトの dist/server.js への絶対パスに置き換えてください（プロジェクトフォルダー内から macOS/Linux では pwd、Windows では cd で確認できます）。

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp/dist/server.js"]
    }
  }
}

⚠️ この絶対パスは手動で入力する必要があります。このリポジトリをクローンした場所へのパスです。Windows でもスラッシュを使用してください（例：C:/Users/you/whoop-mcp/dist/server.js）。この JSON ファイル内では問題なく動作します。

その後、Claude Desktop を完全に再起動します（ウィンドウを閉じるだけでなく、システムトレイから終了します）。

6. テストする

1. Claude Desktop で、チャットボックスのツール/ハンマーアイコンをクリックし、whoop に 6 つのツール（get_recovery、get_sleep、get_strain、get_workouts、get_profile、get_training_recommendation）がリストされていることを確認します。

2. 次のプロンプトを試してください。

   • 「今週の回復はどうですか？」

   • 「今日はハードにトレーニングすべきですか？」

   • 「過去 3 晩の睡眠はどうでしたか？」

   • 「過去 7 日間のワークアウトを見せてください。」

   • 「現在の負荷はどれくらいで、昨日と比べてどうですか？」

   • 「2026 年 3 月の平均負荷はどれくらいでしたか？」（「過去 N 日間」だけでなく、履歴範囲）

3. 1 つの結果（例：今日の回復スコア）を WHOOP アプリと照合して、数値が一致することを確認します。

ツールリファレンス

4 つの範囲ベースのツールは、days（ローリングウィンドウ、例：days=7 で過去 1 週間）または明示的な start/end 日付ペア（YYYY-MM-DD、終了日は含まない）を受け入れ、特定の履歴期間を照会します（例：start="2026-03-01", end="2026-04-01" で 2026 年 3 月全体）。各ツールは、個々の日次/夜間の records とともに summary オブジェクト（平均/合計）を返します。

トラブルシューティング

• 「WHOOP トークンが見つかりません」 — npm run login を実行してください。

• 以前は動作していたのに 401 / トークンエラーが発生する — サーバーはアクセストークンを自動更新します。更新に失敗した場合、更新トークンが失効している可能性があります（例：WHOOP 設定でアプリのアクセスを削除した）。npm run login を再実行してください。

• 403 Forbidden — トークンにスコープが不足しています。スコープはログイン時に固定されるため、npm run login を再実行して、完全なスコープセットを持つ新しいトークンを取得してください。

• 429 Too Many Requests — WHOOP のレート制限（100 リクエスト/分、10,000/日）に達しました。しばらく待ってから再試行してください。

• Claude Desktop にツールが表示されない — claude_desktop_config.json の絶対パスを再確認し、npm run build を実行したこと（設定は src/server.ts ではなく dist/server.js を指している）、および Claude Desktop を完全に再起動したことを確認してください。

プロジェクト構造

src/
  auth.ts        # OAuth constants, token load/save, refresh logic
  login.ts        # One-time login script (npm run login)
  whoopClient.ts  # Authenticated WHOOP API client + response normalizers
  server.ts       # MCP server exposing the 6 tools
.env.example      # Template for WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET / WHOOP_REDIRECT_URI

.env（認証情報）と token.json（アクセス/更新トークン）はどちらも gitignore 対象です。これらのファイルをコミットしないでください。