Withings

Servidor MCP para la integración de datos de salud de Withings

GitHub
44

Documentación

Servidor MCP de Withings

Ayúdame a pagar los servidores en Patreon

Quality Gate Status Bugs Code Smells Lines of Code Reliability Rating Security Rating Maintainability Rating Vulnerabilities

Un servidor de Protocolo de Contexto de Modelo (MCP) que lleva tus datos de salud de Withings a Claude. Accede a tus patrones de sueño, mediciones corporales, entrenamientos, datos cardíacos y más mediante conversación natural.

🔒 Privacidad Primero: Este es mi proyecto personal, y el repositorio es intencionalmente público para demostrar transparencia. El código muestra que no se registra ni almacena información personal de forma maliciosa. Todos los datos sensibles (tokens, IDs de usuario) están cifrados en reposo y se redactan automáticamente de los registros. Puedes revisar todo el código base para verificar este compromiso con la privacidad.

⚠️ Aviso Legal: Este servidor se proporciona tal cual sin garantías ni warranties. Aunque he hecho todo lo posible por garantizar la seguridad y la privacidad, no ofrezco garantías sobre disponibilidad, integridad de datos o seguridad. Úsalo bajo tu propio riesgo. Para casos de uso en producción, considera alojar tu propia instancia.

Configuración Rápida

  1. Abre Claude Desktop → Personalizar → Conectores
  2. Haz clic en + → Agregar Conector Personalizado
  3. Establece la URL a https://withings-mcp.com/mcp → haz clic en Agregar
  4. Haz clic en Conectar y autoriza con tu cuenta de Withings

¡Eso es todo! Pregúntale a Claude sobre tu sueño, peso, entrenamientos o datos cardíacos.

Demo

Demo

Tabla de Contenidos

¿Qué Puedes Hacer Con Esto?

Este servidor MCP le da a Claude acceso a tus datos de salud de Withings, permitiéndote:

  • Analizar tu sueño: Pregunta sobre calidad del sueño, duración, etapas de sueño profundo, frecuencia cardíaca durante el sueño
  • Rastrear métricas corporales: Tendencias de peso, composición corporal, presión arterial, frecuencia cardíaca a lo largo del tiempo
  • Revisar entrenamientos: Analiza patrones de ejercicio, calorías quemadas, zonas de frecuencia cardíaca
  • Monitorear la salud cardíaca: Accede a grabaciones de ECG y datos cardíacos detallados
  • Establecer y rastrear metas: Revisa tus metas de fitness y salud
  • Identificar patrones: Encuentra correlaciones entre sueño, actividad y otras métricas
  • Generar información: Obtén análisis impulsados por IA de tus tendencias de salud

Todo a través de conversación natural con Claude o cualquier otro cliente compatible con MCP.

Para Usuarios Finales: Usar el Servidor Alojado

Si solo quieres usar este servidor MCP con Claude Desktop sin alojar nada tú mismo, sigue estos pasos:

Requisitos Previos

  1. Una cuenta de Withings con dispositivos conectados
  2. Claude Desktop o cualquier otro cliente compatible con MCP instalado en tu computadora

Instrucciones de Configuración

Paso 1: Agregar Conector en Claude Desktop

  1. Abre Claude Desktop
  2. Ve a Personalizar (en la barra lateral o menú)
  3. Navega a la sección Conectores
  4. Haz clic en el botón + para agregar un nuevo conector
  5. Selecciona Agregar Conector Personalizado
  6. Completa los siguientes detalles:
    • Nombre: Withings (o cualquier nombre que prefieras)
    • URL del servidor MCP remoto: https://withings-mcp.com/mcp
  7. Haz clic en Agregar

Nota: Si tu cliente MCP no admite la configuración de conectores basada en interfaz, puedes editar manualmente el archivo de configuración. Consulta la guía de configuración manual a continuación.

Paso 2: Conectar y Autorizar

  1. En la configuración de Conectores, encuentra el conector de Withings que acabas de agregar
  2. Haz clic en Conectar junto al conector
  3. Tu navegador web se abrirá con la página de autorización de Withings
  4. Inicia sesión en tu cuenta de Withings
  5. Revisa y aprueba los permisos solicitados
  6. Serás redirigido de vuelta y la conexión estará completa

