Health Export MCP

Consulte 190 métricas do Apple Health / HealthKit a partir de qualquer agente MCP — sem dependências, somente leitura, local-first

Documentação

health-export-mcp

Consulte seus próprios dados do Apple Health a partir de qualquer cliente MCP.

health-export-mcp é um servidor Model Context Protocol (MCP) de código aberto e sem dependências. Ele lê a exportação do Apple Health / HealthKit na sua própria máquina e responde às perguntas do seu agente a partir dela: 190 métricas, 16 ferramentas e 22 prompts, como JSON limpo. Somente leitura, local-first, sem conta e sem servidor de desenvolvimento no caminho.

Um comando (Claude Code):

claude mcp add --transport stdio health-export \
  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
  -- npx -y health-export-mcp

Mantenha as aspas duplas: o nome da pasta do iCloud contém um espaço. Ainda não exportou? Experimente primeiro com dados sintéticos:

claude mcp add --transport stdio health-export-demo -- npx -y health-export-mcp --demo

Depois pergunte: "Use health-export: compare meu HRV desta semana com a da semana passada." Usando Claude Desktop, Cursor, VS Code, opencode, OpenClaw ou Hermes? Veja o Quickstart.

Glama MCP Server MCP zero dependencies Node ≥18 License: MIT works with Claude, Cursor, ChatGPT, OpenClaw, Hermes

Apple Health exports to iCloud, a folder, or your LAN; health-export-mcp reads it and serves 16 query tools to your AI agent

Pergunte ao seu agente: "Compare meu HRV desta semana com o da semana passada e me diga se estou me recuperando.", ele chama as ferramentas e responde com base nos seus números reais.


O que é health-export-mcp?

É um servidor MCP que transforma sua exportação do Apple Health em uma ferramenta que seu agente de IA pode consultar em linguagem natural: HRV, sono, frequência cardíaca em repouso, passos, treinos, VO₂ máx. e mais de 180 outras métricas.

  • Para quem é: qualquer pessoa que queira que sua IA raciocine sobre seus dados de saúde reais em vez de um CSV desatualizado.
  • O que não é: um serviço em nuvem. Não há servidor de desenvolvimento no caminho; seus dados vão apenas para onde você apontar.
  • Configuração: aponte o servidor para seus dados exportados e adicione-o ao seu cliente de IA.
  • De onde vêm os dados: o aplicativo iOS MetricBridge (antigo Health Export AI), disponível na App Store, grava a exportação que este servidor lê. O servidor ainda se identifica como health-export-ai em serverInfo, e o nome do pacote npm e do repositório permanecem inalterados.

Acabou de exportar e o Mac ainda não viu? O iCloud pode levar alguns minutos para sincronizar o arquivo, então uma verificação 60 segundos após tocar em Executar no aplicativo ainda pode mostrar o timestamp antigo. get_mcp_status relata lastDataDate e o lastWrite intraday, que é a maneira mais rápida de distinguir "ainda sincronizando" de "nunca chegou".

Experimente sem precisar de iPhone: npx -y health-export-mcp --demo (ou node server.mjs --demo em um clone) serve um conjunto de dados sintético determinístico (400 dias, treinos, eventos, sessões de sono) com cada resposta marcada como sintética. Ou execute npm test para gravar um cache de exemplo e exercitar todas as ferramentas.


Conecte o Apple Health ao seu agente de IA, Quickstart

1. Faça seus dados do Apple Health fluírem

O aplicativo iOS complementar MetricBridge exporta seus dados do Apple Health, somente leitura, automático e privado. Para este servidor MCP, exporte para um destino que ele possa ler:

Download MetricBridge on the App Store

DestinoObservações
iCloud Drive (padrão)Seu Mac lê a pasta sincronizada automaticamente
Pasta localQualquer pasta que sincronize com seu Mac (Dropbox, Google Drive, OneDrive, …)
LAN (HTTP / WebSocket)Envio direto para o servidor, ótimo via Tailscale

Usando uma ferramenta não-MCP (ChatGPT, n8n, Home Assistant)? O aplicativo também pode enviar via POST para um webhook que essas ferramentas leem diretamente; veja Funciona com.

2. Adicione o servidor ao seu agente

