WHOOP MCP 서버

Claude가 WHOOP의 공식 OAuth 2.0 REST API(v2)를 통해 개인 WHOOP 건강 데이터(회복, 수면, 스트레인, 운동, 프로필)를 조회할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

이 서버를 사용하는 각 사용자는 자신의 WHOOP 계정에 대해 개별 복사본을 실행합니다. WHOOP에 무료 개발자 앱을 직접 등록하고, 토큰/자격 증명은 사용자 컴퓨터의 로컬 파일(gitignored)에만 저장됩니다. 데이터는 사용자 컴퓨터와 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. 빌드 및 로그인 (최초 1회)

npm run build
npm run login

이 명령은 다음을 수행합니다:

1. http://localhost:8080에 임시 로컬 서버를 시작합니다.

2. 브라우저에서 WHOOP 동의 화면을 엽니다(회복, 수면, 주기, 운동, 프로필, 신체 측정, 오프라인/갱신 범위를 요청).

3. 승인 후 WHOOP은 인증 코드와 함께 localhost:8080/callback으로 리디렉션합니다.

4. 스크립트가 해당 코드를 액세스 + 갱신 토큰으로 교환하고 프로젝트 루트의 token.json(gitignored)에 저장합니다.

이 과정은 한 번만 수행하면 됩니다. 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. 한 결과(예: 오늘의 회복 점수)를 WHOOP 앱과 대조하여 숫자가 일치하는지 확인합니다.

도구 참조

네 가지 범위 기반 도구는 days(롤링 윈도우, 예: 지난 주의 경우 days=7) 또는 특정 역사적 기간을 조회하기 위한 명시적 start/end 날짜 쌍(YYYY-MM-DD, 종료일 제외)을 허용합니다(예: 2026년 3월 전체의 경우 start="2026-03-01", end="2026-04-01"). 각 도구는 개별 일일/야간 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(액세스/갱신 토큰)은 모두 gitignored 처리되어 있습니다. 두 파일 모두 커밋하지 마십시오.