apple-health-mcp: querying Apple Health exports from an MCP client

The gap between an Apple Health export and a question you can actually ask

Apple Health keeps years of sleep stages, workouts, step counts and heart measurements, but the export is a file, not a query interface. Simple Health Export CSV produces one CSV per data type; the server turns those files into DuckDB tables and exposes three tools over stdio: health_schema for discovery, health_query for read-only SELECT statements, and health_report for weekly, monthly or custom summaries. The audience is narrow and specific: people who already run an MCP client such as Claude Desktop, are comfortable with SQL, and want answers like average resting heart rate per month without opening a spreadsheet. It is not a dashboard, and it is not a sync service. Nothing leaves the machine except the query results your client sends to its own model provider, which the README states plainly.

How DuckDB tables get built from your CSV export

The server runs locally and reads the CSV files in place. There is no import step and no persistent database: the first request that touches a table loads that table's full CSV history, and the in-memory DuckDB instance is rebuilt for each server process, so every launch reloads from disk. Table names depend on which files exist in your export, which is why the README says to start with health_schema rather than guessing a table name. Memory is bounded by MAX_MEMORY_MB, default 2048, and the server never spills health rows to a temporary directory. The README estimates roughly 1 GiB for a two-year multi-table export, so the default leaves headroom; an export that does not fit fails with an explicit error instead of degrading quietly. The lifecycle choice is deliberate and it has a cost: restart the process and you pay the CSV load again. The README lists persistent incremental import as planned future work, not current behavior.

Installing apple-health-mcp and asking your first question

The server is published on npm as @neiltron/apple-health-mcp and requires Node.js 22 or newer. You do not install it globally for client use; the client launches it with npx. For Claude Desktop, the README gives this configuration for ~/Library/Application Support/Claude/claude_desktop_config.json, where HEALTH_DATA_DIR points at the unzipped export directory:

{
  "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 editing the file. Other MCP clients use the same command, arguments, environment and stdio transport. Two optional variables matter once you have data: MAX_MEMORY_MB (default 2048) and CACHE_SIZE (default 100, the maximum number of cached query results). To build from source instead, the README documents this sequence:

git clone https://github.com/neiltron/apple-health-mcp.git
cd apple-health-mcp
bun install
npm test
npm run typecheck
npm run build

The first real use is discovery, not analysis. Ask the client to call health_schema and read the table names, columns, units and sample rows it returns. Only then write a SELECT against a real column. If health_schema returns tables you did not expect, your export layout differs from the Simple Health Export CSV layout the server supports.

Where the design breaks: memory ceilings, device overlap and export format

The hard limit is memory. Because the full history of a table is loaded with no date window, a large multi-year export can exceed MAX_MEMORY_MB and fail outright. Raising the limit is the documented remedy, and it moves the problem to your machine rather than solving it. Duplicate-looking measurements are the second trap: when more than one device records the same metric, rows can look like duplicates, and the README advises queries to account for sourceName where appropriate. A naive SUM over steps or heart rate can therefore overcount, and nothing in the server stops you. The third constraint is format. Only the Simple Health Export CSV layout is supported, and the native Apple Health export.xml is explicitly not supported today. Finally, the trust boundary is real: every tool can reach the whole configured history, so the README says to start the server only from an MCP client you trust with that data. Health reports summarize recorded data and are not medical advice.

How it differs from health apps and from writing your own DuckDB script

The obvious alternative is doing this yourself: export the CSVs, open DuckDB or SQLite in a shell, and write the queries by hand. That gives you full control, persistent tables and no memory ceiling tied to a server process, but you lose the conversational layer entirely and you re-implement schema discovery every time the export changes. The other alternative is a hosted health analytics product, which typically asks you to upload or sync your data and gives you fixed charts instead of arbitrary SQL. The trade here is the opposite: no upload, no charts, and the query language is yours to get wrong. Compared with a general-purpose MCP filesystem or database server pointed at the same CSVs, this project's value is the health-specific surface: health_schema understands units and sample rows, health_report produces weekly and monthly summaries directly, and the CSV layout of Simple Health Export CSV is handled for you. If your export is already in a warehouse and you have a SQL client you like, a generic database MCP server may be the simpler path.

Maintenance, versioning and what the MIT licence leaves you to handle

The repository is not archived and the last push was on 2026-08-27, with releases v1.4.0 and v1.4.1 in August 2026 and package.json at version 1.4.2. The project is small and the dependency surface is short: @modelcontextprotocol/sdk and duckdb, with engines pinned to Node.js >=22.0.0 and a pnpm onlyBuiltDependencies entry for duckdb, which means the native DuckDB module is built during install under pnpm. The build script marks duckdb as external, so the published dist expects the native module to be present. Upgrade cost is mostly the DuckDB native dependency and the MCP SDK; because there is no persistent database, upgrading the server cannot corrupt stored state, only change how CSVs are interpreted. The MIT licence permits commercial and private use and modification, and it ships with no warranty, which matters for anything you might later treat as health information. That is a description of the licence text, not legal advice; if you plan to redistribute the server inside a product, read the LICENSE file yourself.

Editorial conclusion

Adopt it if you already use Simple Health Export CSV, run Node.js 22 or newer, and want an assistant to answer SQL questions over a local export without uploading anything. Skip it if your only data is the native export.xml, if you need a persistent database that survives restarts, or if you cannot give the server access to your entire history. Before trusting a number, verify three things: that your export layout matches the CSV files the server expects, that your MAX_MEMORY_MB setting covers the export size, and that duplicate-looking rows from overlapping devices are filtered by sourceName in your query.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. neiltron/apple-health-mcp on GitHub
4. README
5. Releases