¡Después de la autorización, Claude tendrá acceso a tus datos de Withings!

Herramientas Disponibles

Una vez conectado, Claude puede usar estas herramientas para acceder a tus datos:

Sueño y Actividad

  • get_hrv - RMSSD, SDNN y puntuaciones de calidad a nivel de minuto capturados durante el sueño
  • get_sleep_summary - Duración del sueño, etapas (ligero/profundo/REM), frecuencia cardíaca, respiración, puntuación de sueño
  • get_activity - Pasos diarios, distancia, calorías, elevación, duraciones de actividad
  • get_intraday_activity - Datos de actividad de alta frecuencia a lo largo del día
  • get_workouts - Resúmenes detallados de entrenamientos con zonas de frecuencia cardíaca y métricas

Mediciones Corporales

  • get_measures - Peso, composición corporal, presión arterial, frecuencia cardíaca, temperatura, VO2 máx y más

Dispositivos y Metas

  • get_user_devices - Lista de dispositivos Withings conectados
  • get_user_goals - Tus metas de salud y fitness (pasos, sueño, peso)

Salud Cardíaca

  • list_heart_records - Lista de grabaciones de ECG
  • get_heart_signal - Datos detallados de forma de onda de ECG

Estetoscopio (si tienes BPM Core)

  • list_stetho_records - Lista de grabaciones de estetoscopio
  • get_stetho_signal - Datos detallados de señal de audio

Ejemplos de Conversaciones

Prueba preguntarle a Claude:

  • "¿Cómo ha sido la calidad de mi sueño durante la última semana?"
  • "Muéstrame mi tendencia de peso del último mes"
  • "¿Cuál es mi frecuencia cardíaca en reposo promedio?"
  • "¿Alcancé mi meta de pasos esta semana?"
  • "Compara la intensidad de mis entrenamientos entre este mes y el pasado"
  • "¿Cuándo dormí mejor este mes?"

Privacidad y Seguridad

  • Tokens cifrados: Todos los tokens de autenticación y códigos de autorización se cifran usando AES-256-GCM antes del almacenamiento
  • Sin registro de datos personales: El código es público: puedes verificar que no se registra información sensible
  • Redacción automática: Todos los IDs de usuario, tokens y credenciales se redactan automáticamente de los registros del sistema
  • OAuth 2.0: Autenticación segura estándar de la industria con soporte PKCE y validación de URI de redirección
  • Seguridad de sesión: Las sesiones MCP están vinculadas al usuario autenticado, evitando el acceso entre usuarios
  • Tú tienes el control: Revoca el acceso en cualquier momento desde la configuración de tu cuenta de Withings

Para Desarrolladores: Autoalojamiento

¿Quieres ejecutar tu propia instancia? Así es como puedes desplegar este servidor MCP tú mismo.

Requisitos Previos

  1. Bun 1.1+ instalado
  2. Una Cuenta de Desarrollador de Withings

Paso 1: Crear Aplicación de Withings

  1. Ve al Portal de Desarrolladores de Withings
  2. Crea una nueva aplicación
  3. Anota tu ID de Cliente y Secreto de Cliente
  4. Establece tu URI de Redirección a: https://your-domain.com/callback
    • Esto debe ser una URL públicamente accesible (localhost no es compatible con Withings)
    • Puede ser cualquier dominio donde alojarás el servidor (por ejemplo, Fly.io, Railway, tu propio servidor, etc.)

Importante: Eliminar Google Analytics

La versión alojada incluye una etiqueta de Google Analytics (G-ZMGF9WXL3W) en las páginas estáticas bajo public/. Si estás bifurcando este repositorio, elimina o reemplaza el fragmento de GA en public/index.html y public/health.html, y actualiza los encabezados CSP en src/server/app.ts en consecuencia.

Paso 2: Clonar y Configurar