Mais rápido, um comando (Claude Code):

claude mcp add --transport stdio health-export \
  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
  -- npx -y health-export-mcp

Tudo antes de -- é uma opção para claude mcp add; tudo depois é o comando que inicia o servidor. O caminho está entre aspas duplas porque o nome da pasta do iCloud contém um espaço, e $HOME é usado porque um ~ entre aspas não é expandido pelo shell. Exportando para outro lugar? Substitua o caminho pela sua própria pasta. Adicione --scope user para disponibilizar o servidor em todos os projetos (o escopo padrão é apenas o projeto atual). Verifique com claude mcp list.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) e qualquer cliente que aceite um bloco mcpServers:

{
  "mcpServers": {
    "health-export": {
      "command": "npx",
      "args": ["-y", "health-export-mcp"],
      "env": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
    }
  }
}

npx -y busca o pacote publicado em tempo de execução sem prompt de instalação (o npm verifica a integridade do pacote), então funciona em qualquer lugar sem clone ou caminho absoluto. O servidor expande um ~ inicial em HEALTH_DATA_DIR por conta própria, então o formato JSON pode mantê-lo. Prefere fixar um checkout local verificado? Use "command": "node", "args": ["REPLACE_WITH_ABSOLUTE_PATH/server.mjs"] e obtenha o caminho com node -e "console.log(process.cwd()+'/server.mjs')" dentro do repositório. Ou pule o JSON completamente, arraste health-export.mcpb para Claude Desktop → Configurações → Extensões.

Configuração automática a partir de um clone:

git clone https://github.com/PhilipAD/health-export-mcp.git
cd health-export-mcp
node apply-mcp-config.mjs     # detects installed clients and writes the config for you

Cursor / VS Code: node gen-deeplinks.mjs imprime links de instalação com um clique. opencode / OpenClaw / Hermes: veja AGENTS.md para o bloco exato, mesmo formato, um por cliente.

3. Pergunte ao seu agente

Reinicie o cliente e tente:

"Use health-export: qual é meu HRV médio desta semana vs. da semana passada?"


Funciona com Claude, Cursor, ChatGPT, OpenClaw, Hermes

Cliente / AgenteIntegraçãoComo
Claude CodeMCP nativoclaude mcp add ... -- npx -y health-export-mcp
Claude DesktopMCP nativoPacote .mcpb ou bloco mcpServers
CursorMCP nativoDeeplink de um clique ou ~/.cursor/mcp.json
opencodeMCP nativoBloco opencode.json mcp
OpenClawMCP nativoAdicione o bloco do servidor à sua configuração MCP
HermesMCP nativoAdicione o bloco do servidor à configuração MCP do seu agente
VS Code (Copilot / Continue)MCP nativoDeeplink de um clique
ChatGPT · Gemini · GrokWebhook*Consuma a exportação via webhook do aplicativo
n8n · Home AssistantWebhook*Dispare automações no JSON exportado

*Clientes MCP consultam este servidor diretamente via stdio. ChatGPT / Gemini / Grok / n8n / Home Assistant não falam MCP; eles consomem os mesmos dados do Apple Health via exportação webhook autenticada por token do aplicativo iOS.


As 16 ferramentas MCP

Referência completa com exemplos de requisição/resposta: healthexport.dev/mcp.

