{
  "markdown": "# Apple Health MCP Server\n\n[![npm version](https://badge.fury.io/js/@neiltron%2Fapple-health-mcp.svg)](https://www.npmjs.com/package/@neiltron/apple-health-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nQuery Apple Health data from an MCP client using SQL and DuckDB. The server runs\nlocally, reads CSV exports on demand, and provides tools for schema discovery,\nread-only queries, and health summaries.\n\n## Requirements\n\n- Node.js 22 or newer\n- An Apple Health CSV export created with\n  [Simple Health Export CSV](https://apps.apple.com/us/app/simple-health-export-csv/id1535380115)\n\nThe native Apple Health `export.xml` format is not currently supported.\n\n## Configure an MCP client\n\nFor Claude Desktop, add the following to\n`~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"apple-health\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@neiltron/apple-health-mcp\"],\n      \"env\": {\n        \"HEALTH_DATA_DIR\": \"/path/to/your/unzipped/health-export\"\n      }\n    }\n  }\n}\n```\n\nRestart the client after changing its configuration. Other MCP clients can use\nthe same command, arguments, environment, and `stdio` transport.\n\n### Environment variables\n\n| Variable | Required | Default | Purpose |\n| --- | --- | --- | --- |\n| `HEALTH_DATA_DIR` | Yes | — | Directory containing the exported CSV files |\n| `MAX_MEMORY_MB` | No | `2048` | DuckDB memory limit in megabytes |\n| `CACHE_SIZE` | No | `100` | Maximum number of cached query results |\n\n## Export health data\n\n1. Install and open Simple Health Export CSV on your iPhone.\n2. Select **All** and choose the time range to export.\n3. Transfer the archive to the computer running your MCP client.\n4. Unzip it and set `HEALTH_DATA_DIR` to the resulting directory.\n\nThe server reads the files in place. It does not upload the export or make\nnetwork requests, although query results returned to your MCP client may be\nsent to that client's configured model provider.\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `health_schema` | Discover table names, columns, units, and sample rows |\n| `health_query` | Run a read-only `SELECT` query with JSON, CSV, or summary output |\n| `health_report` | Generate a weekly, monthly, or custom health summary |\n\nStart with `health_schema`; table names depend on the files in your export.\nSee [Querying Apple Health data](https://github.com/neiltron/apple-health-mcp/blob/main/docs/querying.md)\nfor the data model and working examples.\n\n## History and memory\n\nThe first request that needs a table loads that table's full CSV history. There\nis no date window, so a query can reach as far back as the export goes.\n\nBecause every tool can reach the whole configured history, only start this\nserver from an MCP client you trust with that data.\n\nLoaded tables are held in memory, and DuckDB is given the `MAX_MEMORY_MB` limit\ndescribed above. Roughly 1 GiB covers a two-year multi-table export, so the\n2048MB default leaves headroom; raise `MAX_MEMORY_MB` for a larger export. The\nserver never spills health rows to a temporary directory on disk, so an export\nthat does not fit in the limit fails with an explicit error instead.\n\nOther current limitations:\n\n- Only the Simple Health Export CSV layout is supported.\n- The DuckDB database is in memory and is rebuilt for each server process, so\n  each launch reloads from the CSV files. Persistent incremental import is\n  planned future work, not current behavior.\n- Device overlap can produce duplicate-looking measurements; queries should\n  account for `sourceName` where appropriate.\n- Health reports summarize recorded data and are not medical advice.\n\n## Development\n\n```bash\ngit clone https://github.com/neiltron/apple-health-mcp.git\ncd apple-health-mcp\nbun install\n\nnpm test\nnpm run typecheck\nnpm run build\n```\n\nSee [Architecture](https://github.com/neiltron/apple-health-mcp/blob/main/docs/architecture.md)\nfor the code layout, data lifecycle, and implementation constraints.\n\n## License\n\nMIT\n",
  "bytes": 4039,
  "sha": "460b46d3059449313a718fb9563295fd6604ba04ae0544242dd85b64866df9a3",
  "repo_slug": "neiltron/apple-health-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_neiltron_apple_health_mcp_44c07396/readme"
}