Apple Health MCP Server

MCP 클라이언트에서 SQL과 DuckDB를 사용하여 Apple Health 데이터를 조회합니다. 서버는 로컬에서 실행되며, 요청 시 CSV 내보내기를 읽고 스키마 탐색, 읽기 전용 쿼리, 건강 요약을 위한 도구를 제공합니다.

요구 사항

• Node.js 22 이상

• Simple Health Export CSV로 생성된 Apple Health CSV 내보내기

기본 Apple Health export.xml 형식은 현재 지원되지 않습니다.

Related MCP server: apple-mcp

MCP 클라이언트 구성

Claude Desktop의 경우 ~/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"
      }
    }
  }
}

구성 변경 후 클라이언트를 다시 시작하세요. 다른 MCP 클라이언트도 동일한 명령, 인수, 환경 및 stdio 전송을 사용할 수 있습니다.

환경 변수

건강 데이터 내보내기

1. iPhone에서 Simple Health Export CSV를 설치하고 엽니다.

2. 모두를 선택하고 내보낼 기간을 선택합니다.

3. 아카이브를 MCP 클라이언트가 실행 중인 컴퓨터로 전송합니다.

4. 압축을 풀고 HEALTH_DATA_DIR을 결과 디렉터리로 설정합니다.

서버는 파일을 제자리에서 읽습니다. 내보내기를 업로드하거나 네트워크 요청을 하지 않지만, MCP 클라이언트로 반환된 쿼리 결과는 해당 클라이언트의 구성된 모델 제공자에게 전송될 수 있습니다.

도구

health_schema부터 시작하세요. 테이블 이름은 내보내기의 파일에 따라 달라집니다. 데이터 모델과 작동 예제는 Apple Health 데이터 쿼리를 참조하세요.

기록 및 메모리

테이블이 필요한 첫 번째 요청은 해당 테이블의 전체 CSV 기록을 로드합니다. 날짜 창이 없으므로 쿼리는 내보내기가 포함하는 만큼 과거로 거슬러 올라갈 수 있습니다.

모든 도구가 구성된 전체 기록에 접근할 수 있으므로, 이 서버는 해당 데이터를 신뢰할 수 있는 MCP 클라이언트에서만 시작하세요.

로드된 테이블은 메모리에 유지되며, DuckDB에는 위에서 설명한 MAX_MEMORY_MB 제한이 적용됩니다. 약 1GiB는 2년 분량의 다중 테이블 내보내기를 처리하므로 2048MB 기본값은 여유가 있습니다. 더 큰 내보내기의 경우 MAX_MEMORY_MB를 높이세요. 서버는 건강 행을 디스크의 임시 디렉터리에 유출하지 않으므로, 제한에 맞지 않는 내보내기는 대신 명시적 오류로 실패합니다.

기타 현재 제한 사항:

• Simple Health Export CSV 레이아웃만 지원됩니다.

• DuckDB 데이터베이스는 메모리에 있으며 각 서버 프로세스마다 다시 구축되므로, 각 시작 시 CSV 파일에서 다시 로드됩니다. 영구 증분 가져오기는 현재 동작이 아닌 향후 작업으로 계획되어 있습니다.

• 기기 중복으로 인해 중복으로 보이는 측정값이 발생할 수 있습니다. 쿼리는 적절한 경우 sourceName을 고려해야 합니다.

• 건강 요약은 기록된 데이터를 요약한 것이며 의학적 조언이 아닙니다.

개발

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

npm test
npm run typecheck
npm run build

코드 레이아웃, 데이터 수명 주기 및 구현 제약 조건은 아키텍처를 참조하세요.

라이선스

MIT