health_schema: Discover available tables, columns, units, and sample rows to understand your health data structure.
health_query: Run read-only SQL SELECT queries on your Apple Health data (from CSV exports by "Simple Health Export CSV"), with output in JSON, CSV, or summary format.
health_report: Generate structured health summaries for weekly, monthly, or custom date ranges, with optional metric filtering.
All operations are local (using DuckDB) — no data is uploaded or sent over the network. Query results go to your MCP client only.
Configuration via environment variables: MAX_MEMORY_MB and CACHE_SIZE.
Note: Only the last 90 days of data is loaded into the in-memory database; older records are inaccessible.
Provides tools for querying and analyzing Apple Health data using SQL, supporting analysis of health metrics, categorical health data, and workout information exported from Apple Health.
Uses DuckDB as the backend database for fast and efficient querying of health data, enabling complex SQL queries on exported Apple Health information.
Works with health data exported from iOS devices via the Simple Health Export CSV app, allowing users to analyze their iOS Health app data through SQL queries.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Apple Health MCP Server show me my average heart rate for the past week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Query Apple Health data from an MCP client using SQL and DuckDB. The server runs locally, reads CSV exports on demand, and provides tools for schema discovery, read-only queries, and health summaries.
Node.js 22 or newer
An Apple Health CSV export created with Simple Health Export CSV
The native Apple Health export.xml format is not currently supported.
Related MCP server: apple-mcp
For Claude Desktop, add the following to
~/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"
}
}
}
}Restart the client after changing its configuration. Other MCP clients can use
the same command, arguments, environment, and stdio transport.
Variable | Required | Default | Purpose |
| Yes | — | Directory containing the exported CSV files |
| No |
| DuckDB memory limit in megabytes |
| No |
| Maximum number of cached query results |
Install and open Simple Health Export CSV on your iPhone.
Select All and choose the time range to export.
Transfer the archive to the computer running your MCP client.
Unzip it and set HEALTH_DATA_DIR to the resulting directory.
The server reads the files in place. It does not upload the export or make network requests, although query results returned to your MCP client may be sent to that client's configured model provider.
Tool | Purpose |
| Discover table names, columns, units, and sample rows |
| Run a read-only |
| Generate a weekly, monthly, or custom health summary |
Start with health_schema; table names depend on the files in your export.
See Querying Apple Health data
for the data model and working examples.
The first request that needs a table loads that table's full CSV history. There is no date window, so a query can reach as far back as the export goes.
Because every tool can reach the whole configured history, only start this server from an MCP client you trust with that data.
Loaded tables are held in memory, and DuckDB is given the MAX_MEMORY_MB limit
described above. Roughly 1 GiB covers a two-year multi-table export, so the
2048MB default leaves headroom; raise MAX_MEMORY_MB for a larger export. The
server never spills health rows to a temporary directory on disk, so an export
that does not fit in the limit fails with an explicit error instead.
Other current limitations:
Only the Simple Health Export CSV layout is supported.
The DuckDB database is in memory and is rebuilt for each server process, so each launch reloads from the CSV files. Persistent incremental import is planned future work, not current behavior.
Device overlap can produce duplicate-looking measurements; queries should
account for sourceName where appropriate.
Health reports summarize recorded data and are not medical advice.
git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
bun install
npm test
npm run typecheck
npm run buildSee Architecture for the code layout, data lifecycle, and implementation constraints.
MIT
Execute SQL queries on Apple Health data. Supports SELECT queries only.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | SQL SELECT query to execute | |
| format | No | Output format (default: json) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the read-only nature via 'Supports SELECT queries only', which is a significant behavioral trait. However, it does not mention output format variations (beyond schema), potential performance/limits, or error behavior, leaving some gaps.
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, immediately stating the action and the key restriction. It is concise and front-loaded, with no wasted words.
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 tool with two parameters and no output schema, the description is adequate: it specifies the action, the data domain, and the central limitation. The output format defaults are in the schema, and the lack of an output schema means return details are not strictly necessary. It is not overly complex, and the description covers the essential context.
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 coverage is 100% with descriptions for both query and format, so the bar is lowered. The description adds the Apple Health data context and the SELECT-only restriction, but these are already partially inferred from the schema. It does not provide deeper semantic meaning beyond the schema.
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 executes SQL queries on Apple Health data, with a specific verb ('Execute') and resource. The additional 'Supports SELECT queries only' clarifies scope and distinguishes it from health_report (pre-built reports) and health_schema (schema introspection).
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 provides the constraint that only SELECT queries are allowed, which implicitly says not to use it for writes, but it does not explicitly mention alternatives like health_report or health_schema, nor does it describe when to prefer this tool over siblings. It gives a minor usage hint but lacks explicit when-to-use guidance.
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. Dates show when Glama detected each change.
v0.1.0health_queryhealth_reporthealth_schemaEach tool has a clearly distinct purpose: querying data via SQL, generating reports, and inspecting schema. There is no overlap or ambiguity in their roles.
All tool names follow a consistent health_ prefix pattern, making them predictable and easy to navigate. The suffixes (query, report, schema) are clear and uniform.
Three tools is a well-scoped size for a read-only health data server. Each tool serves a core function without redundancy or bloat.
The tool set covers the full read-only lifecycle: explore schema, query raw data, and generate structured reports. No obvious gaps exist for typical health data access needs.
Private Apple Health metrics and workout detail for ChatGPT, Claude, and any MCP client.
Collect Apple Health data from your wearables through the Context app and query it via MCP
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
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/neiltron/apple-health-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
