Whoop MCP Server Claude

🚀 WHOOP MCP Server

WHOOPのすべてのAPIエンドポイントにアクセスできる、Model Context Protocol (MCP)サーバーです。このサーバーを使用すると、MCP標準を通じてWHOOPのフィットネスおよび健康データをアプリケーションに統合することができます。

✨ 主な機能

• 完全なWHOOP APIカバレッジ：WHOOP v2のすべてのAPIエンドポイントにアクセス可能
• OAuth 2.0認証：安全な認証フロー
• ユーザーデータ：プロフィール情報と身体測定データ
• サイクル：ストレインと心拍数の指標を含む生理学的サイクルデータ
• 回復：回復スコア、HRV、安静時心拍数のデータ
• 睡眠：睡眠段階とパフォーマンス指標を含む詳細な睡眠分析
• ワークアウト：ストレイン、心拍数ゾーン、活動指標を含む運動データ
• ページネーションサポート：ページネーションで大規模なデータセットを処理
• TypeScript：完全な型安全性とIntelliSenseサポート

📦 インストール

前提条件

• Node.js 18+
• WHOOP開発者アカウント
• WHOOP APIの資格情報

セットアップ手順

1. 依存関係のインストール

npm install

2. WHOOP APIのセットアップ

1. WHOOP開発者プラットフォームにアクセスします。
2. 新しいアプリケーションを作成します。
3. Client IDとClient Secretをメモします。
4. リダイレクトURIを設定します（例：http://localhost:3000/callback）。

3. 環境構成

サンプルの環境ファイルをコピーし、WHOOPの資格情報を設定します。

cp env.example .env

.envファイルを編集し、WHOOP APIの資格情報を入力します。

# WHOOP API Configuration
WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
WHOOP_REDIRECT_URI=http://localhost:3000/callback

# MCP Server Configuration
MCP_SERVER_PORT=3001

4. ビルドと実行

# プロジェクトのビルド
npm run build

# MCPサーバーの実行
npm start

# または開発モードで実行
npm run dev

📚 ドキュメント

認証フロー

MCPサーバーは、WHOOPとのOAuth 2.0認証をサポートしています。認証方法は以下の通りです。

1. 認可URLの取得：whoop-get-authorization-urlツールを使用して、OAuth URLを取得します。
2. ユーザー認可：ユーザーを認可URLに誘導します。
3. 認可コードのコピー：WHOOPからリダイレクトされると、URLから認可コードをコピーします。
4. コードをClaudeと共有：重要 - 認可コードをURLからコピーし、Claudeのチャットに直接貼り付ける必要があります。
5. コードの交換：Claudeがwhoop-exchange-code-for-tokenツールを使用して、認可コードを交換します。
6. アクセストークンの設定：Claudeがwhoop-set-access-tokenツールを使用して、API呼び出し用のアクセストークンを設定します。

⚠️ 認可コードに関する重要な注意事項

ブラウザでWHOOPの認可を完了すると、認可コードを含むURLにリダイレクトされます。このコードをコピーし、Claudeとのチャットに直接貼り付ける必要があります。URL内のコードは次のように表示されます。

http://localhost:3000/callback?code=ABC123XYZ789&scope=read:recovery%20read:cycles...

codeパラメータの値（例：ABC123XYZ789）をコピーし、Claudeとのチャットに貼り付けます。Claudeはこのコードを使用してアクセストークンと交換し、WHOOPデータへの接続を設定します。

利用可能なツール

ユーザーツール

• whoop-get-user-profile - 基本的なユーザープロフィール情報を取得
• whoop-get-user-body-measurements - 身体測定データ（身長、体重、最大心拍数）を取得
• whoop-revoke-user-access - ユーザーのアクセストークンを取り消す

サイクルツール

• whoop-get-cycle-by-id - IDで特定のサイクルデータを取得
• whoop-get-cycle-collection - ページネーションされたサイクルのリストを取得
• whoop-get-sleep-for-cycle - 特定のサイクルの睡眠データを取得

回復ツール

