health-mcp

Tu base de datos de salud personal. Tu agente se encarga de escribir.

Un servidor local-first que almacena tus datos de nutrición, biomarcadores y wearables. Todo se expone como herramientas del Model Context Protocol, de modo que cualquier agente compatible con MCP (Hermes, OpenClaw) pueda leerlo y escribirlo. Un panel web se incluye en el mismo proceso para cuando quieras ver los datos en lugar de hablar con ellos.

Todo se ejecuta en tu máquina. Un único archivo SQLite. Sin cuentas, sin SaaS, sin telemetría.

En lugar de crear otra app de calorías basada en fotografías o un analizador de texto libre, deja que el agente se encargue de las partes ambiguas («he tomado dos huevos y tostada», «registra este PDF de laboratorio», «¿qué afecta a mi puntuación de sueño?») y que este servidor se encargue de las partes duraderas: esquema tipado, transacciones atómicas, consultas por rango, una superficie de herramientas controlada por capacidades y una UI que no miente sobre los datos que tiene debajo.

Qué registra

Nutrición. Alimentos (USDA, Open Food Facts, entradas manuales), comidas compuestas por alimentos / raciones de receta / lotes / componentes personalizados, hidratación, pesos corporales, objetivos de macro como límites {min, max} y resúmenes diarios / semanales.

Recetas y lotes cocinados. Las recetas escalan a las macros por razón. Un lote es una instancia de comida cocinada que se va gastando mientras comes de él, con decrementos atómicos dentro de log_meal y reembolsos al eliminarlo.

Comidas recordadas. Guarda una vez tu desayuno habitual e introdúcelo de nuevo con una única llamada de herramienta. Puede consistir en todos los casos en componentes prefijados (deterministas) o con texto libre canónico (el agente estima de nuevo en cada llamada).

Biomarcadores y laboratorios. Alrededor de 60 biomarcadores preseleccionados con 'códigos LOINC', unidades por defecto y rangos de referencia y óptimos. Los paneles de laboratorio se insertan de forma atómica con todos sus resultados. Un rango de tres niveles ordena la situación de cada resultado: ajuste por resultado de laboratorio → nivel por biomarcador → óptimo curado. Conversión de unidades para los pares duales más comunes (mg/dL ↔ mmol/L, ng/mL ↔ nmol/L, etc.). Consultas de tendencia y del «último valor por marcador».

Wearables. Un Whoop y Oura mediante OAuth2 hoy. Cada espejo de proveedor mantiene la carga real sin procesar (raw_json por fila) para que una migración futura pueda promocionar cualquier campo a una columna normalizada sin una nueva sincronización. Las tablas normalizadas (wearable_sleep, wearable_activity, wearable_readiness, wearable_daily) permiten leer entre un proveedor y otro sin que te importe cuál está conectado. La renovación de tokens de actualización rota; los 401 concurrentes no pueden agotar el mismo token porque la tienda de autenticación está protegida por un mutex por proveedor.

Perspectivas. correlate lanza Pearson o Spearman sobre cualquier conjunto de dos series de mediciones, agrupadas por día / semana / mes. Los recipientes de retardo firmados desplazan del tiempo a su antojo. El avance hacia la completa el último valor a través de los huecos, así que los datos escasos de laboratorio se adaptan limpiamente hacia los resultados diarios del dispositivo de medición del desgaste. La herramienta permanece invisible en el catálogo del agente hasta que hay suficientes datos que merezcan correlacionar.

Inicio rápido

npx

Node ≥ 20 o superior, sin clon ni compilación:

npx health-mcp            # http://127.0.0.1:7777, opens the dashboard
npx health-mcp --stdio    # headless MCP server over stdio

El estado se almacena en ~/.health-mcp/ (un único archivo SQLite). npx health-mcp --help Enumeración de cada flag; npx health-mcp doctor devuelve una revisión automática.

Docker

git clone https://github.com/lukaisailovic/health-mcp.git
cd health-mcp
cp .env.example .env