FerramentaO que faz
get_mcp_statusVerificação de saúde: fonte, contagens de métricas/treinos, quais arquivos de contexto existem, data mais recente dos dados e um resumo freshness. Chame primeiro.
get_freshnessQuão atual está a exportação: stale contra um limite declarado (26 h por padrão, HEALTH_STALE_AFTER_HOURS ou maxAgeHours), age_hours, as_of, last_data_date, horários de gravação por arquivo. Mesma regra do gate de cron status --max-age.
list_metricsCada métrica disponível com unidade, contagem de dias e intervalo de datas.
get_health_metricsValores diários para uma métrica (ou todas) em um intervalo de datas + um agregado (média/soma/mín/máx/mais recente). Suporta filterDays (restringir a dias cobertos por eventos registrados, com negate).
get_trendsJanela recente de N dias vs. os N dias anteriores: mudança, % de mudança, direção. Suporta excludeTravelDays.
compare_periodsUma métrica em dois períodos arbitrários (A vs. B) ou em torno de um evento registrado via anchor: {eventId, days} (o dia do evento excluído de ambos os lados).
get_structured_exportJSON limpo para métricas/intervalo escolhidos, paginado com cursor.
get_intradayJanela de hoje, hora por hora, das automações horárias do aplicativo (health-intraday.json, app 1.4+), substituída a cada execução.
query_health_dataConveniência em linguagem natural: "HRV médio do último mês" roteado para resultados estruturados.
list_eventsEventos de contexto registrados (medicação, hábito, visita, vida, turno, episódio, viagem) com filtros de tipo/tag/data.
get_profileCampos de contexto opt-in (condições, medicamentos, metas, alergias, notas) além de presentFields. Campos ausentes foram omitidos, nunca "nenhum".
get_workoutsTreinos por atividade/data com paginação; inclui frequência cardíaca, dinâmica de corrida, potência de ciclismo, intervalos e hasRoute quando exportados.
get_sleep_sessionsSessões de sono agrupadas atribuídas ao dia de vigília; noites divididas retornadas como estão.
get_cycle_contextDia no ciclo e fase aproximada derivados dos inícios de período registrados. Nunca preditivo.
correlate_metricsCorrelação de Pearson entre duas métricas com atraso de 0 a 3 dias. Associação, não causalidade, sempre declarada.
resolve_metricNome canônico e unidade para qualquer grafia (steps, StepCount, Body Weight, hrv), variantes de unidade com fórmulas exatas, uma conversão opcional {value, unit} e se a exportação a contém. Palavras ambíguas retornam com candidatos, nunca adivinhadas. As ferramentas de dados aceitam os mesmos aliases e relatam resolvedFrom.

Cobertura: 190 métricas do Apple Health em atividade, coração, HRV, mobilidade, respiratório, corpo, sono, audição e nutrição, além de treinos. As respostas de dados carregam blocos honestos de coverage, e respostas de métrica única listam eventos registrados dentro da janela como segmentBoundaries para que uma média entre o início de uma medicação ou mudança de vida não possa se passar por um único regime.

Arquivos de dados

O cache diário (.health-cache.json) e o cache de treinos são unidos por arquivos de contexto opcionais, todos somente leitura e todos opcionais: health-events.json (a superfície de registro), health-profile.json (contexto opt-in), health-sessions.json (sessões de sono), health-cycles.json (inícios de ciclo observados), health-days.json (log de mudança de fuso horário). Um arquivo ausente é relatado como available:false com uma nota, nunca como "sem dados". Formatos: docs/SCHEMA-CONTRACTS.md.

Dois padrões que valem a pena conhecer: consultar o Apple Health de um dos pais a partir da sua própria IA (consentimento primeiro, o telefone do pai/mãe é a autoridade) e registrar dados no Apple Health via Atalhos (o servidor e o aplicativo permanecem estritamente somente leitura).

Prompts MCP

O servidor inclui 22 prompts via prompts/list / prompts/get: resumo diário, revisão semanal, preparação para consulta médica, o que mudou desde minha última visita, qualidade e regularidade do sono, tendência de HRV, revisões de treino e semana de corrida, minutos de zona, experimento n-de-1, antes/depois de medicação, comparação de degrau de dose GLP-1, marco de sobriedade, comparação de bloco de turno, revisão mensal honesta de viagens, leitura de tendência consciente do ciclo, check-in de cuidador, resumo diário de glicose, narrativa de atividade de longo prazo, auditoria de cobertura de dados e um bootstrap de contexto consciente do perfil. Cada prompt começa com honestidade de cobertura e nunca transforma dados em diagnóstico.

Modo demo

node server.mjs --demo (ou HEALTH_DEMO=1) serve um conjunto de dados sintético determinístico: ~15 métricas ao longo de 400 dias, 30 treinos com intervalos, 8 eventos, um perfil, 60 sessões de sono, inícios de ciclo e uma mudança de fuso horário, ancorados a uma data fixa com um PRNG com semente. Cada resposta carrega demo: true e um prefixo de texto [SYNTHETIC DEMO DATA], para que a saída do demo nunca possa passar por uma exportação real.

CLI

