Apple Health MCP Server

Query Apple Health data from an MCP client using SQL and DuckDB. The server runs locally, reads CSV exports on demand, and provides tools for schema discovery, read-only queries, and health summaries.

Requirements

• Node.js 22 or newer
• An Apple Health CSV export created with Simple Health Export CSV

The native Apple Health export.xml format is not currently supported.

Configure an MCP client

For Claude Desktop, add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "apple-health": {
      "command": "npx",
      "args": ["-y", "@neiltron/apple-health-mcp"],
      "env": {
        "HEALTH_DATA_DIR": "/path/to/your/unzipped/health-export"
      }
    }
  }
}

Restart the client after changing its configuration. Other MCP clients can use the same command, arguments, environment, and stdio transport.

Environment variables

Export health data

1. Install and open Simple Health Export CSV on your iPhone.
2. Select All and choose the time range to export.
3. Transfer the archive to the computer running your MCP client.
4. Unzip it and set HEALTH_DATA_DIR to the resulting directory.

The server reads the files in place. It does not upload the export or make network requests, although query results returned to your MCP client may be sent to that client's configured model provider.

Tools

Start with health_schema; table names depend on the files in your export. See Querying Apple Health data for the data model and working examples.

Current limitation: 90-day window

When a table is first queried, the server currently loads only rows whose startDate is within the last 90 days. This is a hard-coded implementation limit, not a configurable query default. Older data remains in the CSV files but is unavailable to tools, and an older export may appear empty. Removing or making this behavior configurable is planned.

Other current limitations:

• Only the Simple Health Export CSV layout is supported.
• The DuckDB database is in memory and is rebuilt for each server process.
• Device overlap can produce duplicate-looking measurements; queries should account for sourceName where appropriate.
• Health reports summarize recorded data and are not medical advice.

Development

git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
bun install

npm test
npm run typecheck
npm run build

See Architecture for the code layout, data lifecycle, and implementation constraints.

License

MIT