# Put a strong token in .env (required to bind off-loopback)
openssl rand -hex 32

docker compose up -d
open http://127.0.0.1:7777

Los datos persisten en el volumen health-mcp-data. Si prefieres ver los archivos en disco, cambia el mapeo del volumen en docker-compose.yml por ./.health-mcp-data:/data.

docker compose down detiene el contenedor; los datos sobreviven a los reinicios.

¿Prefieres la imagen precompilada a compilar localmente? Apunta docker-compose.yml a the published image y elimina su bloque build::

image: ghcr.io/lukaisailovic/health-mcp:latest   # or pin :0.1.0 / :0.1

Cada lanzamiento publica :X.Y.Z, :X.Y e ellolatest; :main se adapta al último commit. Todas las imágenes llevan una atestación de procedencia de compilación. Consulta Releasing.

Desde el código fuente

Node ≥ 20 y pnpm.

git clone https://github.com/lukaisailovic/health-mcp.git
cd health-mcp
pnpm install
pnpm build
pnpm start                      # http://127.0.0.1:7777, browser opens automatically

Para desarrollary con recarga en caliente del panel, los tipos compartidos y el servidor, lanza los tres en modo watch:

pnpm dev
# server on :7777, dashboard dev on :5173 (proxies /api/* to :7777)

Pas --no-open para mantener el navegador cerrado, o --no-dashboard para ejecutarlo como servir MCP / REST sin interfaz.

Subcomandos

pnpm start -- migrate                  # apply pending DB migrations and exit
pnpm start -- doctor                   # self-check (DB pragmas, file modes, token entropy)
pnpm start -- export /tmp/dump.jsonl   # JSONL dump; raw_json redacted unless --include-raw
pnpm start -- import-usda dump.json    # ingest a USDA FoodData Central bulk JSON

Conectar un agente MCP

Hermes / OpenClaw (stdio)

Todos y todos utilizan la configuración estándar de MCP, así que la completa instalación es idéntica: agrega health-mcp de la agente a los mcpServers. No se necesita clon ni compilación; directo al paquete reconstruido:

{
  "mcpServers": {
    "health": {
      "command": "npx",
      "args": ["-y", "health-mcp", "--stdio"]
    }
  }
}

Dónde vive ese bloque varía según el agente; consulta su configuración MCP para obtener la ruta.

Luego pide a tu agente:

• Pregunta «Registrar huevos y tostadas para el desayuno» → log_meal

• «¿Cómo está mi tendencia de glucosa en ayuna?» → biomarker_trend

• «¿Mi ingesta de proteína se correlacionda con la recuperación de Whoop al día siguiente?» → correlate con lag_buckets: 1

¿Ejecutas desde una copia local? Utiliza "command": "node" con "args": ["/path/to/health-mcp/apps/server/dist/index.js", "--stdio"] after pnpm build, o "args": ["--import", "tsx", "/path/to/ health-mcp/apps/server/src/index.ts", "--stdio"] para omitir la compilación.

MCP Inspector

cd apps/server
pnpm inspect

Abre el MCP Inspector contra un hijo stdio para probar herramientas a mano.

HTTP / cliente personalizado

El transporte Streamable-HTTP está montado en POST /mcp en el mismo puerto que el panel. Apunta cualquier cliente MCP compatible con HTTP a http://127.0.0.1:7777/mcp y envíe Authorization: Bearer <HEALTH_MCP_TOKEN> cuando se haya asignado un token.

La primera conexión OAuth a un proveedor de wearable requiere que el servidor HTTP esté en funcionamiento para que la ruta de callback pueda recibir el redirect. Una vez hecha la vinculación, los tokens de restauración permanecen en auth.json y el modo stdio puede sincronizar desde allí a largo plazo.

El panel de gestión

Servido en / desde el mismo proceso. Páginas actuales:

• Today — comidas del día, totales frente a objetivos, hidratación, peso

• Registrar — añade comidas, hidratación, peso, medidas corporales

