Apple Health MCP 프로젝트 소개
최근 헬스케어 데이터에 대한 관심이 높아지면서, 자신의 건강 상태를 수치적으로 파악하고 분석하려는 수요가 증가하고 있습니다. 특히 애플 사용자들은 iPhone과 Apple Watch를 통해 다양한 생체 데이터를 자동으로 수집할 수 있지만, 이 데이터를 효율적으로 분석하거나 외부 툴과 연동해 시각화하는 것은 여전히 쉽지 않은 일입니다. 이런 상황에서 Apple Health MCP는 애플 헬스 데이터를 SQL 기반으로 분석할 수 있도록 도와주는 가볍고 유용한 도구입니다.
이 프로젝트는 Eric Wolter가 개발한 Simple Health Export CSV App에서 추출한 CSV 데이터를 활용합니다. 즉, Apple Health MCP Server는 직접적으로 Apple Health 데이터에 접근할 수 없습니다.
Apple Health MCP는 MCP(Model Context Protocol) 서버를 기반으로 Apple Health 데이터를 SQL 쿼리로 조회할 수 있게 도와주는 오픈소스 도구입니다. 정확히는 Simple Health Export CSV App으로 추출한 CSV 형식의 Health 데이터를 빠르게 처리하며, 사용자는 자연어를 기반으로 한 질의나 직접 SQL을 작성하여 데이터를 조회할 수 있습니다. 이 도구는 npx 명령어를 통해 설치 없이 사용할 수 있으며, Claude Desktop과 같은 MCP 클라이언트에 간단히 설정만 추가하면 바로 연동 가능합니다. 특히 DuckDB의 빠른 처리 속도와 저메모리 환경에서도 동작하는 장점 덕분에, 헬스 데이터를 직접 분석하거나 자동 리포트를 생성하려는 사용자들에게 매우 실용적인 솔루션이 됩니다.
애플의 기본 헬스 앱은 사용자 인터페이스에 초점을 맞추고 있어, 데이터의 구조적인 분석에는 한계가 있습니다. 반면, Apple Health MCP는 CSV로 내보내기(export)한 데이터를 SQL로 직접 조회할 수 있기 때문에, 평균 심박수, 수면 패턴, 걸음 수 등의 정보를 자유롭게 가공하거나, 자동화된 리포트를 생성하는 데 매우 유리합니다. 따라서 건강 데이터를 분석하려는 개발자, 헬스케어 앱 개발자, 데이터 과학자들에게 매우 흥미로운 프로젝트입니다.
Apple Health MCP의 주요 기능
- 자연어 질의 지원: MCP 클라이언트가 자연어를 SQL로 변환하여 질의 수행
- 직접 SQL 쿼리 가능: 헬스 데이터에 대해 직접 SQL 작성 가능
- 자동 리포트: 주간/월간 건강 리포트 자동 생성
- 지연 로딩 및 캐싱: 성능 최적화를 위한 lazy loading과 TTL 기반 쿼리 결과 캐싱
Apple Health MCP 설치 및 사용법
Claude Desktop에 추가
Apple Health MCP 프로젝트는 별도의 설치 없이 npx 명령어로 바로 사용할 수 있습니다. 예를 들어, Claude Desktop 설정 파일(claude_desktop_config.json)에 다음과 같이 설정하면 MCP 서버로 연동됩니다:
{
"mcpServers": {
"apple-health": {
"command": "npx",
"args": ["@neiltron/apple-health-mcp"],
"env": {
"HEALTH_DATA_DIR": "/Users/yourname/Downloads/HealthExport",
"MAX_MEMORY_MB": "2048"
}
}
}
}
여기서 중요한 설정값은 HEALTH_DATA_DIR이며, 이는 CSV 파일이 저장된 경로입니다. 해당 디렉토리는 아래에서 설명할 iOS 앱을 통해 얻을 수 있습니다.
데이터 추출 방법
Apple Health MCP 프로젝트는 iOS 앱인 Simple Health Export CSV를 통해 헬스 데이터를 내보낸 후 사용할 수 있습니다. 사용법은 다음과 같습니다:
- Simple Health Export CSV App을 설치합니다.
- 설치 후
All버튼을 눌러 전체 데이터를 선택합니다. (기본 값은 1달입니다.) - 원하는 기간의 데이터를 선택 후 Airdrop 등으로 Mac에 전송합니다.
- 압축을 해제한 후, 해당 폴더 경로를
HEALTH_DATA_DIR로 설정합니다.
Apple Health MCP Server가 제공하는 Tools
Apple Health MCP 프로젝트는 다음과 같은 주요 도구를 제공합니다:
health_schema: 사용 가능한 테이블 구조 확인health_query: SQL로 직접 헬스 데이터 질의health_report: 정기 리포트 생성
데이터 구조
Apple Health에서 내보낸 CSV 파일은 다음과 같은 형식을 가집니다:
HKQuantityTypeIdentifier*.csv: 정량적(Quantitative)인 건강 지표HKCategoryTypeIdentifier*.csv: 범주형(Categorical) 건강 데이터HKWorkoutActivityType*.csv: 운동 및 활동 데이터
각 CSV 파일들은 다음의 컬럼들을 갖습니다:
type: 세부 건강 지표 종류 (The specific health metric type)sourceName: 수집한 원천 장치 또는 App (Source device/app)startDate: 시작 시간 (Start timestamp, UTC)endDate: 종료 시간 (End timestamp, UTC)value: 측정 값 (The measurement value)unit: 측정 단위 (Unit of measurement)
이 형식을 통해 시간대별 심박수, 수면 상태, 활동량 등 다양한 데이터를 SQL로 조회할 수 있습니다.
Apple Health MCP 프로젝트 GitHub 저장소
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 