io.github.davidmosiah/apple-health-mcp

⚡ One-command install with Delx Wellness for Hermes: npx -y delx-wellness-hermes setup — preconfigures this connector and the other 8 in a dedicated Hermes profile.

Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.

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.

If this connector helps your agent workflow, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure.

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

Or let the CLI find the newest local export in Downloads, Desktop or Documents, copy it into managed local storage, and save that path:

npx -y apple-health-mcp-unofficial setup --auto-import

Supported export paths:

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

Keep it fresh — watch a folder (no macOS needed):

Apple Health is a manual export, so the usual pain is that your data goes stale the moment you stop re-running setup. Point the connector at a folder you drop new exports into:

npx -y apple-health-mcp-unofficial setup --watch-path /path/to/health-exports

Now every time you export from your iPhone and drop the new export.zip (or export.xml, or unzipped apple_health_export/) into that folder, the connector auto-promotes the newest one to be the active export — on server startup and live while it runs — and refreshes the cached summaries. You can also trigger a re-scan on demand with the apple_health_reimport tool. This is the cross-platform recurring-refresh path; a fully live HealthKit bridge still needs a native macOS/iOS component.

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_data_inventory first. What Apple Health signals and date ranges
are available in this export?

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.

Tools

Start with these:

• apple_health_connection_status — verify export path before reading data
• apple_health_data_inventory — discover available record types, date coverage, sources count and stale export risk
• 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

Keeping data fresh

• apple_health_reimport — re-scan the watch folder (APPLE_HEALTH_WATCH_PATH) and promote the newest export, refreshing summaries; pass check_only: true to preview without promoting

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://inventory, 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. In summary mode, low-level list tools return aggregates instead of individual records. 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
APPLE_HEALTH_TIMEZONE=America/Fortaleza        # local-day summaries; defaults to UTC unless setup saves a timezone
APPLE_HEALTH_WATCH_PATH=/path/to/health-exports # optional: auto-reimport the newest export dropped here

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

setup --auto-import scans common local folders for the newest Apple Health export and copies it to ~/.apple-health-mcp/exports/ with 0600 permissions. This automates the local import step after you transfer the export from the iPhone. Fully live HealthKit sync still requires a separate native bridge; this Node MCP intentionally reads local exports only.

setup --watch-path <dir> (or APPLE_HEALTH_WATCH_PATH) makes the connector treat a folder as a drop zone. On startup, while running (via filesystem events), and whenever the apple_health_reimport tool is called, it promotes the newest Apple Health export found there — export.xml, export.zip, an apple_health_export/ directory, or any *apple*health*.zip — to be the active export and clears the snapshot + incremental caches so the next summary reflects the new data. apple_health_connection_status reports the watch folder state and warns when a newer export is waiting.

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

Links

• npm: https://www.npmjs.com/package/apple-health-mcp-unofficial
• Docs site: https://wellness.delx.ai/connectors/apple-health
• GitHub: https://github.com/davidmosiah/apple-health-mcp
• Delx Wellness registry: https://github.com/davidmosiah/delx-wellness
• Connector quality standard: https://github.com/davidmosiah/delx-wellness/blob/main/docs/connector-quality-standard.md
• Apple Health export how-to: https://support.apple.com/guide/iphone/share-health-and-fitness-data-iph27f6325b2/ios

See also

The full Delx Wellness connector library:

One-command setup for Hermes — preconfigures every connector above plus wellness skills + onboarding: delx-wellness-hermes.

📧 Contact & Support

• 📨 support@delx.ai — general questions, integration help, partnerships
• 🐛 Bug reports / feature requests — GitHub Issues
• 🐦 Updates — @delx369 on X
• 🌐 Site — wellness.delx.ai

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.