health4ai

health4.ai — Apple Health × IA

Pregunta a tu IA sobre tu sueño, VFC, recuperación y estado físico — en lenguaje natural.
App iOS gratuita · Tu propia base de datos · Funciona con cualquier cliente MCP

Qué hace

iPhone HealthKit → Your Supabase project → MCP server → Any AI

Apple Health guarda años de tus datos biométricos — fases del sueño, VFC, frecuencia cardíaca, entrenamientos, VO₂ máx y más de 150 métricas adicionales. health4.ai hace que todo ello sea consultable desde Claude, ChatGPT, Cursor, Ollama o cualquier cliente compatible con MCP mediante herramientas MCP diseñadas específicamente.

Tú controlas los datos. Se sincronizan con un proyecto de Supabase que tú creas y posees. health4.ai no ejecuta ningún backend y nunca almacena ni tiene acceso a tus datos de salud.

Por qué existe

Demostración

El vídeo de demostración llegará pronto. Así es como se ve una conversación típica:

You:     How was my recovery this week? Anything standing out?

Claude:  Your recovery this week was mixed but trending positive.
         • HRV averaged 58ms (Tue–Thu strong at 64–68ms; Monday low at 44ms after Saturday's long run)
         • Sleep averaged 7h 12m — Wednesday and Thursday were your best nights (7h 40m+)
         • Resting HR dropped from 54bpm Monday to 49bpm Friday — a good sign
         Recommendation: today looks like a solid day for a moderate-intensity session.

Inicio rápido

health4ai necesita un proyecto de Supabase que sea tuyo. La app inicia sesión con Supabase Auth y escribe a través de una Supabase Edge Function, por lo que Postgres simple (Neon, un contenedor Docker local) no es un backend compatible. Guía completa: docs/SETUP.md.

1. Crea el esquema. Crea un proyecto en supabase.com, abre su editor SQL y ejecuta web/public/schema.sql (también en https://health4.ai/schema.sql). Se genera a partir de supabase/bootstrap/: tablas, seguridad a nivel de fila y permisos que deniegan el acceso directo a los clientes. No uses supabase db push — las migraciones numeradas no se aplican a un proyecto nuevo.

2. Despliega la función de ingesta (requiere la Supabase CLI):

git clone https://github.com/jefflitt1/health4ai.git
cd health4ai
supabase functions deploy healthkit-ingest --project-ref <your-project-ref> --no-verify-jwt

--no-verify-jwt es intencional: la función verifica el token del usuario con sesión iniciada por sí misma y escribe únicamente bajo el ID de ese usuario.

3. Crea tu usuario. En el panel, Authentication → Users → añade un usuario y copia su UID. La app inicia sesión; no se registra.

Luego configura el servidor MCP (desde el mismo checkout):

cp mcp-server/.env.example mcp-server/.env

Edita mcp-server/.env:

DATABASE_URL=postgresql://...  # your project's pooler connection string (database password, not a key)
HEALTHKIT_USER_ID=...           # your Supabase Auth user's UID (see mcp-server/.env.example)

Añádelo a tu cliente de IA:

{
  "mcpServers": {
    "health4ai": {
      "command": "python",
      "args": ["/path/to/health4ai/mcp-server/main.py"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "HEALTHKIT_USER_ID": "<your auth user UID>"
      }
    }
  }
}

mcphost --model ollama/llama3.2 \
  --mcp-server "health4ai:python /path/to/health4ai/mcp-server/main.py"

Instala la app iOS: conéctala a ese proyecto de Supabase (URL del proyecto + clave anónima), inicia sesión como el usuario que creaste y toca Iniciar sincronización. Para una beta privada de TestFlight, sigue la guía de aislamiento de evaluadores; nunca uses el backend o las credenciales de otra persona.

Herramientas MCP

Si una métrica está vacía, lee data_status antes de creértelo

iOS nunca le dice a una app que se denegó un permiso de Health. Un tipo que no has compartido devuelve un resultado vacío, idéntico byte a byte a un día en el que realmente no hiciste nada. Nada en la API de HealthKit puede distinguir ambos casos, así que un asistente que lea un 0 simple te dirá con seguridad que no diste ningún paso.

Las herramientas que pueden devolver un resultado vacío adjuntan por tanto un bloque data_status:

• never_recorded — esta métrica nunca ha producido una muestra para ti. Para pasos, frecuencia cardíaca, energía activa o distancia caminada, eso no es posible si los datos se estuvieran compartiendo, así que casi con seguridad no lo están. Abre Salud → Compartir → Apps → health4ai, activa la métrica y vuelve a ejecutar la importación desde la pestaña Inicio de la app.
• empty_window — no hay nada en el período que consultaste, pero la métrica tiene datos en otros momentos. Una brecha real, no un problema de permisos.

Esto no es hipotético. En la propia cuenta del autor, el recuento de pasos, la frecuencia cardíaca, la energía activa y la distancia caminada estuvieron sin compartir silenciosamente durante casi tres meses mientras todas las demás métricas se sincronizaban con normalidad, y la app mostraba un "Completo" en verde durante todo ese tiempo.

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│  iPhone                                                      │
│  HKObserverQuery + BGTaskScheduler                          │
│  → continuous background sync                               │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS → your healthkit-ingest Edge Function
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Your Supabase project (you own it)                         │
│  healthkit_metrics · healthkit_daily_summaries              │
│  row-level security on · no direct client access            │
└──────────────────────────┬──────────────────────────────────┘
                           │ Postgres connection (database password, from your machine)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  FastMCP server  (mcp-server/main.py)                       │
│  FastMCP tools · stdio transport                             │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP
                           ▼
              Claude · ChatGPT · Cursor · Ollama · any client

Niveles de datos: las consultas de los últimos 30 días devuelven muestras sin procesar. Los días anteriores usan una fila pre-agregada de healthkit_daily_summaries cuando existe y, en caso contrario, se agregan por día dentro de Postgres a partir de las muestras sin procesar, de modo que los resultados son completos tanto si el resumidor se ha ejecutado en tu proyecto como si no (en un proyecto autoalojado nuevo nunca se ha ejecutado). Las respuestas incluyen un bloque tier que indica cuántos días sirvió cada nivel. Los días del calendario siguen HEALTH4AI_TZ (UTC por defecto; configúralo en mcp-server/.env).

Estructura del repositorio

health4ai/
├── ios/                         # Swift/SwiftUI iOS app (iOS 17+)
│   └── Health4AI/               # HealthKit sync engine, auth, settings
├── mcp-server/
│   ├── main.py                  # FastMCP server entry point
│   ├── tools.py                 # MCP tool implementations
│   └── .env.example             # Required environment variables
├── web/
│   ├── public/schema.sql        # Generated from supabase/bootstrap (Supabase only)
│   └── src/                     # Astro marketing site
├── scripts/
│   ├── import_health_export.py  # One-time XML backfill from Apple Health export
│   └── summarize_historical.py  # Backfill daily summaries table
└── docs/
    └── SETUP.md                 # Detailed setup guide

Privacidad

Tus datos de salud van directamente de tu iPhone a tu propio proyecto de Supabase. health4.ai nunca los recibe, almacena ni tiene acceso a ellos. El servidor MCP se ejecuta localmente con tus propias credenciales — tus datos nunca tocan nuestra infraestructura.

Consulta la Política de privacidad para más detalles.

Contribuciones

Licencia MIT. Se aceptan pull requests.

Buenas áreas para empezar: agregaciones de métricas adicionales, soporte multiusuario con JWT/RLS, Android y más guías de integración con clientes MCP.

Licencia

MIT — consulta LICENSE.