Servidor MCP de WHOOP

Un servidor MCP (Protocolo de Contexto del Modelo) que permite a Claude consultar tus datos personales de salud de WHOOP: recuperación, sueño, esfuerzo, entrenamientos y perfil — a través de la API REST oficial OAuth 2.0 de WHOOP (v2).

Cada persona que lo usa ejecuta su propia copia contra su propia cuenta de WHOOP: registras tu propia aplicación de desarrollador gratuita con WHOOP, y tus tokens/credenciales permanecen en archivos locales de tu máquina (ignorados por git) — nada se comparte ni se envía a ningún sitio excepto directamente entre tu máquina y la API de WHOOP.

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

1. Obtener credenciales de la API de WHOOP

1. Ve al Panel de Desarrollador de WHOOP e inicia sesión.

2. Crea (o abre) una aplicación.

3. En la configuración de la API de la aplicación, establece la URI de Redirección exactamente como:

   http://localhost:8080/callback

4. Copia el ID de Cliente y el Secreto de Cliente — los pegarás en .env en el paso 3 a continuación.

Related MCP server: Whoop MCP Server

2. Requisitos previos

• Node.js 18+ (necesario para la API fetch integrada). Verifica con node --version.

3. Instalar y configurar

npm install
cp .env.example .env

Abre .env y pega tu ID de Cliente y Secreto de Cliente del paso 1:

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

⚠️ Debes rellenar manualmente WHOOP_CLIENT_ID y WHOOP_CLIENT_SECRET — el servidor se negará a iniciar cualquier flujo OAuth hasta que estén configurados.

4. Compilar e iniciar sesión (una sola vez)

npm run build
npm run login

Esto:

1. Inicia un servidor local temporal en http://localhost:8080.

2. Abre tu navegador en la pantalla de consentimiento de WHOOP (solicitando los ámbitos de recuperación, sueño, ciclo, entrenamiento, perfil, medición corporal y offline/refresco).

3. Después de que apruebes, WHOOP redirige de vuelta a localhost:8080/callback con un código de autorización.

4. El script intercambia ese código por un token de acceso + de actualización y los guarda en token.json (ignorado por git) en la raíz del proyecto.

Solo necesitas hacer esto una vez. El servidor MCP actualiza automáticamente el token de acceso usando el token de actualización cuando caduca (los tokens de acceso de WHOOP duran aproximadamente 1 hora). Si tu token de actualización alguna vez se revoca o caduca, simplemente vuelve a ejecutar npm run login.

5. Conectar a Claude Desktop

Abre tu archivo de configuración de 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

Nota: si instalaste Claude Desktop desde Microsoft Store, el archivo anterior puede ser solo un marcador de posición — la aplicación realmente lee %LOCALAPPDATA%\Packages\<carpeta del paquete Claude>\LocalCache\Roaming\Claude\claude_desktop_config.json. Si las herramientas no aparecen después de seguir los pasos a continuación, verifica allí.

Añade una entrada whoop bajo mcpServers. Reemplaza la ruta a continuación con la ruta absoluta a este proyecto dist/server.js en tu máquina (encuéntrala con pwd en macOS/Linux o cd en Windows desde dentro de la carpeta del proyecto):

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

⚠️ Debes rellenar manualmente esta ruta absoluta hasta donde hayas clonado este repositorio. Usa barras inclinadas incluso en Windows (ej. C:/Users/tu/whoop-mcp/dist/server.js) — funcionan bien dentro de este archivo JSON.

Luego reinicia completamente Claude Desktop (sal de la bandeja del sistema, no solo cierres la ventana).

6. Probarlo

1. En Claude Desktop, haz clic en el icono de herramientas/martillo en el cuadro de chat y confirma que ves whoop con 6 herramientas listadas: get_recovery, get_sleep, get_strain, get_workouts, get_profile, get_training_recommendation.

2. Prueba estos mensajes:

   • "¿Cómo fue mi recuperación esta semana?"

   • "¿Debería entrenar fuerte hoy?"

   • "¿Cómo dormí las últimas 3 noches?"

   • "Muéstrame mis entrenamientos de los últimos 7 días."

   • "¿Cuál es mi esfuerzo actual y cómo se compara con ayer?"

   • "¿Cuál fue mi esfuerzo promedio en marzo de 2026?" (rango histórico, no solo "últimos N días")

3. Verifica un resultado (ej. la puntuación de recuperación de hoy) contra la aplicación de WHOOP para confirmar que los números coinciden.

Referencia de herramientas

Las cuatro herramientas basadas en rangos aceptan ya sea días (ventana móvil, ej. días=7 para la última semana) o un par explícito de fechas inicio/fin (AAAA-MM-DD, fin exclusivo) para consultar un período histórico específico, ej. inicio="2026-03-01", fin="2026-04-01" para todo marzo de 2026. Cada una devuelve un objeto resumen (promedios/totales) junto con los registros diarios/nocturnos individuales.

Solución de problemas

• "No se encontraron tokens de WHOOP" — ejecuta npm run login.

• Errores 401 / de token después de haber funcionado antes — el servidor actualiza automáticamente los tokens de acceso; si ves un fallo de actualización, es probable que tu token de actualización haya sido revocado (ej. eliminaste el acceso de la aplicación en la configuración de WHOOP). Vuelve a ejecutar npm run login.

• 403 Prohibido — a tu token le falta un ámbito. Los ámbitos se fijan al iniciar sesión, así que vuelve a ejecutar npm run login para obtener un token nuevo con el conjunto completo de ámbitos.

• 429 Demasiadas solicitudes — has alcanzado el límite de velocidad de WHOOP (100 solicitudes/minuto, 10,000/día). Espera e inténtalo de nuevo.

• Las herramientas no aparecen en Claude Desktop — verifica la ruta absoluta en claude_desktop_config.json, que ejecutaste npm run build (la configuración apunta a dist/server.js, no a src/server.ts), y que reiniciaste completamente Claude Desktop.

Estructura del proyecto

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

Tanto .env (credenciales) como token.json (tokens de acceso/actualización) están ignorados por git — nunca confirmes ninguno de los dos archivos.