Apple Health MCP

Consulta datos de Apple Health usando lenguaje natural y SQL.

Documentación

Servidor Apple Health MCP

Consulta datos de Apple Health desde un cliente MCP usando SQL y DuckDB. El servidor se ejecuta localmente, lee exportaciones CSV bajo demanda y proporciona herramientas para descubrimiento de esquemas, consultas analíticas y resúmenes de salud.

Requisitos

Node.js 22 o más reciente
Una exportación CSV de Apple Health creada con Simple Health Export CSV

El formato nativo export.xml de Apple Health no es compatible actualmente.

Configurar un cliente MCP

Para Claude Desktop, agrega lo siguiente a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["-y", "@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/path/to/your/unzipped/health-export"
      }
    }
  }
}

Reinicia el cliente después de cambiar su configuración. Otros clientes MCP pueden usar el mismo comando, argumentos, entorno y transporte stdio.

Variables de entorno

Variable	Requerida	Predeterminado	Propósito
`HEALTH_DATA_DIR`	Sí	—	Directorio que contiene los archivos CSV exportados
`MAX_MEMORY_MB`	No	`2048`	Límite de memoria de DuckDB en megabytes
`CACHE_SIZE`	No	`100`	Número máximo de resultados de consulta en caché

Exportar datos de salud

Instala y abre Simple Health Export CSV en tu iPhone.
Selecciona Todo y elige el rango de tiempo a exportar.
Transfiere el archivo al equipo que ejecuta tu cliente MCP.
Descomprímelo y establece HEALTH_DATA_DIR al directorio resultante.

El servidor lee los archivos en su lugar. No sube la exportación ni realiza solicitudes de red, aunque los resultados de consulta devueltos a tu cliente MCP pueden enviarse al proveedor de modelos configurado de ese cliente.

Herramientas

Herramienta	Propósito
`health_schema`	Descubre nombres de tablas, columnas, unidades y filas de muestra
`health_query`	Ejecuta una declaración analítica de la familia SELECT de DuckDB con salida JSON, CSV o resumen
`health_report`	Genera un resumen de salud semanal, mensual o personalizado

Comienza con health_schema; los nombres de las tablas dependen de los archivos en tu exportación. Consulta Consultando datos de Apple Health para el modelo de datos y ejemplos prácticos.

health_query acepta una declaración analítica de DuckDB. Consulta Protecciones de consulta para las declaraciones admitidas y las operaciones restringidas.

Protecciones de consulta

El servidor limita el acceso a archivos de DuckDB a HEALTH_DATA_DIR. También desactiva el acceso a la red y el almacenamiento temporal en disco, y bloquea la configuración de la base de datos. El directorio de datos permanece legible y escribible para que el importador pueda leer archivos CSV.

Estos controles reducen los efectos secundarios accidentales del SQL generado. No aislan el proceso. Ejecuta el servidor a través de un cliente MCP stdio local. No lo expongas a un cliente de red no confiable. Usa aislamiento de proceso o del sistema operativo si el servidor debe aceptar SQL no confiable.

Historial y memoria

La primera solicitud que necesita una tabla carga el historial CSV completo de esa tabla. No hay ventana de fechas, por lo que una consulta puede llegar tan atrás como llegue la exportación.

Debido a que cada herramienta puede acceder a todo el historial configurado, solo inicia este servidor desde un cliente MCP en el que confíes con esos datos.

Las tablas cargadas se mantienen en memoria, y a DuckDB se le asigna el límite MAX_MEMORY_MB descrito anteriormente. Aproximadamente 1 GiB cubre una exportación de dos años con múltiples tablas, por lo que el predeterminado de 2048MB deja margen; aumenta MAX_MEMORY_MB para una exportación más grande. El servidor nunca vuelca filas de salud a un directorio temporal en disco, por lo que una exportación que no quepa en el límite falla con un error explícito en su lugar.

Otras limitaciones actuales:

Solo se admite el diseño CSV de Simple Health Export.
La base de datos DuckDB está en memoria y se reconstruye para cada proceso del servidor, por lo que cada inicio recarga desde los archivos CSV. La importación incremental persistente es trabajo futuro planificado, no comportamiento actual.
La superposición de dispositivos puede producir mediciones de apariencia duplicada; las consultas deben tener en cuenta sourceName cuando corresponda.
Los informes de salud resumen los datos registrados y no son consejo médico.

Desarrollo

git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
bun install

npm test
npm run typecheck
npm run build

Consulta Arquitectura para el diseño del código, el ciclo de vida de los datos y las restricciones de implementación. Consulta Procedimiento de publicación para los pasos de publicación y recuperación.

Licencia

MIT