The server lets you query and analyze Apple Health data through an MCP client using SQL and DuckDB.
health_schema: Discover available health data tables, columns, units, and sample rows to guide query writing.
health_query: Run read-only DuckDB SELECT statements against the health data, with output as JSON, CSV, or a summary.
health_report: Generate structured weekly, monthly, or custom health summaries, optionally filtering which metrics to include.
Data is loaded from a local Apple Health CSV export (Simple Health Export CSV format) and queried in place without network uploads.
The server enforces safeguards: limits file access to the configured data directory, disables network/temp disk use, and locks database settings.
All tools can access the full exported history, so queries can reach as far back as the export includes.
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 "Deploy 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, analytical 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 one DuckDB SELECT-family analytical statement with JSON, CSV, or summary output |
| 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.
health_query accepts one DuckDB analytical statement. See
Query safeguards
for supported statements and restricted operations.
The server limits DuckDB file access to HEALTH_DATA_DIR. It also disables
network access and temporary disk storage, and it locks the database settings.
The data directory stays readable and writable so the importer can read CSV
files.
These controls reduce accidental side effects from generated SQL. They do not
isolate the process. Run the server through a local stdio MCP client. Do not
expose it to an untrusted network client. Use process or OS isolation if the
server must accept untrusted SQL.
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. See Release procedure for publishing and recovery steps.
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
The Ramp MCP server enables users to securely connect Ramp with AI assistants like ChatGPT and Claude to query financial data and take actions using natural language. It transforms Ramp's developer API into a SQL interface that LLMs can query, allowing admins to analyze spend trends, identify cost savings, and run complex SQL analyses on comprehensive datasets (transactions, purchase orders, vendors, users), while all users can manage cards, view transactions, request reimbursements, and get expense policy answers.
