Apple Health MCP Server
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.
Apple Health MCP Server
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.
Requirements
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
Configure an MCP client
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.
Environment variables
Variable | Required | Default | Purpose |
| Yes | — | Directory containing the exported CSV files |
| No |
| DuckDB memory limit in megabytes |
| No |
| Maximum number of cached query results |
Export health data
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_DIRto 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.
Tools
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.
Query safeguards
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.
History and memory
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
sourceNamewhere appropriate.Health reports summarize recorded data and are not medical advice.
Development
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.
License
MIT
Available Tools
3 toolshealth_queryB
Run one analytical query on Apple Health data.
Inputs: query (required), format.
health_reportB
Generate structured health reports for a specific period
Inputs: report_type (required), end_date, start_date, include_metrics.
health_schemaA
Get information about available health data tables, their structure, and sample data to help write SQL queries
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored 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.
Maintenance
Related MCP Connectors
Hosted Apple Health MCP for Claude and ChatGPT, works outside the US. iPhone app, no local server.
Hosted Apple Health MCP: workouts, sleep and HRV in ChatGPT, Claude, Gemini, Grok. Free, no export.
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
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables seamless interaction between LLM-based agents and Apple Health data, allowing users to query, analyze, and manage health records through natural language commands.7287MIT
- AlicenseBqualityCmaintenanceMCP server for macOS Apple apps. Enables read/write access to Notes, Reminders, Calendar, Contacts, and Safari using SQLite and JXA, all running locally.2811 npm4MIT
- AlicenseBqualityBmaintenanceLocal-first MCP server that connects AI agents to your Oura Ring readiness, sleep, activity, and HRV data. Tokens never leave your machine.27439 npm6MIT
- AlicenseAqualityBmaintenanceOpen-source MCP server for MetricBridge (formerly Health Export AI). 16 tools and 22 prompts let any MCP agent query 190 Apple Health metrics from files on your own machine. The server is read-only, has zero dependencies and makes zero network calls.21561 npm11MIT