# Clone the repository
git clone https://github.com/your-username/withings-mcp.git
cd withings-mcp

# Install dependencies
bun install

# Generate encryption secret
bun run generate-secret
# Copy the output - you'll need it for environment variables

Paso 2.5: Configurar Base de Datos Supabase

  1. Crea un proyecto gratuito en Supabase
  2. Instala la CLI de Supabase: bun install -g supabase (o usa brew install supabase/tap/supabase)
  3. Vincula tu proyecto: supabase link --project-ref <your-project-ref>
  4. Aplica las migraciones de base de datos: supabase db push
  5. Obtén tus credenciales de Panel → Configuración → API:
    • URL del Proyecto → SUPABASE_URL
    • Clave de rol de servicio → SUPABASE_SECRET_KEY

Paso 3: Desarrollo Local

Nota: Withings requiere una URL públicamente accesible para las devoluciones de llamada OAuth. Para desarrollo local, usa un servicio de túnel para exponer tu servidor local o despliega a un entorno de pruebas para probar.

# Copy environment template
cp .env.example .env

# Edit .env with your values
# WITHINGS_CLIENT_ID=your_client_id
# WITHINGS_CLIENT_SECRET=your_client_secret
# WITHINGS_REDIRECT_URI=https://your-tunnel-url.com/callback
# ENCRYPTION_SECRET=paste_generated_secret_here
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_SECRET_KEY=your_service_role_key
# PORT=3000

# Run locally (Bun executes TypeScript directly — no build step)
bun run dev

Asegúrate de que tu URI de redirección en el archivo .env coincida con la URL públicamente accesible que apunta a tu servidor local.

Paso 4: Desplegar a Producción

# The project runs TypeScript directly with Bun — no build step required.
bun run start

Despliega en Plataforma de Aplicaciones de DigitalOcean (su buildpack de Bun detecta package.json y ejecuta bun run start automáticamente), o cualquier otro host que admita Bun.

Establece las siguientes variables de entorno en tu plataforma de alojamiento:

VariableRequeridaEjemplo
WITHINGS_CLIENT_IDSíyour_client_id
WITHINGS_CLIENT_SECRETSíyour_client_secret
WITHINGS_REDIRECT_URISíhttps://your-domain.com/callback
ENCRYPTION_SECRETSíGenerada desde el paso 2
SUPABASE_URLSíhttps://your-project.supabase.co
SUPABASE_SECRET_KEYSíTu clave de rol de servicio de Supabase
PORTNo3000 (o el predeterminado de tu plataforma)
LOG_LEVELNoinfo
ALLOWED_ORIGINSNohttps://example.com,https://app.example.com

Paso 5: Actualizar Configuración de la App de Withings

Vuelve a tu aplicación de desarrollador de Withings y actualiza la URI de redirección para que coincida con tu URL desplegada: https://your-domain.com/callback

Paso 6: Configurar Tu Cliente MCP

Para Claude Desktop:

  1. Abre Claude Desktop
  2. Ve a Personalizar → sección Conectores
  3. Haz clic en el botón +, luego selecciona Agregar Conector Personalizado
  4. Completa los siguientes detalles:
    • Nombre: Withings (o cualquier nombre que prefieras)
    • URL del servidor MCP remoto: https://your-domain.com/mcp
  5. Haz clic en Agregar
  6. Haz clic en Conectar junto al conector para autorizar

Para Otros Clientes MCP:

Configura tu cliente MCP con los siguientes detalles de conexión:

  • URL del servidor: https://your-domain.com
  • Transporte: HTTP Transmisible
  • Endpoint: /mcp
  • Autenticación: OAuth 2.0
  • URL de descubrimiento: /.well-known/oauth-authorization-server

Referencia de Variables de Entorno

