The Health Export AI MCP server exposes your Apple Health data to any MCP client as seven read-only tools. It is zero-dependency, runs entirely on your own machine, and never writes to Apple Health or sends data anywhere.
Last updated 24 July 2026 · source on GitHub · npm: health-export-mcp
An Apple Health MCP server is a Model Context Protocol server that exposes your Apple Health data to AI agents as tools they can call on demand, rather than as a file you paste into a chat. Health Export AI's server reads a local JSON snapshot written by the iOS app and serves it through seven read-only tools, so an agent can ask for a specific metric, trend or date range instead of loading everything into its context.
The practical difference: Apple's own export produces one large export.xml archive that most
tools cannot parse and that will not fit in a model's context window. An MCP server turns the same data into
queryable tools.
The server is a single JavaScript file with no dependencies. It requires Node.js 18 or later.
npx health-export-mcpOr install it globally:
npm install -g health-export-mcpYou can also run the file directly from a clone of the repository — it imports nothing outside Node's standard library, so there is no install step to audit.
.health-cache.json to a location
you choose. On macOS the default is
~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents. Point
HEALTH_DATA_DIR at that folder (see environment variables).
All seven are read-only. None of them can write to Apple Health, and none of them make network requests.
Health check: reports the data source, how many metrics and workouts are available, and the most recent data date. Call this first to confirm the bridge is connected.
{ "ok": true, "source": "file /Users/you/…/.health-cache.json",
"metricCount": 34, "workoutCount": 12, "lastDataDate": "2026-07-24" }Lists every available metric with its unit, day count and date range. Use it to discover exact metric names
before querying — names are snake_case, such as heart_rate_variability.
The core data-retrieval tool. Returns daily values for one metric (or all metrics) over an optional date range, plus an aggregate.
| Parameter | Type | Notes |
|---|---|---|
metric | string | e.g. step_count. Omit for all metrics. |
start, end | string | YYYY-MM-DD, both optional. |
aggregation | string | avg, sum, min, max or latest. Defaults to sum for cumulative metrics, average otherwise. |
Compares the most recent N-day window against the prior N days and returns the change, percent change and direction. This is the tool behind questions like "compare my HRV this week versus last week".
| Parameter | Type | Notes |
|---|---|---|
metric | string | Required. |
window | integer | Days per window. Defaults to 7. |
{ "metric": "heart_rate_variability", "unit": "ms", "window": 7,
"recent": 59.657, "prior": 57.157, "change": 2.5,
"changePercent": 4.374, "direction": "up" }Compares one metric between two arbitrary date periods and returns each aggregate plus the change and percent change. Use it when the two windows are not adjacent — for example this January against last January.
Returns clean structured JSON for the chosen metrics and date range, shaped to drop straight into an agent's context window.
A natural-language convenience tool: pass a question such as "average HRV last month" and it routes to structured results. Prefer the specific tools above when you know which one you need — they are cheaper and more predictable.
Any MCP client works. Replace SERVER_PATH with the path to server.mjs and
HEALTH_DATA_DIR with your export folder.
Edit claude_desktop_config.json and merge into mcpServers, then restart Claude Desktop.
{
"mcpServers": {
"health-export": {
"command": "node",
"args": ["SERVER_PATH"],
"env": { "HEALTH_DATA_DIR": "/path/to/your/export/folder" }
}
}
}Use the CLI — it writes the config for you:
claude mcp add health-export -e HEALTH_DATA_DIR="/path/to/folder" -- node "SERVER_PATH"Claude Code also reads a project-scoped .mcp.json using the same mcpServers shape
as Claude Desktop. If pairing is enabled, do not pass PAIRING_SECRET on the command line — it
would land in your shell history and in ps output. Put it in the config file instead.
Cursor reads ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project), using
the same mcpServers shape shown above.
VS Code's MCP support reads .vscode/mcp.json in the workspace, again with the same server
shape. Reload the window after editing.
Add the server to opencode.json:
{
"mcp": {
"health-export": {
"type": "local",
"command": ["node", "SERVER_PATH"],
"enabled": true,
"environment": { "HEALTH_DATA_DIR": "/path/to/folder" }
}
}
}The server speaks standard MCP over stdio, so any compliant client works — OpenClaw, Hermes, and others.
Point the client at node SERVER_PATH and set HEALTH_DATA_DIR.
| Variable | Purpose |
|---|---|
HEALTH_DATA_DIR | Folder containing .health-cache.json. Defaults to the current directory; on macOS the app's iCloud container is ~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents. A leading ~ is expanded. |
PAIRING_SECRET | Only needed if the iOS app has pairing enabled. Must match the code shown in the app under Settings → Agent pairing. Without it the data tools return a clear "Locked" error rather than an empty result. |
stdio is the primary transport and is what every client config above uses. Streamable HTTP is also supported for clients that need it. There is no hosted endpoint — the server only ever runs on your machine.
Every published artifact is checksummed and signed, so you can confirm you are running exactly what was published before you execute it.
minisign -Vm SHA256SUMS -p minisign.pub
shasum -a 256 -c SHA256SUMSYes. The server makes no network requests, has no dependencies, requires no account, and reads a local file you control. Apple Health access happens only in the iOS app, which requests read-only HealthKit permission and never writes back. Your data goes only to the destination you configure.