node server.mjs --doctor            # diagnostics: files, sizes, schema, freshness, pairing
node server.mjs status --max-age 24 # exit 0 if data is fresh, 1 if stale (cron gate)
node server.mjs receive             # standalone LAN receiver (binds 127.0.0.1 by default)
node server.mjs --help

Exemplos de consultas de IA

"What has my resting heart rate done over the last 30 days?"
"Compare my deep sleep this week vs last week."
"Is my VO₂ max trending up or down this quarter?"
"Give me a clean JSON export of HRV, RHR and sleep for the last 14 days."
"Correlate my step count with my sleep duration this month."

Casos de uso

  • Coach de saúde com IA, deixe um agente raciocinar sobre seu HRV real, frequência cardíaca em repouso e sono para sugerir quando avançar e quando recuperar, com base nos seus números reais em vez de conselhos genéricos.
  • Análise de carga de treino, puxe treinos, VO₂ máx. e tendências de frequência cardíaca para que seu agente possa sinalizar excesso de treino, traçar a progressão de condicionamento e ritmar um bloco de treinamento.
  • Correlações de sono, faça seu agente correlacionar a duração do sono profundo com passos, cafeína, treinos tardios ou tempo de tela para descobrir o que realmente afeta sua qualidade de sono.
  • Dashboards de self-tracking, alimente JSON limpo para qualquer conjunto de métricas e intervalo de datas diretamente em um notebook, planilha ou dashboard construído por LLM para seu próprio rastreamento.
  • Pesquisa pessoal e experimentos, execute experimentos n-de-1 (mudanças de suplemento, rotina ou protocolo) e deixe um agente comparar períodos antes/depois em 190 métricas para ver o que mudou.

O aplicativo que alimenta isso

MetricBridge dashboard    190 Apple Health metrics    Export to iCloud, folder, LAN, or webhook

MetricBridge, exporta seus dados do Apple Health para seu agente, automaticamente.

Baixar na App Store →


Privacidade e segurança

  • Somente leitura. O servidor apenas lê seus dados exportados, nunca toca no HealthKit e nunca grava de volta.
  • Local primeiro. Ele roda na sua máquina via stdio. Não há servidor do desenvolvedor no caminho.
  • Emparelhamento opcional. Defina PAIRING_SECRET com o código que o app iOS mostra (Ajustes → Emparelhamento do agente) para controlar o acesso.
  • Exportações criptografadas (opcional). Se você ativar a criptografia de exportação no app iOS, defina HEALTH_EXPORT_PASSPHRASE (ou HEALTH_EXPORT_PASSPHRASE_FILE) com a mesma senha e o servidor descriptografa na sua máquina. Veja Exportações criptografadas.
  • Sem telemetria. O servidor não faz requisições de rede. Quando não encontra uma exportação utilizável (nenhuma ainda, uma desatualizada ou --demo), get_mcp_status inclui um link estático para o site do app complementar. Esse link carrega rótulos de campanha fixos (utm_source=mcp, utm_medium=agent-tool, utm_campaign=mcp-unlock) que são idênticos para todos os usuários e não contêm nada sobre você ou seus dados; eles só contam se você optar por abri-lo.
  • Auditável. Zero dependências e algumas centenas de linhas de JavaScript legível, leia cada linha.
  • Versões assinadas. Os artefatos hospedados são assinados com minisign e verificados por checksum, veja Verificando versões.

Exportações criptografadas

O app iOS pode criptografar o que exporta com uma senha de sua escolha (Ajustes > Criptografia de exportação, ativada por destino: iCloud Drive, uma pasta, seu servidor, a rede local). Dê ao servidor a mesma senha e cada arquivo é descriptografado de forma transparente, em memória, nesta máquina:

HEALTH_EXPORT_PASSPHRASE='your passphrase' HEALTH_DATA_DIR=... node server.mjs
# or keep it out of your shell history and process list:
HEALTH_EXPORT_PASSPHRASE_FILE=~/.config/metricbridge/passphrase HEALTH_DATA_DIR=... node server.mjs

