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
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 전송을 사용할 수 있습니다.
변수 | 필수 | 기본값 | 용도 |
| 예 | — | 내보낸 CSV 파일이 있는 디렉터리 |
| 아니요 |
| DuckDB 메모리 제한(메가바이트) |
| 아니요 |
| 캐시된 쿼리 결과의 최대 수 |
iPhone에서 Simple Health Export CSV를 설치하고 엽니다.
모두를 선택하고 내보낼 기간을 선택합니다.
아카이브를 MCP 클라이언트가 실행 중인 컴퓨터로 전송합니다.
압축을 풀고 HEALTH_DATA_DIR을 결과 디렉터리로 설정합니다.
서버는 파일을 제자리에서 읽습니다. 내보내기를 업로드하거나 네트워크 요청을 하지 않지만, MCP 클라이언트로 반환된 쿼리 결과는 해당 클라이언트의 구성된 모델 제공자에게 전송될 수 있습니다.
도구 | 용도 |
| 테이블 이름, 열, 단위, 샘플 행 탐색 |
| JSON, CSV 또는 요약 출력으로 읽기 전용 |
| 주간, 월간 또는 사용자 지정 건강 요약 생성 |
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
Run one analytical query on Apple Health data.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | One DuckDB analytical query. Joins, CTEs, subqueries, set operations, and window functions are supported. | |
| format | No | Output format (default: json) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral burden. It states the tool runs a query but does not explicitly disclose that it is read-only, whether there are side effects, limits on query complexity or result size, or what the tool returns. 'Analytical query' weakly implies a read operation, but this is under-specified for a tool that accepts arbitrary SQL.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler: it names the verb, resource, and scope immediately. It is concise, but so terse that it misses opportunities to add routing or behavioral context that would make it more genuinely helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool accepting arbitrary DuckDB SQL over health data, an agent needs to know how to discover available tables and fields IAW health_schema, and what output shape or limits to expect. With no output schema, no annotations, and no mention of health_schema, the description is only minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the query string and the format enum including the default JSON value. The description adds the 'one analytical query' framing but no additional parameter detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Run') and names the resource ('Apple Health data'), with the qualifier 'one analytical query.' It clearly communicates what the tool does, though it does not explicitly distinguish itself from the sibling tools health_report and health_schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use this tool when an analytical query needs to be executed against Apple Health data. However, there is no explicit guidance about when to choose this tool over health_report or health_schema, and no mention of alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate structured health reports for a specific period
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | End date for custom reports (YYYY-MM-DD) | |
| start_date | No | Start date for custom reports (YYYY-MM-DD) | |
| report_type | Yes | Type of report to generate | |
| include_metrics | No | Metrics to include (default: all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'Generate structured health reports' without disclosing whether the operation is read-only, what permissions are needed, what side effects exist, or what the output format is. This is insufficient for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundant information. It is front-loaded with the action and object, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description is too minimal to provide complete context. It does not specify what a health report contains, how it is structured, or any edge-case behavior. The presence of sibling tools and moderate parameter count (4) calls for more explanatory content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema—it merely echoes the 'specific period' concept already covered by start_date and end_date descriptions. It does not explain report_type enum semantics or include_metrics default behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Generate') and resource ('structured health reports') with a scope ('for a specific period'). It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools like health_query or health_schema beyond the word 'report'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the description: it generates reports for a period. However, there is no explicit guidance on when to use this tool versus siblings, nor any alternative or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about available health data tables, their structure, and sample data to help write SQL queries
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It indicates a read-only, informational operation ('Get information'), which is consistent with a schema tool. However, it does not disclose any behavioral details such as data source, freshness, or access restrictions beyond the basic read-only implication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action ('Get information') and immediately specifies the resource and purpose. Every phrase adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameterless tool, the description is largely complete. It specifies what the tool returns (table structures and sample data) and why it is useful (writing SQL queries). Without an output schema, this baseline description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with zero parameters, so there are no parameter semantics to explain. Per the baseline for 0-parameter tools, this scores 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get information about available health data tables, their structure, and sample data.' It uses a specific verb ('get') and a specific resource, and the context of sibling tools (health_query, health_report) makes it distinct as the metadata/schema exploration tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before writing SQL queries ('to help write SQL queries'), but it does not explicitly state when to use this tool versus health_query or health_report, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.4.5health_query1 field changedInput schema / properties / query / descriptionPrevious value: -"SQL SELECT query to execute"New value: +"One DuckDB analytical query. Joins, CTEs, subqueries, set operations, and window functions are supported."v0.1.0health_queryhealth_reporthealth_schemaScored across 3 tools
Each tool serves a clearly distinct purpose: health_query runs analytical queries, health_report generates reports, and health_schema provides metadata about tables. There is no overlap in functionality.
All tools follow a consistent pattern with the prefix 'health_' followed by a clear noun (query, report, schema). Naming is uniform and predictable.
With only 3 tools, the set is compact but well-scoped for the stated analytical purpose. While slightly minimal, each tool earns its place and doesn't feel overly sparse.
The tools cover the essential analytical workflow: querying data, generating reports, and understanding schema. Minor gaps exist (e.g., no direct data export), but for the apparent read-only analytical scope, coverage is sufficient.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
GibsonAI MCP server: manage your databases with natural language
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
