Skip to content
Back to search

apple-health-mcp

Local-first Apple Health MCP server. Lets AI assistants answer questions about your sleep, workouts, activity and heart data from a local export.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neiltron--apple-health-mcp/badge.svg)](/listings/neiltron--apple-health-mcp)

HTML

<a href="/listings/neiltron--apple-health-mcp"><img src="/api/listings/neiltron--apple-health-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 130 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Apple Health MCP Server
  2. [![npm version](https://badge.fury.io/js/@neiltron%2Fapple-health-mcp.svg)](https://www.npmjs.com/package/@neiltron/apple-health-mcp)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. Query Apple Health data from an MCP client using SQL and DuckDB. The server runs
  5. locally, reads CSV exports on demand, and provides tools for schema discovery,
  6. analytical queries, and health summaries.
  7. ## Requirements
  8. - Node.js 22 or newer
  9. - An Apple Health CSV export created with
  10. [Simple Health Export CSV](https://apps.apple.com/us/app/simple-health-export-csv/id1535380115)
  11. The native Apple Health `export.xml` format is not currently supported.
  12. ## Configure an MCP client
  13. For Claude Desktop, add the following to
  14. `~/Library/Application Support/Claude/claude_desktop_config.json`:
  15. ```json
  16. {
  17. "mcpServers": {
  18. "apple-health": {
  19. "command": "npx",
  20. "args": ["-y", "@neiltron/apple-health-mcp"],
  21. "env": {
  22. "HEALTH_DATA_DIR": "/path/to/your/unzipped/health-export"
  23. }
  24. }
  25. }
  26. }
  27. ```
  28. Restart the client after changing its configuration. Other MCP clients can use
  29. the same command, arguments, environment, and `stdio` transport.
  30. ### Environment variables
  31. | Variable | Required | Default | Purpose |
  32. | --- | --- | --- | --- |
  33. | `HEALTH_DATA_DIR` | Yes | — | Directory containing the exported CSV files |
  34. | `MAX_MEMORY_MB` | No | `2048` | DuckDB memory limit in megabytes |
  35. | `CACHE_SIZE` | No | `100` | Maximum number of cached query results |
  36. ## Export health data
  37. 1. Install and open Simple Health Export CSV on your iPhone.
  38. 2. Select **All** and choose the time range to export.
  39. 3. Transfer the archive to the computer running your MCP client.
  40. 4. Unzip it and set `HEALTH_DATA_DIR` to the resulting directory.
  41. The server reads the files in place. It does not upload the export or make
  42. network requests, although query results returned to your MCP client may be
  43. sent to that client's configured model provider.
  44. ## Tools
  45. | Tool | Purpose |
  46. | --- | --- |
  47. | `health_schema` | Discover table names, columns, units, and sample rows |
  48. | `health_query` | Run one DuckDB SELECT-family analytical statement with JSON, CSV, or summary output |
  49. | `health_report` | Generate a weekly, monthly, or custom health summary |
  50. Start with `health_schema`; table names depend on the files in your export.
  51. See [Querying Apple Health data](https://github.com/neiltron/apple-health-mcp/blob/main/docs/querying.md)
  52. for the data model and working examples.
  53. `health_query` accepts one DuckDB analytical statement. See
  54. [Query safeguards](https://github.com/neiltron/apple-health-mcp/blob/main/docs/architecture.md#query-safeguards)
  55. for supported statements and restricted operations.
  56. ## Query safeguards
  57. The server limits DuckDB file access to `HEALTH_DATA_DIR`. It also disables
  58. network access and temporary disk storage, and it locks the database settings.
  59. The data directory stays readable and writable so the importer can read CSV
  60. files.
  61. These controls reduce accidental side effects from generated SQL. They do not
  62. isolate the process. Run the server through a local `stdio` MCP client. Do not
  63. expose it to an untrusted network client. Use process or OS isolation if the
  64. server must accept untrusted SQL.
  65. ## History and memory
  66. The first request that needs a table loads that table's full CSV history. There
  67. is no date window, so a query can reach as far back as the export goes.
  68. Because every tool can reach the whole configured history, only start this
  69. server from an MCP client you trust with that data.
  70. Loaded tables are held in memory, and DuckDB is given the `MAX_MEMORY_MB` limit
  71. described above. Roughly 1 GiB covers a two-year multi-table export, so the
  72. 2048MB default leaves headroom; raise `MAX_MEMORY_MB` for a larger export. The
  73. server never spills health rows to a temporary directory on disk, so an export
  74. that does not fit in the limit fails with an explicit error instead.
  75. Other current limitations:
  76. - Only the Simple Health Export CSV layout is supported.
  77. - The DuckDB database is in memory and is rebuilt for each server process, so
  78. each launch reloads from the CSV files. Persistent incremental import is
  79. planned future work, not current behavior.
  80. - Device overlap can produce duplicate-looking measurements; queries should
  81. account for `sourceName` where appropriate.
  82. - Health reports summarize recorded data and are not medical advice.
  83. ## Development
  84. ```bash
  85. git clone https://github.com/neiltron/apple-health-mcp.git
  86. cd apple-health-mcp
  87. bun install
  88. npm test
  89. npm run typecheck
  90. npm run build
  91. ```
  92. See [Architecture](https://github.com/neiltron/apple-health-mcp/blob/main/docs/architecture.md)
  93. for the code layout, data lifecycle, and implementation constraints.
  94. See [Release procedure](https://github.com/neiltron/apple-health-mcp/blob/main/docs/releasing.md)
  95. for publishing and recovery steps.
  96. ## License
  97. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.