\n Give your AI agent your Apple Health activity, sleep, HRV and workouts — from your local export.zip. \n Local-first MCP server — tokens never leave your machine.\n
\n\n
\n \n \n \n \n
\n\n
\n \n \n \n \n
\n\n> ⚡ **One-command install** with [Delx Wellness for Hermes](https://github.com/davidmosiah/delx-wellness-hermes):\n> `npx -y delx-wellness-hermes setup` — preconfigures this connector and the other 8 in a dedicated Hermes profile.\n>\n> Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.\n\n---\n\n## HTTP (v2 stateless)\n\nDefault is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:\n\n```bash\nnpx -y apple-health-mcp-unofficial --http\n# GET http://127.0.0.1:3000/health\n# POST http://127.0.0.1:3000/mcp (sessionless)\n```\n\nEnv: `APPLE_HEALTH_MCP_HOST`, `APPLE_HEALTH_MCP_PORT`, `APPLE_HEALTH_MCP_TRANSPORT=http`.\n\n\n\n\n**Local-first MCP server that reads your Apple Health export and exposes it to AI agents.**\n\n> **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.\n\n> **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.\n\nBuilt by [David Mosiah](https://github.com/davidmosiah) 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.\n\nPart of [Delx Wellness](https://github.com/davidmosiah/delx-wellness), a registry of local-first wellness MCP connectors.\n\n> 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.\n\n## Why this exists\n\nApple 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.\n\nThis 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.\n\n## Setup in 60 seconds\n\n**1. Export your Apple Health data on iPhone:**\n\n```text\nHealth app → tap your profile picture → Export All Health Data\n```\n\nWait a few minutes. AirDrop or transfer the zip to this machine.\n\n**2. Configure and verify:**\n\n```bash\nnpx -y apple-health-mcp-unofficial setup --export-path /path/to/export.zip\nnpx -y apple-health-mcp-unofficial doctor\n```\n\nOr let the CLI find the newest local export in `Downloads`, `Desktop` or `Documents`, copy it into managed local storage, and save that path:\n\n```bash\nnpx -y apple-health-mcp-unofficial setup --auto-import\n```\n\nSupported export paths:\n- `/path/to/export.zip`\n- `/path/to/apple_health_export/` (unzipped folder)\n- `/path/to/export.xml` (raw export file)\n\n**Keep it fresh — watch a folder (no macOS needed):**\n\nApple 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:\n\n```bash\nnpx -y apple-health-mcp-unofficial setup --watch-path /path/to/health-exports\n```\n\nNow 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.\n\nThen add this to your MCP client config:\n\n\n\n```json\n{\n \"mcpServers\": {\n \"apple_health\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"apple-health-mcp-unofficial\"]\n }\n }\n}\n```\n\nFor Claude Desktop, run `setup --client claude --export-path /path/to/export.zip` and the snippet is written for you.\n\n## Try it with your agent\n\nThree things to ask first:\n\n```text\nUse apple_health_connection_status to check setup, then run apple_health_daily_summary.\nGive me a 5-line wellness brief for today.\n```\n\n```text\nCall apple_health_data_inventory first. What Apple Health signals and date ranges\nare available in this export?\n```\n\n```text\nCall apple_health_weekly_summary with response_format=json. Compare steps,\nsleep, workouts and heart signals across the last 7 days.\n```\n\n```text\nUse the apple_health_weekly_review prompt, days=14.\nFind the biggest habit pattern and suggest one experiment.\n```\n\n## Data availability\n\nThis 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.\n\n| Data | Available | Notes |\n|---|:---:|---|\n| Activity (steps, distance, energy, exercise) | ✓ | Standard `HKQuantityType` records |\n| Heart rate (resting + samples) | ✓ | Recorded HR samples and resting HR |\n| Sleep analysis + sleep stages | ✓ | When iPhone/Watch logs sleep |\n| Workouts + sport metadata | ✓ | All `HKWorkout` entries |\n| Body measurements (weight, BMI, body fat) | ✓ | When the user logs them |\n| HRV (SDNN) + breathing rate | ✓ | When Watch supports them |\n| ECG records | ✓ (metadata) | Apple Watch ECG events; raw waveform requires PDF export |\n| Live HealthKit access | — | Apple does not expose a public live API |\n| iCloud Health sync | — | Not exposed by export files |\n\n## Tools\n\n**Start with these:**\n\n- `apple_health_connection_status` — verify export path before reading data\n- `apple_health_data_inventory` — discover available record types, date coverage, sources count and stale export risk\n- `apple_health_daily_summary` — daily wellness brief from export data\n- `apple_health_weekly_summary` — weekly comparison and habit signals\n\n**Diagnostics**\n\n- `apple_health_capabilities`, `apple_health_agent_manifest`, `apple_health_privacy_audit`\n\n**Records**\n\n- `apple_health_list_records` — bounded records by `type` (e.g. `HKQuantityTypeIdentifierStepCount`), `start`, `end`, `limit`. `limit` caps the returned **list** only: in the default `summary` privacy mode the `aggregate` block (`count_by_type`, `units`, `date_range`, `numeric`) is computed over every record matching the filter, and `truncated` / `limit_applied` / `matched_count` tell you whether the list itself was cut. The statistics live **under `numeric`** (`numeric.min` / `numeric.max` / `numeric.sum` / `numeric.average` / `numeric.count`), not at the top of `aggregate` — see [What a payload looks like](#what-a-payload-looks-like)\n- `apple_health_list_workouts` — bounded workouts by `start`, `end`, `limit`. Same contract: `limit` caps the returned **list** only, and in `summary` privacy mode the `aggregate` totals (`count_by_activity`, `date_range`, `total_duration_minutes`, `total_distance`, `distance_units`, `total_energy_kcal`, `workout_count`) cover every workout matching the filter, with `truncated` / `limit_applied` / `matched_count` reporting whether the list was cut\n\n**Keeping data fresh**\n\n- `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\n\n### What a list call costs\n\n`limit` bounds the **output**, not the work. In the default `summary` privacy mode the aggregate has to describe every matching record, so the scan cannot stop at the cap — it streams `export.xml` to the end. Narrowing with `type`, `start` or `end` does **not** shorten it: a match could still sit in the last byte, so the file is read in full either way.\n\nMeasured on synthetic exports (Node 23, macOS, warm page cache), for one `apple_health_list_records` call in summary mode:\n\n| export.xml | first call, summary mode | same call repeated | same call, `privacy_mode: \"raw\"` |\n|---|---|---|---|\n| 84 MB (353k records) | ~3.0 s | <1 ms | ~1 ms |\n| 336 MB (1.4M records) | ~11.3 s | <1 ms | ~2 ms |\n\nRoughly **33 ms per MB**, linear in file size. A cold first read of a large export — before the OS has the file cached — costs noticeably more (~29 s was observed for 336 MB).\n\nPractical guidance:\n\n- **Identical repeat queries are free.** Results are memoized in memory per export file, keyed on path + size + mtime. Promoting a new export (or `apple_health_reimport`) invalidates them, so a stale export is never served.\n- **`apple_health_daily_summary`, `apple_health_weekly_summary` and `apple_health_data_inventory` share a separate snapshot cache** and were already paying one full parse; they are not affected by this.\n- **Need a quick page rather than statistics?** `privacy_mode: \"structured\"` or `\"raw\"` stops the scan at `limit` and returns in about a millisecond — at the cost of returning individual records instead of an aggregate.\n- **`apple_health_list_workouts` reaches the end of the file in every mode**, because workouts are sparse: an export rarely holds enough `Workout` elements to fill even the default page of 50.\n- `incremental_cache: true` is never memoized — it advances a persistent per-category cursor, so each call must actually run.\n\n### What a payload looks like\n\nSynthetic values, real shape. `npm run test:readme-contract` calls the actual server against the repo fixture and fails if any key below stops existing — or if the server starts returning a key this section does not show.\n\n\n\n```json\n{\n \"source\": \"apple_health_export\",\n \"type\": \"HKQuantityTypeIdentifierHeartRate\",\n \"privacy_mode\": \"summary\",\n \"count\": 50,\n \"limit_applied\": 50,\n \"truncated\": true,\n \"matched_count\": 2847,\n \"records\": [],\n \"aggregate\": {\n \"count_by_type\": { \"HKQuantityTypeIdentifierHeartRate\": 2847 },\n \"units\": [\"count/min\"],\n \"date_range\": {\n \"first\": \"2026-04-01T03:12:00.000Z\",\n \"last\": \"2026-04-30T23:41:00.000Z\",\n \"first_date\": \"2026-04-01\",\n \"last_date\": \"2026-04-30\"\n },\n \"numeric\": { \"count\": 2847, \"sum\": 202137, \"average\": 71, \"min\": 48, \"max\": 174 }\n },\n \"aggregate_scope\": \"all_matching_records\",\n \"disclosure\": \"summary_mode_omits_individual_records_aggregate_covers_all_matching_records\"\n}\n```\n\n`records` is empty in `summary` mode by design — the aggregate replaces the individual samples. `count` still reports how many records the scan paged in; `matched_count` is the full match set the aggregate covers.\n\n\n\n```json\n{\n \"source\": \"apple_health_export\",\n \"privacy_mode\": \"summary\",\n \"count\": 12,\n \"limit_applied\": 50,\n \"truncated\": false,\n \"matched_count\": 12,\n \"workouts\": [],\n \"aggregate\": {\n \"count_by_activity\": {\n \"HKWorkoutActivityTypeRunning\": 8,\n \"HKWorkoutActivityTypeTraditionalStrengthTraining\": 4\n },\n \"date_range\": {\n \"first\": \"2026-04-02T21:10:00.000Z\",\n \"last\": \"2026-04-29T22:05:00.000Z\",\n \"first_date\": \"2026-04-02\",\n \"last_date\": \"2026-04-29\"\n },\n \"total_duration_minutes\": 486.5,\n \"total_distance\": 62.4,\n \"distance_units\": [\"km\"],\n \"total_energy_kcal\": 5820,\n \"workout_count\": 12\n },\n \"aggregate_scope\": \"all_matching_workouts\",\n \"disclosure\": \"summary_mode_omits_individual_workouts_aggregate_covers_all_matching_workouts\"\n}\n```\n\n## Prompts\n\n- `apple_health_daily_review` — daily wellness review with non-medical framing\n- `apple_health_weekly_review` — weekly habit signals and trend comparison\n\n## Resources\n\n- `apple-health://capabilities`, `apple-health://agent-manifest`\n- `apple-health://inventory`, `apple-health://summary/daily`, `apple-health://summary/weekly`\n\n## Privacy & security\n\n- Apple Health exports are highly sensitive personal health data. Keep them local.\n- Never commit `export.xml` / `export.zip` to GitHub, paste raw exports into chat, or upload them to issues.\n- The export path is read-only; the MCP never modifies your export.\n- `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.\n- This is **not medical advice**. The server exposes data you exported yourself for personal AI workflows, not diagnosis or emergency monitoring.\n\n## Configuration\n\n```bash\nAPPLE_HEALTH_EXPORT_PATH=/path/to/export.zip # or export.xml or apple_health_export/\nAPPLE_HEALTH_PRIVACY_MODE=summary # summary | structured | raw\nAPPLE_HEALTH_TIMEZONE=America/Fortaleza # local-day summaries; defaults to UTC unless setup saves a timezone\nAPPLE_HEALTH_WATCH_PATH=/path/to/health-exports # optional: auto-reimport the newest export dropped here\n```\n\n`setup` writes these settings into `~/.apple-health-mcp/config.json` with `0600` permissions.\n\n`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.\n\n`setup --watch-path ` (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.\n\n## Hermes / remote setup\n\n```bash\nnpx -y apple-health-mcp-unofficial setup --client hermes --export-path /path/to/export.zip\nnpx -y apple-health-mcp-unofficial doctor --client hermes\nhermes mcp test apple_health\n```\n\nAfter Hermes config changes, use `/reload-mcp` or `hermes mcp test apple_health`. Don't restart the gateway for normal export access.\n\nIf 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`.\n\n## Requirements\n\n- Node.js 20+\n- An Apple Health export from your iPhone (Health app → profile → Export All Health Data)\n\n## Development\n\n```bash\ngit clone https://github.com/davidmosiah/apple-health-mcp.git\ncd apple-health-mcp\nnpm install\nnpm test\nnpm run build\n```\n\nTest with MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\nOptional local HTTP transport:\n\n```bash\nAPPLE_HEALTH_MCP_TRANSPORT=http APPLE_HEALTH_MCP_PORT=3000 node dist/index.js\ncurl http://127.0.0.1:3000/health\n```\n\n## Links\n\n- npm: \n- Docs site: \n- GitHub: \n- Delx Wellness registry: \n- Connector quality standard: \n- Apple Health export how-to: \n\n\n\n## See also\n\nThe full [Delx Wellness](https://wellness.delx.ai) connector library:\n\n| Provider | Package | Repo |\n|---|---|---|\n| WHOOP | [`whoop-mcp-unofficial`](https://www.npmjs.com/package/whoop-mcp-unofficial) | [whoop-mcp](https://github.com/davidmosiah/whoop-mcp) |\n| Oura | [`oura-mcp-unofficial`](https://www.npmjs.com/package/oura-mcp-unofficial) | [ouramcp](https://github.com/davidmosiah/ouramcp) |\n| Garmin | [`garmin-mcp-unofficial`](https://www.npmjs.com/package/garmin-mcp-unofficial) | [garminmcp](https://github.com/davidmosiah/garminmcp) |\n| Strava | [`strava-mcp-unofficial`](https://www.npmjs.com/package/strava-mcp-unofficial) | [strava-mcp](https://github.com/davidmosiah/strava-mcp) |\n| Fitbit | [`fitbit-mcp-unofficial`](https://www.npmjs.com/package/fitbit-mcp-unofficial) | [fitbitmcp](https://github.com/davidmosiah/fitbitmcp) |\n| Withings | [`withings-mcp-unofficial`](https://www.npmjs.com/package/withings-mcp-unofficial) | [withingsmcp](https://github.com/davidmosiah/withingsmcp) |\n| Apple Health | [`apple-health-mcp-unofficial`](https://www.npmjs.com/package/apple-health-mcp-unofficial) | [apple-health-mcp](https://github.com/davidmosiah/apple-health-mcp) |\n| Polar | [`polar-mcp-unofficial`](https://www.npmjs.com/package/polar-mcp-unofficial) | [polarmcp](https://github.com/davidmosiah/polarmcp) |\n| Nourish (nutrition) | [`wellness-nourish`](https://www.npmjs.com/package/wellness-nourish) | [wellness-nourish](https://github.com/davidmosiah/wellness-nourish) |\n\n**One-command setup for Hermes** — preconfigures every connector above plus wellness skills + onboarding: [`delx-wellness-hermes`](https://github.com/davidmosiah/delx-wellness-hermes).\n\n\n\n## 📧 Contact & Support\n\n- 📨 **support@delx.ai** — general questions, integration help, partnerships\n- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/davidmosiah/apple-health-mcp/issues)\n- 🐦 **Updates** — [@delx369](https://x.com/delx369) on X\n- 🌐 **Site** — [wellness.delx.ai](https://wellness.delx.ai)\n\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Disclaimer\n\nThis 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.\n\n## Skill or MCP\n\nSame package, two doors. MCP registers tools on stdio/HTTP. The [skill](skill/SKILL.md) can drive the **same** tools through the CLI when the client has no MCP:\n\n```bash\nnpx -y apple-health-mcp-unofficial call apple_health_connection_status --json '{}'\n```\n\nCopy `skill/SKILL.md` into your agent skills dir.\n",
"bytes": 20736,
"sha": "c1dd2320cf155c955477d99b430e160b39ecf810445ea65be71ae4c2bbb63649",
"repo_slug": "davidmosiah/apple-health-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_davidmosiah_apple_health_mcp_9125d422/readme"
}
![\"Apple](\"assets/banner.png\")
\n![\"npm](\"https://img.shields.io/npm/v/apple-health-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white\")
![\"npm](\"https://img.shields.io/npm/dm/apple-health-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white\")
![\"License](\"https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"Site\"](\"https://img.shields.io/badge/SITE-wellness.delx.ai-0EA5A3?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/davidmosiah/apple-health-mcp?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github\")
![\"Built](\"https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"Hermes](\"https://img.shields.io/badge/HERMES-one--command_setup-10B981?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"Apple](\"https://img.shields.io/badge/Apple%20Health-FA243C?style=for-the-badge&labelColor=0F172A&logoColor=white&logo=apple&logoColor=white\"){kind=icon}