Apple Health Semantic

Query your Apple Health export with an LLM, over the Model Context Protocol.

The hard part of this is not moving the data. It is that Apple Health data is full of traps that produce confidently wrong answers: percentages stored as fractions, sleep that changes date at midnight, three apps recording the same steps, device names containing an invisible character that makes LIKE filters match nothing. A model that reads the raw tables will answer fluently and incorrectly, and you will have no way to tell.

So this server ships a semantic layer: for every metric it states what the value means, which aggregate function is valid, and what is known to go wrong — and injects that into the model's context before it writes any SQL.

It optionally imports CPAP therapy data, so a single query can correlate machine data with wearable data.

SELECT o.nightOf, o.ahi, ROUND(AVG(h.value), 1) AS sdnn_ms
FROM oscar_daily o
JOIN hkquantitytypeidentifierheartratevariabilitysdnn h USING (nightOf)
GROUP BY 1, 2 ORDER BY 1;

Quick start

git clone https://github.com/Barbaroso/apple-health-semantic-mcp
cd apple-health-semantic-mcp
npm install

On your iPhone: Health → your profile picture → Export All Health Data. Get the resulting export.zip onto this machine — AirDrop, iCloud Drive, a cable, whatever suits. Do not unzip it; point the tool at the archive as it is.

node bin/cli.js setup /path/to/export.zip --write-config

That one command reads the archive, converts it, imports CPAP data if it finds any, verifies the result, and registers the server with Claude Desktop (keeping a backup of your previous config, and leaving every other server alone). Restart the client and you are done.

For VS Code, Visual Studio, GitHub Copilot or Codex, add --client — see Connecting a client.

Drop --write-config if you would rather paste the configuration yourself — it gets printed either way, in that client's own format, with absolute paths already filled in.

Reading straight from the archive is not just less typing. A real 83 MB export.zip holding a 1.4 GB export.xml converts in 16 seconds, faster than converting the extracted file, because the disk only has to deliver 83 MB. It also saves you 1.4 GB. Memory stays flat regardless of export size: the XML is streamed through a decompressor, never held.

export.xml and the extracted apple_health_export/ folder are accepted too, if you have already unpacked one.

Restart the client and ask something. Good first questions:

• "What's my sleep been like over the last month, and is it trending?"
• "Show me nights where my blood oxygen dropped below 90%."
• "Does my resting heart rate go up after short nights?"

node bin/cli.js convert    --in /path/to/export.zip --out ~/health-data
node bin/cli.js sync-oscar --out ~/health-data          # optional, CPAP
node bin/cli.js doctor     --dir ~/health-data

Connecting a client

setup --write-config targets Claude Desktop unless told otherwise. Each client below has been checked against a running server:

node bin/cli.js setup /path/to/export.zip --client vscode --write-config

Without --write-config the block is printed in that client's own format for you to paste. Nothing is ever rewritten blind: the previous file is copied to a timestamped sibling first, and every other server and unrelated setting is kept.

Three differences matter, because each one produces a client that starts cleanly and then lists no tools at all:

• VS Code and Visual Studio read servers, not mcpServers, and expect an explicit "type": "stdio".
• Codex uses TOML, as [mcp_servers.<name>] with the environment in its own [mcp_servers.<name>.env] table. That file is edited by section rather than parsed and reserialised, so comments and hand-written ordering survive.
• The GitHub Copilot CLI reads its configuration when a session starts. A session that was already open when you added the server keeps its original list; start a new one.

{
  "mcpServers": {
    "apple-health": {
      "command": "node",
      "args": ["/absolute/path/to/apple-health-semantic-mcp/bin/cli.js", "serve"],
      "env": { "HEALTH_DATA_DIR": "/absolute/path/to/health-data" }
    }
  }
}

{
  "servers": {
    "apple-health": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/apple-health-semantic-mcp/bin/cli.js", "serve"],
      "env": { "HEALTH_DATA_DIR": "/absolute/path/to/health-data" }
    }
  }
}

[mcp_servers.apple-health]
command = "node"
args = ["/absolute/path/to/apple-health-semantic-mcp/bin/cli.js", "serve"]

[mcp_servers.apple-health.env]
HEALTH_DATA_DIR = "/absolute/path/to/health-data"

Why a semantic layer

These are real defects in real exports, all of which produce a plausible wrong answer rather than an error.