• Foods, Recipes, Batches — el grafo de alimentos

• Goals — límites de macros, objetivo de peso

• Labs — paneles, resultados, tendencias, tarjeta " "Acerca de» por biomarcador

• Trends — resúmenes semanales

• Wearables — estado del proveedor, lecturas de sueño / actividad / disposición / diarias

• Insights — interfaz de correlate

• Ajustes — token, zona horaria, tema

Construido con TanStack Router + Query, Kumo UI supera Tailwind v4 y Recharts. El modo oscuro sigue a tu SO por defecto; puedes fijarlo en Settings.

Configuración

Precedencia: flag de CLI > variable de entorno > archivo de configuración JSON > valor predeterminado.

Todos los flags, todas las variables de entorno, el esquema del archivo de configuración JSON y los invariantes de seguridad aplicados en el inicio se describen en docs/CONFIGURATION.md.

Privacidad y seguridad

El servidor está diseñado para su propio cierre en caso de error.

• El loopback es el único valor por defecto seguro. Para conectarla en cualquier otro lugar, hay que establecer HEALTH_MCP_TOKEN con una cadena de 32+ caracteres de alta entropía (openssl rand -hex 32); el servidor se niega a arrancarsin esa condición, sin caída flexible.

• data.db y auth.json se crean con 0600 dentro de un directorio 0700. Los modos más laxos no se abren a menos que se pase --allow-insecure-db / --allow-insecure-auth.

• Las credenciales OAuth de los wearables se almacenan en ~/.health-mcp/auth.json, separadas de data.db, para que health-mcp export pueda transportar la base de datos sin exponer los tokens del proveedor.

• Los proveedores como Whoop rotan tokens de actualización en cada uso. El almacenamiento de autenticación serializa la renovación por proveedor, de modo que dos 401 concurrentes no puedan gastar el mismo token y bloquearlo.

• El callback OAuth utiliza un estado firmado con HMAC con una caducidad de 10 minutos y un nonce de un único uso persistido en SQLite. Sin reproducción, sin falsificación.

Para exponer el servidor fuera de localhost, conviene leer qué protección ofrece, qué no ofrece y cómo hacerlo de forma segura (túnel TLS; consulta el doctor) se cubre en docs/SECURITY.md.

Cómo está organizado

Un proceso de Node. Una aplicación Hono monta el transporte MCP Streamable-HTTP en /mcp, el espejo REST en /api/*, elallback OAuth en /auth/wearable/callback y la SPA del panel en /. El almacenamiento es SQLite a través de better-sqlite3 con journal_mode=WAL y foreign_keys=ON. Toda la lógica de negocio está en apps/server/src/services/*.ts; los handlers de herramientas MCP y las rutas REST son adaptadores finos validados por Zod that delegitan responsabilidades. Los datos de WearableProvider se comparten a través de una interfaz que escribe los espejos en bruto por proveedor y las tablas normalizadas intersistemalizadas en una sola transacción por página de sincronización.

En modo HTTP, un trabajo cron (*/30 * * * * por defecto, configurable) llama a syncWearables() para cada proveedor conectado. El modo stdio omite el planificador; los agentes llaman a sync_wearables a demanda.

La descomposición servicio por servicio, la canalización de transporte y los mecanismos de capacidad detallada en docs/ARCHITECTURE.md.

Superficie de herramientas

Alrededor de 60 herramientas. discover_capabilities devuelve el catálogo dinámico agrupado por área y el flag de estado actual, por lo que los agentes pueden consultarlo primero en lugar de adivinar lo que está disponible.

ping, discover_capabilities

# food
search_food, search_foods, lookup_barcode, get_food
create_custom_food, bulk_upsert_custom_foods, update_custom_food, delete_custom_food

# meals
log_meal, list_meals, get_meal, update_meal, delete_meal, undo_last_meal,
add_meal_component, update_meal_component, remove_meal_component

