Apple Health MCP

Consulte dados do Apple Health usando linguagem natural e SQL

Documentação

Servidor Apple Health MCP

Consulte dados do Apple Health a partir de um cliente MCP usando SQL e DuckDB. O servidor roda localmente, lê exportações CSV sob demanda e fornece ferramentas para descoberta de esquema, consultas analíticas e resumos de saúde.

Requisitos

Node.js 22 ou mais recente
Uma exportação CSV do Apple Health criada com Simple Health Export CSV

O formato nativo export.xml do Apple Health não é suportado atualmente.

Configurar um cliente MCP

Para o Claude Desktop, adicione o seguinte 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"
      }
    }
  }
}

Reinicie o cliente após alterar sua configuração. Outros clientes MCP podem usar o mesmo comando, argumentos, ambiente e transporte stdio.

Variáveis de ambiente

Variável	Obrigatória	Padrão	Finalidade
`HEALTH_DATA_DIR`	Sim	—	Diretório contendo os arquivos CSV exportados
`MAX_MEMORY_MB`	Não	`2048`	Limite de memória do DuckDB em megabytes
`CACHE_SIZE`	Não	`100`	Número máximo de resultados de consulta em cache

Exportar dados de saúde

Instale e abra o Simple Health Export CSV no seu iPhone.
Selecione All e escolha o intervalo de tempo para exportar.
Transfira o arquivo para o computador que executa seu cliente MCP.
Descompacte-o e defina HEALTH_DATA_DIR para o diretório resultante.

O servidor lê os arquivos no local. Ele não envia a exportação nem faz requisições de rede, embora os resultados de consulta retornados ao seu cliente MCP possam ser enviados ao provedor de modelo configurado desse cliente.

Ferramentas

Ferramenta	Finalidade
`health_schema`	Descobrir nomes de tabelas, colunas, unidades e linhas de exemplo
`health_query`	Executar uma instrução analítica da família SELECT do DuckDB com saída JSON, CSV ou resumo
`health_report`	Gerar um resumo de saúde semanal, mensal ou personalizado

Comece com health_schema; os nomes das tabelas dependem dos arquivos na sua exportação. Consulte Consultando dados do Apple Health para o modelo de dados e exemplos práticos.

health_query aceita uma instrução analítica do DuckDB. Consulte Proteções de consulta para instruções suportadas e operações restritas.

Proteções de consulta

O servidor limita o acesso a arquivos do DuckDB a HEALTH_DATA_DIR. Ele também desativa acesso à rede e armazenamento temporário em disco, e bloqueia as configurações do banco de dados. O diretório de dados permanece legível e gravável para que o importador possa ler arquivos CSV.

Esses controles reduzem efeitos colaterais acidentais de SQL gerado. Eles não isolam o processo. Execute o servidor por meio de um cliente MCP stdio local. Não o exponha a um cliente de rede não confiável. Use isolamento de processo ou SO se o servidor precisar aceitar SQL não confiável.

Histórico e memória

A primeira solicitação que precisa de uma tabela carrega o histórico CSV completo dessa tabela. Não há janela de data, então uma consulta pode alcançar tão longe quanto a exportação permitir.

Como toda ferramenta pode alcançar todo o histórico configurado, inicie este servidor apenas a partir de um cliente MCP em que você confie com esses dados.

As tabelas carregadas são mantidas em memória, e o DuckDB recebe o limite MAX_MEMORY_MB descrito acima. Aproximadamente 1 GiB cobre uma exportação multi-tabela de dois anos, então o padrão de 2048MB deixa margem; aumente MAX_MEMORY_MB para uma exportação maior. O servidor nunca grava linhas de saúde em um diretório temporário em disco, então uma exportação que não caiba no limite falha com um erro explícito.

Outras limitações atuais:

Apenas o layout CSV do Simple Health Export é suportado.
O banco de dados DuckDB está em memória e é reconstruído para cada processo do servidor, então cada inicialização recarrega dos arquivos CSV. Importação incremental persistente é trabalho futuro planejado, não comportamento atual.
Sobreposição de dispositivos pode produzir medições com aparência duplicada; consultas devem considerar sourceName quando apropriado.
Relatórios de saúde resumem dados registrados e não são aconselhamento médico.

Desenvolvimento

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

npm test
npm run typecheck
npm run build

Consulte Arquitetura para o layout do código, ciclo de vida dos dados e restrições de implementação. Consulte Procedimento de lançamento para etapas de publicação e recuperação.

Licença

MIT