Se ambos estiverem definidos, HEALTH_EXPORT_PASSPHRASE vence; uma quebra de linha final no arquivo é ignorada e um valor vazio conta como não definido. O pacote .mcpb tem um campo opcional Senha de exportação. Exportações em texto simples continuam funcionando de qualquer forma. Uma senha ausente ou incorreta, ou um arquivo que falha na verificação de integridade, é relatado como tal (get_mcp_status diz encrypted: true mais o motivo, --doctor imprime uma linha encryption:), nunca como "sem dados". A senha nunca é registrada ou ecoada.

O receptor LAN (HEALTH_LISTEN=1) descriptografa envios criptografados com a mesma variável e responde 422 com uma máquina reason (passphrase_missing, passphrase_mismatch, tampered, malformed, unsupported_version, passphrase_file_unreadable, encryption_required). O token de emparelhamento viaja em um cabeçalho http simples nesse trecho, então defina HEALTH_REQUIRE_ENCRYPTED=1 para recusar envios em texto simples uma vez que o app criptografe esse trecho. Para descriptografar um corpo você mesmo (um webhook que você executa, um script):

HEALTH_EXPORT_PASSPHRASE='...' node envelope.mjs open body.json     # prints the decrypted JSON

Formato (metricbridge.enc v1, envelope.mjs, node:crypto apenas): um objeto JSON {format, v, alg: "A256GCM", kdf: "PBKDF2-HMAC-SHA256", iter, salt, kcv, nonce, ct}. master = PBKDF2-HMAC-SHA256(NFC(passphrase), salt[16], iter) (600.000 iterações, o valor da OWASP); uma chave AES-256-GCM e um valor de verificação de chave de 8 bytes saem dela com HKDF-SHA256; cada mensagem recebe um nonce aleatório de 12 bytes; cada campo de cabeçalho é vinculado como AAD como a string metricbridge.enc|v=1|alg=A256GCM|kdf=PBKDF2-HMAC-SHA256|iter=<n>|salt=<b64>|kcv=<b64>|nonce=<b64>. Base64 é canônico com preenchimento. test/fixtures/ contém envelopes feitos pelo codificador Swift do app iOS e por este módulo; envelope.test.mjs prova que ambos abrem e regeneram byte por byte.

O que protege: a exportação em repouso no destino (iCloud Drive, uma pasta sincronizada, o armazenamento de um host de webhook) e o envio LAN na rede, além da integridade de cada arquivo lacrado. O que não protege: um telefone desbloqueado, este computador (ele contém a senha), metadados (tamanhos, tempo), rollback ou replay de um arquivo lacrado inteiro, arquivos que você compartilha manualmente pelo app, ou uma senha fraca (qualquer pessoa com os arquivos pode adivinhar offline; o app exige pelo menos 8 caracteres).


Verificando versões

Os artefatos do servidor hospedados em healthexport.dev/mcp/ (usados pela habilidade de configuração) são assinados com minisign, e cada download é verificado por SHA-256. A chave pública de assinatura é publicada neste repositório (minisign.pub) e em SKILL.md, fixe-a a partir daqui, não apenas do site, para que um comprometimento do site sozinho não possa trocar tanto um artefato quanto sua chave.

PUBKEY='RWS6TxVWSKUblYkx7Db6ZpmvHALwHpznZpjaED/FlZj+PpxSlel0MxHZ'   # = minisign.pub in this repo
curl -fsSL https://healthexport.dev/mcp/SHA256SUMS         -o SHA256SUMS
curl -fsSL https://healthexport.dev/mcp/SHA256SUMS.minisig -o SHA256SUMS.minisig
minisign -Vm SHA256SUMS -P "$PUBKEY" || { echo "signature INVALID, do not run"; exit 1; }   # fail closed
curl -fsSL https://healthexport.dev/mcp/server.mjs -o server.mjs
shasum -a 256 --ignore-missing -c SHA256SUMS || { echo "checksum mismatch, do not run"; exit 1; }

O download fixado e verificado por checksum acima é o caminho bloqueado. npx -y health-export-mcp em vez disso resolve a versão mais recente publicada no npm em tempo de execução (o npm fornece sua própria integridade de pacote). Cada versão do GitHub também carrega um arquivo SHA256SUMS e sua assinatura SHA256SUMS.minisig feita com a mesma chave. Política completa, incluindo proveniência npm e como relatar uma vulnerabilidade em particular: SECURITY.md. Visão geral de segurança: https://healthexport.dev/security.


