Apple Health MCP Server

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 de solo lectura 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 se admite actualmente.

Related MCP server: apple-mcp

Configurar un cliente MCP

Para Claude Desktop, añade 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

Exportar datos de salud

1. Instala y abre Simple Health Export CSV en tu iPhone.

2. Selecciona Todo y elige el rango de tiempo a exportar.

3. Transfiere el archivo al ordenador que ejecuta tu cliente MCP.

4. 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

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

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 da 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 valor 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 que parecen duplicadas; las consultas deben tener en cuenta sourceName cuando corresponda.

• Los resúmenes de salud resumen 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 Architecture para la estructura del código, el ciclo de vida de los datos y las restricciones de implementación.

Licencia

MIT