Ultrahuman

Obtén métricas de salud y fitness como frecuencia cardíaca, sueño y pasos desde la API de Ultrahuman.

GitHub
21

Documentación

Servidor MCP de Ultrahuman

Un servidor de Protocolo de Contexto de Modelo (MCP) para obtener métricas de salud y estado físico de la API de Ultrahuman. Construido con TypeScript y diseñado para uso en producción.

🚀 Inicio Rápido

  1. Clona el repositorio
  2. Instala las dependencias: 
    bun install
  3. Compila el proyecto: 
    bun run build
  4. Configura tus variables de entorno (consulta la sección de Configuración)
  5. Añádelo a Claude Desktop (consulta la sección de Uso)

🔑 Primeros pasos con la API de Ultrahuman

Antes de poder usar este servidor MCP, necesitarás obtener tus credenciales de Ultrahuman. Sigue estos pasos:

Paso 1: Obtén tu correo electrónico de Ultrahuman

  1. Abre la aplicación de Ultrahuman en tu dispositivo
  2. Navega a la pestaña Perfil en la parte inferior de la pantalla
  3. Toca el icono de configuración (icono de engranaje) en la esquina superior izquierda
  4. Tu dirección de correo electrónico se mostrará en la parte superior de la pantalla de configuración
  5. Copia esta dirección de correo electrónico: la necesitarás para la configuración

Paso 2: Solicita la clave de API y el ID de socio

Debes obtener una clave de API y un ID de socio de Ultrahuman contactándolos a través de uno de estos métodos:

  • Correo electrónico: Envía una solicitud a support@ultrahuman.com
  • Chat en la aplicación: Usa el chat de atención al cliente dentro de la aplicación de Ultrahuman

Importante: Asegúrate de incluir tu dirección de correo electrónico de Ultrahuman en tu solicitud para acelerar el tiempo de respuesta.

Una vez que recibas tu clave de API y tu ID de socio, mantenlos seguros y privados.

Paso 3: Configura el ID de socio en la aplicación

  1. Abre la aplicación de Ultrahuman en tu dispositivo
  2. Navega a la pestaña Perfil en la parte inferior de la pantalla
  3. Toca el icono de configuración (icono de engranaje) en la esquina superior izquierda
  4. Desplázate hacia abajo para encontrar el campo ID de socio
  5. Ingresa el código de ID de socio que recibiste de Ultrahuman

Paso 4: Configura el servidor MCP

Ahora puedes configurar este servidor MCP con tus credenciales:

  1. Configura tus variables de entorno (consulta la sección de Configuración a continuación)
  2. Compila y ejecuta el servidor
  3. Añádelo a Claude Desktop con tus credenciales de API

¡Estás listo para comenzar a obtener tus datos de salud!

✨ Características principales

  • Obtén métricas de salud completas de la API de Ultrahuman
  • Monitoreo de frecuencia cardíaca, sueño, pasos, temperatura y VFC (variabilidad de la frecuencia cardíaca)
  • Construido con TypeScript para seguridad de tipos
  • Bun para pruebas y desarrollo rápidos
  • Biome para linting y formateo
  • Estructura de proyecto limpia y mantenible

📂 Estructura del proyecto

ultrahuman-mcp/
├── src/
│   ├── tools/          # MCP tools implementation
│   │   └── ultrahumanMetrics/  # Ultrahuman API integration
│   ├── utils/          # Shared utilities
│   ├── main.ts         # Server entry point
│   └── types.ts        # Shared type definitions
├── scripts/            # Build and utility scripts
├── biome.json          # Linting configuration
├── tsconfig.json       # TypeScript configuration
└── package.json        # Project dependencies

⚙️ Configuración

Este servidor requiere variables de entorno para autenticarse con la API de Ultrahuman:

  • ULTRAHUMAN_AUTH_TOKEN: Tu token de autorización de la API de Ultrahuman
  • ULTRAHUMAN_USER_EMAIL: La dirección de correo electrónico del usuario de Ultrahuman cuyos datos deseas obtener

La URL base de la API está configurada en https://partner.ultrahuman.com/api/v1.

🔧 Herramientas disponibles

ultrahuman_metrics

Obtiene métricas de salud y estado físico de la API de Ultrahuman para una fecha específica. El correo electrónico del usuario se configura mediante una variable de entorno, por lo que solo necesitas especificar la fecha para recuperar datos de salud completos.

Parámetros:

  • date: Fecha en formato AAAA-MM-DD para obtener métricas (por ejemplo, '2025-06-19')

Ejemplo de uso:

{
  "name": "ultrahuman_metrics",
  "arguments": {
    "date": "2025-06-19"
  }
}

📊 Datos de salud disponibles

La API proporciona métricas de salud completas que incluyen:

  • Frecuencia cardíaca: Monitoreo continuo de la frecuencia cardíaca con marcas de tiempo
  • Temperatura de la piel: Variaciones de la temperatura corporal a lo largo del día
  • VFC (Variabilidad de la frecuencia cardíaca): Mediciones de la variabilidad de la frecuencia cardíaca
  • Pasos: Datos de conteo de pasos con seguimiento de actividad
  • Datos de sueño: Análisis detallado del sueño que incluye:
    • Etapas del sueño (profundo, ligero, REM, despierto)
    • Métricas de eficiencia y calidad del sueño
    • Frecuencia cardíaca y VFC durante el sueño
    • Variaciones de temperatura durante el sueño
  • Índice de recuperación: Puntuación general de recuperación
  • Índice de movimiento: Métricas de actividad y movimiento
  • VO2 Max: Indicador de aptitud cardiovascular

💻 Uso con Claude Desktop

  1. Compila el proyecto:

    bun run build

  2. Añádelo a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

    {
  "mcpServers": {
    "ultrahuman": {
      "command": "node",
      "args": ["/path/to/your/project/dist/main.js"],
      "env": {
        "ULTRAHUMAN_AUTH_TOKEN": "your_token_here",
        "ULTRAHUMAN_USER_EMAIL": "your_email@example.com"
      }
    }
  }
}

🧪 Pruebas

Puedes probar el servidor ejecutándolo directamente:

node dist/main.js

El servidor escuchará solicitudes MCP en stdio y proporcionará la herramienta ultrahuman_metrics para obtener datos de salud de la API.

🛠️ Desarrollo

  • Ejecutar pruebas: bun test
  • Formatear código: bun run format
  • Lint de código: bun run lint
  • Compilar proyecto: bun run build

📜 Gestión de versiones

Este proyecto utiliza standard-version para la gestión automatizada de versiones. Ejecuta bun run release para crear una nueva versión.

Formato de mensajes de commit

  • feat: Nueva característica (incrementa la versión menor)
  • fix: Corrección de errores (incrementa la versión de parche)
  • BREAKING CHANGE: Cambio importante (incrementa la versión principal)

📦 Publicación en npm

  1. Asegúrate de haber iniciado sesión en npm: 
    npm login
  2. Compila el proyecto: 
    bun run build
  3. Publica el paquete: 
    npm publish

Instalación desde npm (después de publicar)

Añádelo a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "ultrahuman": {
      "command": "npx",
      "args": ["-y", "ultrahuman-mcp"],
      "env": {
        "ULTRAHUMAN_AUTH_TOKEN": "your_token_here",
        "ULTRAHUMAN_USER_EMAIL": "your_email@example.com"
      }
    }
  }
}