The last one deserves emphasis, because it is invisible in every tool that displays it. Apple writes device and source names with a NO-BREAK SPACE. A query that looks correct returns zero rows, and the natural conclusion — "this device has no data" — is wrong. The converter normalises it. See docs/DATA-TRAPS.md for the full catalogue.

Tools

health_schema

Lists every table and returns the semantic layer: measurement class, correct aggregate function, units, observed value ranges, recording sources, date coverage, and per-metric caveats. Call this first. Everything else depends on the model having read it.

health_query

Read-only DuckDB SQL. Writes are rejected with an explanation, not a generic failure. Tables load on demand. Rows come back as labelled objects rather than positional arrays, because column misalignment is exactly the class of silent error this project exists to prevent.

If a query names a column that doesn't exist, the error lists the columns that do:

Binder Error: Referenced column "measurementClass" not found ...

Columns that actually exist -> hkquantitytypeidentifierheartrate: type,
sourceName, sourceVersion, unit, startDate, endDate, value, valueText, device,
productType, nightOf. Note that measurementClass, aggregation and caveats are
metadata returned by health_schema, not columns in any table.

health_report

A summary across heart rate, resting heart rate, HRV, sleep, respiratory rate, blood oxygen, activity, workouts and CPAP therapy.

Every section declares how it was computed:

## Sleep  [per night (noon to noon), source: Apple Watch]
   Average 7.81 h across 14 nights (6.65-8.53)
   ! 2 sources recorded this metric. Restricted to 'Apple Watch' (14 days,
     140 readings); combining them would count the same activity more than once.

Three rules are enforced throughout, because breaking any of them yields a number that looks reasonable and is wrong:

1. Nocturnal metrics group by nightOf, never by calendar day. Otherwise a night that crosses midnight is split in two and a fictitious short night drags the average down.
2. Per-day and per-night values are computed first, then averaged. Averaging raw samples weights each day by how often the device happened to sample it.
3. Where several apps recorded the same metric, one source is used and the rest are named in sourcesExcluded.

Choosing the window

Explicit dates take effect on their own — period does not have to be set to custom, and one endpoint is enough:

{ "start_date": "2026-07-22", "end_date": "2026-07-30" }  // exactly those 9 days
{ "start_date": "2026-07-22" }                            // that date to today
{ "period": "week", "end_date": "2026-06-15" }            // the 7 days ending then
{ "period": "quarter" }                                   // 90 days ending today

Named periods are inclusive of both endpoints, so a week is seven days, and they are dated in local time rather than UTC — the same wall-clock the data uses.

Every reply reports the window it actually used, and why:

"period": {
  "start": "2026-07-22", "end": "2026-07-30", "days": 9,
  "basis": "the requested start_date and end_date, inclusive"
}

That field exists because of a shipped defect: dates were honoured only when period was custom, so a caller passing dates the obvious way silently got the default window, correctly computed and confidently labelled. A report on the wrong period is worse than an error — nothing about it looks wrong. An unrecognised parameter is now refused rather than dropped, for the same reason.

Data model

One table per HealthKit type, named after the identifier in lower case (HKQuantityTypeIdentifierHeartRate → hkquantitytypeidentifierheartrate). Every table has exactly these columns:

nightOf

CAST(DATE_TRUNC('day', startDate - INTERVAL 12 HOUR) AS DATE)

A night runs noon to noon and is labelled with the day it began. Sleep starting at 23:40 on the 22nd and sleep starting at 01:10 on the 23rd both belong to nightOf = 2024-01-22.

Measured on a real six-year export: 87% of asleep records are assigned to the wrong night by DATE(startDate). This is not an edge case.

Timestamps are local wall-clock time. The CSV keeps the original UTC offset and the loader truncates it at load, so "last night" means what the wearer would mean by it, in whatever timezone they were in.

CPAP correlation (optional)

If you use a CPAP or BiPAP machine and review your therapy in OSCAR, you can pull the nightly summaries into the same database:

node bin/cli.js sync-oscar --out ~/health-data

This reads the oscar.db that OSCAR 2.x writes in its own data folder — there is no export step, and OSCAR can stay open. The database is copied together with its write-ahead log before being read, so nothing is locked. OSCAR 1.x used a different on-disk layout and is not supported.

This adds an oscar_daily table: one row per night, with AHI, RDI, event counts by class, pressure and leak statistics, usage hours and compliance.

The join needs no date adjustment — OSCAR and this pipeline both define a night as noon-to-noon, so nightOf matches directly.

SELECT o.nightOf,
       o.ahi,
       o.leakTotal95th,
       ROUND(MIN(s.value), 1) AS lowest_spo2