# recipes + batches
create_recipe, update_recipe, delete_recipe, list_recipes, get_recipe
create_batch, list_batches, get_batch, archive_batch, delete_batch

# remembered meals  (read tools hidden until you save one)
remember_meal, list_remembered_meals, get_remembered_meal,
update_remembered_meal, forget_meal, log_remembered_meal

# simple logs
log_hydration, list_hydration, delete_hydration
log_weight,    list_weight,    delete_weight
log_measurement, list_measurements, delete_measurement
get_goals, set_goals

# summaries
daily_summary, weekly_summary, range_summary

# biomarkers + labs
search_biomarker, get_biomarker, create_custom_biomarker, update_biomarker, set_optimal_range
log_lab_panel, log_lab_result, list_lab_results, latest_biomarkers, biomarker_trend
list_lab_panels, get_lab_panel, delete_lab_result, delete_lab_panel

# insights  (hidden until ≥7 days intake AND (≥1 wearable_daily row OR ≥3 lab_results))
correlate, list_correlate_metrics

# wearables  (most hidden until a provider is linked)
wearables_list_providers, wearables_status,
wearable_connect_url, wearable_disconnect, sync_wearables,
wearable_sleep, wearable_activity, wearable_readiness, wearable_daily, wearable_metric_minutes,
set_activity_type_map

# whoop  (hidden until linked)
whoop_recovery, whoop_cycles, whoop_sleep_raw, whoop_workouts_raw,
whoop_profile, whoop_body_measurement

El control de capacidades oculta las herramientas que el agente no puede actualmente usar, para que la interfaz se mantenga pequeña. Las lecturas de wearables se mantienen invisibles hasta que un proveedor está vinculado; correlate se mantiene invisible hasta que hay datos con los que se correliona. El catálogo completo con parámetros, formas de retorno y reglas de control está en docs/MCP.md.

Documentación

Contribuciones

Se aceptan issues y pull requests.

pnpm install
pnpm typecheck && pnpm lint && pnpm test

Algunas reglas básicas:

• La lógica de negocio reside en apps/server/src/services/. Los Herramientas MCP (src/mcp/tools/) y las rutas REST (src/rest/) son capas delgadas que la envuelven. No pongas lógica en los handlers.

• Las migraciones son módulos TypeScript versionados en apps/server/src/db/sql/000N-*.ts. Solo hacia delante.

• Los esquemas Zod compartidos viven en packages/shared. El servidor y el dashboard se coordinan allí.

• Los servicios nuevos deben incluir un test de Vitest (*.test.ts) o cobertura con la suite de integración (apps/server/src/integration.test.ts).

• pnpm lint:fix antes de subir los cambios — Biome.

Añadir un nuevo proveedor de wearables es un trabajo autocontenido: crea apps/server/src/wearables/providers/<id>/, añade una migración con las tablas espejo raw y regístralo en el registro de wearables. Las herramientas de lectura normalizadas lo recogen automáticamente. Guía en docs/WEARABLES.md.

Lanzar una versión es una ejecución de GitHub Actions en un clic — bump de versión, tag, npm publish y tags GHCR en un solo paso. Ver docs/RELEASING.md.

Estado

Proyecto individual, en desarrollo activo. El modelo de datos es estable para alimentación, biomarcadores y sincronía con Whoop / Oura; las migraciones son solo hacia delante y se aplican al arrancar. Espera cambios incompatibles en los parámetros de las tools y en las rutas del dashboard hasta un tag 1.0. Abre una issue si algo te bloquea por completo.

Es una herramienta de uso personal, no un consejo médico ni un dispositivo médico. Los valores, rangos y correlaciones que expone son para la autocuantificación, no para el diagnóstico.

Tecnología

Node ≥ 20 · tsconfig · TypeScript (ESM, strict) · Hono · @modelcontextprotocol/sdk v1 · better-sqlite3 · Zod · croner · Vitest · Biome.

Dashboard: Vite · React 18 · TanStack Router + Query · Tailwind v4 · Kumo UI · Recharts.

Licencia

MIT.