Skip to main content
Glama

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

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 앱과 대조하여 숫자가 일치하는지 확인합니다.

도구 참조

도구

설명

get_recovery(days | start+end)

회복 점수, HRV, 안정 시 심박수, SpO2, 피부 온도 — 평균 요약 포함

get_sleep(days | start+end)

수면 성능 %, 효율 %, 단계별 분석(얕은/깊은/REM) — 평균 요약 포함

get_strain(days | start+end)

일일 스트레인, 평균/최대 심박수, 일일 칼로리 — 평균/총계 요약 포함

get_workouts(days | start+end)

기록된 운동(종목, 시간, 스트레인, 심박수, 칼로리) — 요약 포함

get_profile()

이름, 이메일, 키, 몸무게, 최대 심박수

get_training_recommendation()

오늘의 회복 + 지난 3일간의 수면을 결합하여 초록/노랑/빨강 훈련 권장 사항 제공, 2일 이상 성능이 80% 미만인 경우 수면 부채 경고 포함

네 가지 범위 기반 도구는 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 처리되어 있습니다. 두 파일 모두 커밋하지 마십시오.

Available Tools

6 tools
get_profileA

Get the WHOOP user's basic profile: name, email, height (cm), weight (kg), and max heart rate. Use this for identity or body-metric questions.

Inputs: no named parameters.

get_recoveryA

Get WHOOP recovery data: recovery score (0-100), HRV (ms), resting heart rate, SpO2, and skin temperature, per day. Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary with averages plus the daily records. Use this to answer questions about how recovered/rested the user is, now or in the past.

Inputs: end, days, start.

get_sleepA

Get WHOOP sleep data: sleep performance %, efficiency %, time in bed, time asleep, and a breakdown of light/deep/REM sleep stages, per night (excludes naps). Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary with averages plus the nightly records. Use this to answer questions about sleep quality or duration, now or in the past.

Inputs: end, days, start.

get_strainA

Get WHOOP daily strain data: cardiovascular strain score (0-21), average/max heart rate, and calories burned, per day (cycle). Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary with averages/totals plus the daily records. Use this to answer questions about daily exertion or workload, now or in the past — including things like 'what was my average strain in March'.

Inputs: end, days, start.

get_training_recommendationA

Get a coaching recommendation for today based on today's WHOOP recovery score and the last 3 days of sleep performance. Returns a recovery band (green/yellow/red) with guidance on training load, plus a warning if sleep debt has been building. Use this to answer 'should I train today' or 'how hard should I push today' style questions.

Inputs: no named parameters.

get_workoutsA

Get a list of logged WHOOP workouts, each with sport type, duration, strain, average/max heart rate, and calories burned. Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary plus the individual workout records. Use this to answer questions about specific exercise sessions, now or in the past.

Inputs: end, days, start.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool addresses a distinct WHOOP domain (recovery, sleep, strain, workouts, profile, training recommendation) with no overlap. The descriptions clearly differentiate the data each returns, making it easy for an agent to select the correct tool for a given question.

    Naming Consistency4/5

    All tool names follow a consistent 'get_' prefix with a noun representing the data type (recovery, sleep, strain, etc.). This is predictable and clear. The only minor deviation is the slightly longer 'get_training_recommendation' compared to the others, but it still fits the pattern.

    Tool Count5/5

    With 6 tools, the set is well-scoped for a WHOOP fitness tracker integration. Each tool represents a core data category a user would query, and there are no extraneous or missing tools that would make the surface too large or too small for the domain.

    Completeness4/5

    The tools cover the most common queries about WHOOP data: recovery, sleep, strain, workouts, profile, and training recommendations. A minor gap is the lack of tools to query cycle/physiological data, meal logging, or team features, but the core personal health metrics are well represented.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers