Local-first Apple Health MCP server for questions about your sleep, workouts and heart data.
Apple Health MCP Server (io.github.neiltron/apple-health-mcp)
This Model Context Protocol (MCP) server queries and analyzes Apple Health CSV exports using DuckDB. An MCP client can run SQL against local, read-only data, with tools that support schema discovery, queries, and generated health summaries.
🛠️ Key Features
Uses DuckDB to query Apple Health CSV exports
Works with CSV exports on demand
Supports schema discovery
Provides read-only queries and health summaries
🚀 Use Cases
Analyze quantified-self health data stored as Apple Health CSV exports
Run SQL-based queries over Apple Health datasets via an MCP client
⚡ Developer Benefits
SQL access to Apple Health data through an MCP server
Schema discovery tooling to understand available fields for querying
⚠️ Limitations
Relies on Apple Health CSV exports (source data must be exported first)
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.
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
HEALTH_DATA_DIR
Yes
—
Directory containing the exported CSV files
MAX_MEMORY_MB
No
2048
DuckDB memory limit in megabytes
CACHE_SIZE
No
100
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_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.
Tools
Tool
Purpose
health_schema
Discover table names, columns, units, and sample rows
health_query
Run a read-only SELECT query with JSON, CSV, or summary output
health_report
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.
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 sourceName where appropriate.
Health reports summarize recorded data and are not medical advice.
Development
bash
git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
bun install
npm test
npm run typecheck
npm run build
See Architecture
for the code layout, data lifecycle, and implementation constraints.