Requisitos

  • Node.js ≥ 18 (node -v).
  • Uma pasta contendo um .health-cache.json exportado pelo MetricBridge, ou execute npm test para gerar um exemplo.
  • Um cliente compatível com MCP (Claude Desktop, Cursor, opencode, OpenClaw, Hermes, VS Code), ou qualquer ferramenta que possa ler a exportação via webhook.

FAQ

Como obtenho meus dados do Apple Health no Claude / ChatGPT / meu agente de IA? Instale health-export-mcp, exporte seus dados do Apple Health com o app iOS MetricBridge (para iCloud, uma pasta ou sua LAN), depois adicione o servidor MCP ao seu cliente de IA. Seu agente pode então consultar suas métricas do Apple Health em linguagem natural. (Ferramentas não-MCP como ChatGPT leem a exportação via webhook do app.)

Meus dados de saúde são enviados para um servidor? Não para nós. O servidor MCP roda localmente e lê apenas os arquivos ou endpoints de exportação que você configura, não há servidor do desenvolvedor no caminho. Onde sua exportação iOS é entregue (iCloud, sua LAN, um webhook) é inteiramente sua escolha.

Quais agentes são suportados? Qualquer cliente MCP, Claude Desktop, Cursor, opencode, OpenClaw, Hermes, VS Code, nativamente. ChatGPT, Gemini, Grok, n8n e Home Assistant consomem os mesmos dados via webhook.

Preciso do app iOS? O app é a maneira mais fácil de tirar dados do Apple Health do seu iPhone no formato que este servidor lê. Você também pode apontar HEALTH_DATA_DIR para qualquer pasta contendo um .health-cache.json compatível.


Solução de problemas

  • "Nenhuma métrica encontrada", confirme que HEALTH_DATA_DIR aponta para a pasta que contém .health-cache.json, e que o app exportou pelo menos uma vez. Execute get_mcp_status para ver a fonte resolvida e a data mais recente.
  • Servidor não visível no cliente, use um caminho absoluto para server.mjs, garanta Node ≥18 e reinicie completamente o cliente.
  • Erro de dados bloqueados, o arquivo de exportação está protegido até o primeiro desbloqueio após a reinicialização; desbloqueie seu dispositivo uma vez.

Execute localmente

# Node ≥18, no install needed
HEALTH_DATA_DIR=~/Library/Mobile\ Documents/iCloud~ai~healthexport~app/Documents node server.mjs

# integration test, writes a 14-day sample cache and exercises every tool
npm test

Transporte stdio (JSON-RPC 2.0 delimitado por nova linha), o transporte MCP universal. Opcionalmente, defina HEALTH_LISTEN=1 para também aceitar envios LAN do app iOS no mesmo processo (veja receiver.mjs).


Como funciona

O app iOS lê o Apple Health (somente leitura) e grava um .health-cache.json compacto (mais arquivos de contexto opcionais) no destino que você escolher. Este servidor lê esses arquivos e expõe as 16 ferramentas acima via MCP. Sem ponte, sem Docker, sem banco de dados: apenas arquivos e stdio.

Apple Health → MetricBridge (iOS) → .health-cache.json → health-export-mcp → MCP client → you

Projetos relacionados

Outros servidores MCP de Apple Health no ecossistema, vale a pena dar uma olhada dependendo da sua configuração:

Como health-export-mcp difere: zero dependências, JSON estruturado limpo, 190 métricas do Apple Health e o suporte mais amplo a agentes (Claude, Cursor, opencode, OpenClaw, Hermes, VS Code nativamente, além de ChatGPT/Gemini/Grok/n8n/Home Assistant via webhook).


Relacionados

Se isso ajudar na sua configuração, uma ⭐ facilita que outros encontrem.

Licença

MIT, veja LICENSE. Contribuições são bem-vindas.


Servidor MCP de Apple Health · exporte Apple Health para IA · servidor MCP HealthKit · consulte Apple Health com Claude / ChatGPT / Cursor · servidor de saúde Model Context Protocol · Apple Health para LLM · HRV, sono e frequência cardíaca para agentes de IA.