apple-health-mcp-server

Local-first MCP server that reads your Apple Health export and exposes it to AI agents.

Unofficial project. Not affiliated with, endorsed by or supported by Apple Inc. Apple Health is a trademark of Apple Inc. This package reads exports you generate yourself from the Apple Health app.

No live HealthKit access. This connector reads export.xml / export.zip files exported from your iPhone. A native iOS HealthKit bridge is a separate future component.

Built by David Mosiah for people who use Claude, Cursor, Hermes, OpenClaw or other MCP-compatible agents to think about long-term health and activity trends — without copy-pasting numbers from the Health app.

Part of Delx Wellness, a registry of local-first wellness MCP connectors.

Why this exists

Apple Health is the most complete personal health dataset most people own — years of activity, heart rate, sleep, workouts, body measurements, even ECGs. But Apple does not expose a public cloud API. The data lives on the iPhone behind HealthKit, and the only practical way to bring it off-device today is the Health Export feature inside the Health app.

This package reads that export locally — either the raw export.xml, the unzipped folder, or the export.zip — and exposes Apple Health through the Model Context Protocol. No tokens, no OAuth, no cloud sync. The export never leaves your machine.

Setup in 60 seconds

1. Export your Apple Health data on iPhone:

Health app → tap your profile picture → Export All Health Data

Wait a few minutes. AirDrop or transfer the zip to this machine.

2. Configure and verify:

npx -y apple-health-mcp-unofficial setup --export-path /path/to/export.zip
npx -y apple-health-mcp-unofficial doctor

Supported export paths:

/path/to/export.zip
/path/to/apple_health_export/ (unzipped folder)
/path/to/export.xml (raw export file)

Then add this to your MCP client config:

{
  "mcpServers": {
    "apple_health": {
      "command": "npx",
      "args": ["-y", "apple-health-mcp-unofficial"]
    }
  }
}

For Claude Desktop, run setup --client claude --export-path /path/to/export.zip and the snippet is written for you.

Try it with your agent

Three things to ask first:

Use apple_health_connection_status to check setup, then run apple_health_daily_summary.
Give me a 5-line wellness brief for today.

Call apple_health_weekly_summary with response_format=json. Compare steps,
sleep, workouts and heart signals across the last 7 days.

Use the apple_health_weekly_review prompt, days=14.
Find the biggest habit pattern and suggest one experiment.

Data availability

This package parses Apple Health exports from the Health app. When this README says raw, it means the upstream XML record fields — not raw HealthKit data.

Data	Available	Notes
Activity (steps, distance, energy, exercise)	✓	Standard `HKQuantityType` records
Heart rate (resting + samples)	✓	Recorded HR samples and resting HR
Sleep analysis + sleep stages	✓	When iPhone/Watch logs sleep
Workouts + sport metadata	✓	All `HKWorkout` entries
Body measurements (weight, BMI, body fat)	✓	When the user logs them
HRV (SDNN) + breathing rate	✓	When Watch supports them
ECG records	✓ (metadata)	Apple Watch ECG events; raw waveform requires PDF export
Live HealthKit access	—	Apple does not expose a public live API
iCloud Health sync	—	Not exposed by export files

Tools

Start with these:

apple_health_connection_status — verify export path before reading data
apple_health_daily_summary — daily wellness brief from export data
apple_health_weekly_summary — weekly comparison and habit signals

Diagnostics

apple_health_capabilities, apple_health_agent_manifest, apple_health_privacy_audit

Records

apple_health_list_records — bounded records by type (e.g. HKQuantityTypeIdentifierStepCount), start, end, limit
apple_health_list_workouts — bounded workout records

Prompts

apple_health_daily_review — daily wellness review with non-medical framing
apple_health_weekly_review — weekly habit signals and trend comparison

Resources

apple-health://capabilities, apple-health://agent-manifest
apple-health://summary/daily, apple-health://summary/weekly

Privacy & security

Apple Health exports are highly sensitive personal health data. Keep them local.
Never commit export.xml / export.zip to GitHub, paste raw exports into chat, or upload them to issues.
The export path is read-only; the MCP never modifies your export.
APPLE_HEALTH_PRIVACY_MODE defaults to summary for this connector (more conservative than other Delx Wellness connectors) since the dataset is rich and sensitive. Raw record dumps are opt-in.
This is not medical advice. The server exposes data you exported yourself for personal AI workflows, not diagnosis or emergency monitoring.

Configuration

APPLE_HEALTH_EXPORT_PATH=/path/to/export.zip   # or export.xml or apple_health_export/
APPLE_HEALTH_PRIVACY_MODE=summary              # summary | structured | raw

setup writes both into ~/.apple-health-mcp/config.json with 0600 permissions.

Hermes / remote setup

npx -y apple-health-mcp-unofficial setup --client hermes --export-path /path/to/export.zip
npx -y apple-health-mcp-unofficial doctor --client hermes
hermes mcp test apple_health

After Hermes config changes, use /reload-mcp or hermes mcp test apple_health. Don't restart the gateway for normal export access.

If the Hermes server runs on a different machine than your iPhone, transfer the export there and point --export-path at it. The export file should be chmod 600.

Requirements

Node.js 20+
An Apple Health export from your iPhone (Health app → profile → Export All Health Data)

Development

git clone https://github.com/davidmosiah/apple-health-mcp.git
cd apple-health-mcp
npm install
npm test
npm run build

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Optional local HTTP transport:

APPLE_HEALTH_MCP_TRANSPORT=http APPLE_HEALTH_MCP_PORT=3000 node dist/index.js
curl http://127.0.0.1:3000/health

License

MIT — see LICENSE.

Disclaimer

This software is provided as-is. It is not a medical device, does not provide medical advice, and should not be used for diagnosis, treatment or emergency monitoring. Always consult qualified professionals for medical concerns.

apple-health-mcp