• whoop-get-recovery-collection - ページネーションされた回復データを取得
• whoop-get-recovery-for-cycle - 特定のサイクルの回復データを取得

睡眠ツール

• whoop-get-sleep-by-id - IDで特定の睡眠記録を取得
• whoop-get-sleep-collection - ページネーションされた睡眠記録を取得

ワークアウトツール

• whoop-get-workout-by-id - IDで特定のワークアウト記録を取得
• whoop-get-workout-collection - ページネーションされたワークアウト記録を取得

OAuthツール

• whoop-get-authorization-url - OAuth認可URLを取得
• whoop-exchange-code-for-token - 認可コードをアクセストークンに交換
• whoop-refresh-token - アクセストークンを更新
• whoop-set-access-token - API呼び出し用のアクセストークンを設定

💻 使用例

ユーザープロフィールの取得

// まずアクセストークンを設定
await callTool('whoop-set-access-token', { accessToken: 'your_access_token' });

// 次にユーザープロフィールを取得
const profile = await callTool('whoop-get-user-profile', {});

最近のサイクルの取得

const cycles = await callTool('whoop-get-cycle-collection', {
  limit: 10,
  start: '2024-01-01T00:00:00Z'
});

睡眠データの取得

const sleepData = await callTool('whoop-get-sleep-collection', {
  limit: 5,
  end: '2024-01-31T23:59:59Z'
});

ワークアウトデータの取得

const workouts = await callTool('whoop-get-workout-collection', {
  limit: 10,
  start: '2024-01-01T00:00:00Z'
});

データ型

サーバーは、すべてのWHOOP APIレスポンスに対して包括的なTypeScript型を提供します。

• ユーザーデータ：プロフィール情報、身体測定データ
• サイクル：ストレインスコア、心拍数データ、キロジュール消費量
• 回復：回復スコア、HRV、安静時心拍数、SpO2、皮膚温度
• 睡眠：睡眠段階、パフォーマンス指標、呼吸数、効率
• ワークアウト：活動ストレイン、心拍数ゾーン、距離、高度データ

ページネーション

ほとんどのコレクションエンドポイントは、以下のパラメータでページネーションをサポートしています。

• limit：返すレコード数（最大25）
• start：開始時間フィルター（ISO 8601形式）
• end：終了時間フィルター（ISO 8601形式）
• nextToken：次のページのトークン

エラー処理

MCPサーバーには包括的なエラー処理が組み込まれています。

• 無効な資格情報
• レート制限
• ネットワークエラー
• 無効なパラメータ
• 必須フィールドの欠落

開発

プロジェクト構造

src/
├── index.ts          # メインエントリーポイント
├── mcp-server.ts     # MCPサーバーの実装
├── whoop-api.ts      # WHOOP APIクライアント
└── types.ts          # TypeScript型定義

利用可能なスクリプト

• npm run build - TypeScriptプロジェクトをビルド
• npm start - ビルドされたサーバーを実行
• npm run dev - ホットリロードで開発モードで実行
• npm run watch - 変更を監視して再ビルド

新しいエンドポイントの追加

新しいWHOOP APIエンドポイントを追加するには、以下の手順を実行します。

1. whoop-api.tsのWhoopApiClientにエンドポイントメソッドを追加します。
2. types.tsに対応する型を追加します。
3. mcp-server.tsにツール定義とハンドラーを追加します。

WHOOP APIドキュメント

WHOOP APIの詳細情報については、以下のリンクを参照してください。

• WHOOP開発者プラットフォーム
• WHOOP APIリファレンス

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

サポート

問題や質問については、以下の手順を実行してください。

1. WHOOP APIドキュメントを確認します。
2. MCPサーバーからのエラーメッセージを確認します。
3. OAuthの資格情報が正しく構成されていることを確認します。
4. アクセストークンが有効で期限切れでないことを確認します。

移行通知

重要：WHOOP v2 APIが利用可能になり、2025年10月1日までに移行が必要です。現在のv1 APIとウェブフックはこの日以降削除されます。このMCPサーバーはv2 APIを使用しています。