VariableRequeridaDescripción
WITHINGS_CLIENT_IDSíTu ID de cliente de la aplicación de Withings
WITHINGS_CLIENT_SECRETSíTu secreto de cliente de la aplicación de Withings
WITHINGS_REDIRECT_URISíURL de devolución de llamada OAuth (debe coincidir con la configuración de la app de Withings)
ENCRYPTION_SECRETSíSecreto de 32+ caracteres para cifrado de tokens (genera con bun run generate-secret)
SUPABASE_URLSíURL de tu proyecto Supabase (de Panel → Configuración → API)
SUPABASE_SECRET_KEYSíTu clave de rol de servicio de Supabase (de Panel → Configuración → API)
PORTNoPuerto del servidor (predeterminado: 3000)
LOG_LEVELNoNivel de registro: trace, debug, info, warn, error (predeterminado: info)
ALLOWED_ORIGINSNoLista separada por comas de orígenes CORS permitidos para clientes de navegador

Comandos de Desarrollo

bun run start            # Run the server
bun run dev              # Hot-reload mode
bun run typecheck        # Type-check with tsc (no emit)
bun run build            # Bundle for production (outputs to ./build)
bun run generate-secret  # Generate encryption secret for ENCRYPTION_SECRET env variable

Estructura del Proyecto

src/
├── auth/              # OAuth 2.0 authentication & token storage
├── db/                # Supabase client & cleanup scheduler
├── server/            # Hono app, MCP endpoints, middleware
├── tools/             # MCP tools for Withings API (sleep, measure, user, heart, stetho)
├── types/             # TypeScript type definitions (Hono, Withings API)
├── withings/          # Withings API client
├── utils/             # Logger and encryption utilities
└── index.ts           # Main entry point

supabase/
└── migrations/        # Database schema migrations

Consulta CLAUDE.md para documentación detallada de arquitectura.

Características de Seguridad

Cifrado de Tokens

Todos los tokens de acceso de Withings, tokens de actualización y códigos de autorización se cifran en reposo usando AES-256-GCM:

  • Algoritmo: AES-256-GCM (cifrado autenticado)
  • Derivación de clave: PBKDF2 con 100,000 iteraciones
  • Defensa en profundidad: Incluso si la base de datos se ve comprometida, los tokens permanecen protegidos Importante: Mantén tu ENCRYPTION_SECRET:
  • Al menos 32 caracteres de longitud
  • Generado aleatoriamente (usa bun run generate-secret)
  • Seguro y nunca comprometido en el control de versiones
  • Consistente entre reinicios del servidor

Endurecimiento de OAuth

  • Validación de URI de redirección: El endpoint /authorize valida redirect_uri contra las URI permitidas del cliente registrado, previniendo ataques de redirección abierta
  • Códigos de autorización de un solo uso: Los códigos de autorización se consumen atómicamente para prevenir ataques de reproducción (según RFC 6749)
  • Soporte PKCE: Método de desafío de código SHA-256 para mayor seguridad
  • Validación de inicio: El servidor se niega a iniciar si faltan variables de entorno requeridas

Seguridad del Transporte

  • Vinculación de token de sesión: Las sesiones MCP están vinculadas al token portador que las creó, previniendo el secuestro de sesiones entre usuarios
  • Validación JSON-RPC: Todos los mensajes entrantes se validan contra la especificación JSON-RPC 2.0 antes de procesarse
  • Límites del cuerpo de solicitud: Límite global de 1MB para prevenir el agotamiento de memoria
  • Redirección HTTPS: Las solicitudes HTTP se redirigen automáticamente a HTTPS en producción
  • CSP estricto: Política de Seguridad de Contenido sin directivas unsafe-inline
  • Limitación de tasa atómica: La función de PostgreSQL con bloqueo a nivel de fila previene condiciones de carrera

Registro Seguro para la Privacidad

El registrador personalizado redacta automáticamente toda la información sensible:

  • ✅ Eventos operativos y errores registrados
  • ❌ Sin tokens, credenciales o códigos de autorización
  • ❌ Sin IDs de usuario o información personal
  • ❌ Sin cargas útiles de solicitudes/respuestas de API con datos sensibles

Puedes revisar la implementación del registro en src/utils/logger.ts.

Contribuciones

Este es un proyecto personal, ¡pero las contribuciones son bienvenidas! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Envía una solicitud de extracción

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Soporte

Agradecimientos

Construido con: