🏃 WHOOP MCP 서버

모델 컨텍스트 프로토콜(MCP)을 통해 WHOOP 피트니스 데이터를 Claude Desktop에 연결하세요.

Claude Desktop에서 자연어 쿼리를 통해 WHOOP 피트니스 데이터를 실행 가능한 인사이트로 변환하세요. 데이터의 보안과 프라이버시를 유지하면서 운동, 회복, 수면 패턴 등에 대해 질문할 수 있습니다.

🚀 신규: 설정이 필요 없는 Smithery 호스팅 버전을 사용해 보세요!

✨ 주요 기능

🔐 안전한 OAuth 통합 - 암호화된 로컬 저장소를 통한 안전한 WHOOP 계정 연결 🏃 전체 데이터 액세스 - 운동, 회복, 수면, 주기 및 프로필 정보 🤖 자연어 쿼리 - 평이한 영어로 Claude에게 피트니스 데이터 질문 ⚡ 스마트 캐싱 - 지능형 데이터 캐싱을 통한 최적화된 성능 🛡️ 개인정보 보호 우선 - 모든 데이터는 로컬 기기에 머물며 제3자에게 전송되지 않음 🔄 자동 토큰 갱신 - 자동 인증 갱신으로 끊김 없는 경험 제공

Related MCP server: Whoop MCP Server

🚀 빠른 시작

🎯 배포 방법 선택

옵션 A: Smithery 호스팅 (초보자 권장)

• ✅ 설치 복잡성 없음

• ✅ 자동 업데이트 및 유지보수

• ✅ 엔터프라이즈급 호스팅

• ➡️ Smithery 시작하기

옵션 B: 로컬 설치 (고급 사용자)

• ✅ 완전한 제어 및 프라이버시

• ✅ 외부 의존성 없음

• ✅ 사용자 정의 및 확장 가능

• ➡️ 아래 로컬 설정 계속하기

📦 로컬 설치

1. 사전 요구 사항

• Python 3.8+

• Claude Desktop

• 활성화된 WHOOP 계정

2. 설치

git clone https://github.com/romanevstigneev/whoop-mcp-server.git
cd whoop-mcp-server
pip install -r requirements.txt

3. 설정

옵션 A: 대화형 설정 (권장)

대화형 설정을 실행합니다:

python setup.py

이 과정은 다음을 수행합니다:

• WHOOP OAuth 인증을 위해 브라우저를 엽니다.

• 토큰을 로컬에 안전하게 저장합니다.

• Claude Desktop 구성을 제공합니다.

옵션 B: 수동 WHOOP OAuth 설정

대화형 설정이 작동하지 않는 경우, 수동으로 WHOOP 토큰을 얻을 수 있습니다:

1. WHOOP OAuth 페이지 열기: 👉 여기를 클릭하여 WHOOP 액세스 권한 부여

2. 계정 권한 부여:

   • WHOOP 자격 증명으로 로그인합니다.

   • 요청된 범위에 대한 권한을 부여합니다:

     • read:profile - 프로필 정보 액세스

     • read:workout - 운동 데이터 액세스

     • read:recovery - 회복 데이터 액세스

     • read:sleep - 수면 데이터 액세스

     • offline - 지속적인 액세스를 위한 리프레시 토큰

3. 인증 코드 복사:

   • 인증 후 성공 페이지가 표시됩니다.

   • 전체 인증 코드를 복사하세요 (문자/숫자로 시작하는 긴 문자열)

   • 예시: ABC123...XYZ789 (훨씬 더 깁니다)

4. 토큰으로 코드 교환:

   python -c "
   import sys
   sys.path.insert(0, './src')
   from auth_manager import TokenManager
   import requests
   
   # Paste your authorization code here
   auth_code = 'YOUR_AUTHORIZATION_CODE_HERE'
   
   # Exchange for tokens
   url = f'https://personal-integrations-462307.uc.r.appspot.com/api/get-tokens/{auth_code}'
   response = requests.get(url, timeout=30)
   
   if response.status_code == 200:
       token_data = response.json()
       if token_data.get('success'):
           # Save tokens
           token_manager = TokenManager()
           token_manager.save_tokens(token_data)
           print('✅ Tokens saved successfully!')
       else:
           print('❌ Token exchange failed')
   else:
       print(f'❌ HTTP Error: {response.status_code}')
   "

5. 설정 확인:

   python -c "
   import sys
   sys.path.insert(0, './src')
   from whoop_client import WhoopClient
   client = WhoopClient()
   print(f'✅ Auth status: {client.get_auth_status()}')
   "

4. Claude Desktop 구성

Claude Desktop 설정에 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "whoop": {
      "command": "/opt/miniconda3/bin/python",
      "args": ["/path/to/whoop-mcp-server/src/whoop_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/whoop-mcp-server/src"
      }
    }
  }
}

⚠️ 중요: 전체 Python 경로를 사용하세요 (which python3로 확인 가능)

5. Claude Desktop 재시작

구성을 추가한 후, Claude Desktop을 재시작하여 WHOOP 서버를 로드하세요.

💡 사용 예시

설정이 완료되면 Claude에게 다음과 같이 물어볼 수 있습니다:

• "Show my WHOOP profile"

• "What were my workouts this week?"

• "How is my recovery trending?"

• "Show my sleep data for the last 7 days"

• "What's my HRV looking like?"

• "Compare my recovery to last month"

🛠️ 사용 가능한 도구

get_whoop_profile

WHOOP 사용자 프로필 정보를 가져옵니다.

get_whoop_workouts

선택적 필터를 사용하여 운동 데이터를 가져옵니다:

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (결과 개수)

get_whoop_recovery

선택적 필터를 사용하여 회복 데이터를 가져옵니다:

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (결과 개수)

get_whoop_sleep

선택적 필터를 사용하여 수면 데이터를 가져옵니다:

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (결과 개수)

get_whoop_cycles

선택적 필터를 사용하여 생리학적 주기(일일 데이터)를 가져옵니다:

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (결과 개수)

get_whoop_auth_status

인증 상태 및 토큰 정보를 확인합니다.

clear_whoop_cache

캐시된 데이터를 지우고 새로운 API 호출을 강제합니다.

🔐 보안

• 토큰 암호화: 모든 토큰은 AES 암호화를 사용하여 저장 시 암호화됩니다.

• 로컬 저장소: 토큰은 로컬 기기에 저장되며 제3자에게 전송되지 않습니다.

• 보안 권한: 토큰 파일은 제한된 권한(600)을 가집니다.

• 자동 갱신: 토큰은 만료 시 자동으로 갱신됩니다.

📊 데이터 캐싱

• 스마트 캐싱: 성능 향상을 위해 API 응답은 5분 동안 캐시됩니다.

• 속도 제한: WHOOP API 제한을 준수하기 위한 내장 속도 제한 기능이 있습니다.

• 캐시 제어: 수동 캐시 삭제가 가능합니다.

🔧 구성

환경 변수 (선택 사항):

• LOG_LEVEL: 로깅 레벨 (DEBUG, INFO, WARNING, ERROR)

• LOG_FILE: 로그 파일 경로 (기본값: 콘솔 전용)

🆚 배포 비교

📁 파일 구조

whoop-mcp-server/
├── src/                       # Python local installation
│   ├── whoop_mcp_server.py    # Main MCP server
│   ├── whoop_client.py        # WHOOP API client
│   ├── auth_manager.py        # Token management
│   └── config.py              # Configuration
├── smithery/                  # TypeScript source files
│   └── src/
│       ├── index.ts           # Smithery MCP server
│       ├── whoop-client.ts    # TypeScript WHOOP client
│       └── types.ts           # Type definitions
├── storage/                   # Local installation only
│   ├── tokens.json            # Encrypted tokens (auto-generated)
│   └── .encryption_key        # Encryption key (auto-generated)
├── package.json               # Node.js dependencies (Smithery)
├── smithery.yaml              # Smithery configuration (root required)
├── tsconfig.json              # TypeScript configuration
├── setup.py                   # Interactive setup script
└── requirements.txt           # Python dependencies

🐛 문제 해결

"No valid access token available"

• python setup.py를 실행하여 다시 인증하세요.

• WHOOP 계정이 활성화되어 있는지 확인하세요.

"Authentication failed"

• 토큰이 갱신 범위를 넘어 만료되었을 수 있습니다.

• python setup.py를 실행하여 새 토큰을 받으세요.

"Rate limit exceeded"

• 요청을 더 보내기 전에 잠시 기다리세요.

• 캐시된 데이터를 사용하거나 요청 빈도를 줄이는 것을 고려하세요.

Claude Desktop이 서버를 인식하지 못함

• 전체 Python 경로 사용: "command": "python"을 "command": "/opt/miniconda3/bin/python"으로 변경하세요 (which python3로 확인).

• 올바른 구성 파일 확인: ~/Library/Application Support/Claude/claude_desktop_config.json을 편집하세요 (.claude.json이 아님).

• 절대 경로 사용: /Users/username/whoop-mcp-server/src/whoop_mcp_server.py와 같은 전체 경로를 사용하세요.

• 로그 확인: tail -f ~/Library/Logs/Claude/mcp-server-whoop.log

• 구성 변경 후 Claude Desktop을 재시작하세요.

🔄 토큰 갱신

서버는 리프레시 토큰을 사용하여 만료된 토큰을 자동으로 갱신합니다. 실패할 경우 다시 인증해야 합니다:

python setup.py

📝 로깅

로그는 기본적으로 콘솔에 기록됩니다. 파일로 기록하려면:

export LOG_FILE="/path/to/whoop-mcp.log"
export LOG_LEVEL="INFO"

🤝 기여

1. 저장소를 포크하세요.

2. 기능 브랜치를 만드세요.

3. 변경 사항을 적용하세요.

4. 해당되는 경우 테스트를 추가하세요.

5. 풀 리퀘스트를 제출하세요.

📄 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.

⚠️ 면책 조항

이것은 WHOOP과의 비공식 통합입니다. 공식 WHOOP API를 사용하지만 WHOOP의 보증을 받지 않습니다.

📞 지원

• 위의 문제 해결 섹션을 확인하세요.

• GitHub에 이슈를 제기하세요.

• https://developer.whoop.com/ 에서 WHOOP API 문서를 검토하세요.

🎯 로드맵

• [ ] 과거 데이터 분석

• [ ] 사용자 지정 날짜 범위 쿼리

• [ ] 데이터 내보내기 기능

• [ ] 실시간 업데이트를 위한 웹훅 지원

• [ ] 고급 분석 및 인사이트