FROM oscar_daily o
JOIN hkquantitytypeidentifieroxygensaturation s USING (nightOf)
WHERE o.maskOnHours >= 4
GROUP BY 1, 2, 3
ORDER BY o.ahi DESC;

Two things worth knowing:

• OSCAR stores "not recorded" as 0 for SpO2 and pulse. If no oximeter was attached, every value is a placeholder. The importer exports these as NULL so the model cannot report a saturation of 0%.
• Apple's "breathing disturbances" metric is not an AHI and the two are not comparable. It is a relative index from a wrist accelerometer; AHI is a count of scored respiratory events per hour from a flow sensor.

This bridge is deliberately narrow: one row per night, enough to correlate therapy with wearable data in a single SQL statement. To interrogate CPAP data on its own — session detail, event clustering through the night, pressure and setting changes — use oscar-mcp, a separate read-only MCP server for exactly that. The two run side by side.

More examples in examples/queries.md.

Configuration

CLI

apple-health-semantic-mcp setup       <export.zip|export.xml|dir> [--out <dir>]
                                      [--client <name>] [--write-config] [--config <path>]
                                      [--memory <mb>] [--no-oscar] [--limit n]
apple-health-semantic-mcp convert     --in <export.zip|export.xml|dir> --out <dir> [--limit n] [--dry]
apple-health-semantic-mcp sync-oscar  --out <dir> [--db <oscar.db>] [--dry]
apple-health-semantic-mcp doctor      [--dir <dir>]
apple-health-semantic-mcp serve

setup is the whole pipeline in one call and is what a first install should use. --client picks which application to configure (claude, vscode, visual-studio, copilot-cli, codex — see Connecting a client); --config overrides the file it would otherwise find for that client. --write-config merges the server in, keeping a timestamped backup and every other server you have; without it the block is printed for you to paste. A configuration file that cannot be parsed is refused rather than overwritten.

doctor is the one to run when something looks wrong. It validates the data directory, loads a table, and checks for un-normalised non-breaking spaces.

Privacy

Everything runs locally. The server reads files on your disk and speaks MCP over stdio; it opens no network connection and sends nothing anywhere. Your data goes to whichever model you have connected, and nowhere else.

.gitignore excludes *.csv, export.xml, semantics.json and *.db, so health data cannot be committed by accident. The test suite generates its own synthetic data — there is no real health data in this repository, and none should ever be added.

This is not a medical device. Consumer wearable data supports trend and correlation analysis, not diagnosis. Wrist reflectance oximetry in particular is not comparable to a pulse oximeter, and Apple's own documentation says so. Take clinical decisions with a clinician.

Development

npm test

75 end-to-end tests. They generate a synthetic export containing every trap listed above, pack it into real ZIP archives (including a ZIP64 one, which is what a multi-gigabyte export produces), convert it, build a synthetic CPAP database, and drive the real server over stdio. Nothing is mocked, so a failure means a client would see the same failure.

test/period.test.js is deliberately exhaustive about report windows. That is where the worst defect in this project's history lived, and it survived a green suite because every test had pinned period: 'custom' — encoding the implementation rather than the requirement. Tests should ask for things the way a caller would.

Requires Node 22.5 or newer (for the built-in node:sqlite).

bin/cli.js       setup | convert | sync-oscar | doctor | serve
src/ontology.js  the semantic layer: every metric's meaning, aggregation, caveats
src/convert.js   streaming export.xml -> CSV + semantics.json
src/zip.js       streaming reader for the archive the phone produces
src/setup.js     one-shot install: convert, verify, configure the client
src/oscar.js     CPAP bridge
src/doctor.js    data directory health checks
src/db.js        DuckDB storage, catalogue, on-demand loading
src/tools.js     the three MCP tools
src/server.js    stdio wiring

The ontology is where contributions are most valuable. If Apple adds a metric, or you find a trap that isn't documented, add it to src/ontology.js and the model will be told about it everywhere.

Related

oscar-mcp — a read-only MCP server for CPAP therapy data, reading OSCAR's own oscar.db directly. Where this project pulls one summary row per night for correlation, that one exposes the therapy data properly: per-session detail, when events clustered during the night, pressure and setting changes. The two run side by side, and an assistant with both can reason across them.

Acknowledgements

The idea of exposing an Apple Health export over MCP comes from @neiltron/apple-health-mcp. This is an independent implementation; several bugs found along the way were reported back upstream.

License

MIT