health-export-mcp

An MCP server for your own Apple Health data. 194 metrics, 18 tools (16 read-only, plus two that log events to their own file) and 22 prompts over local stdio, with zero dependencies, no account and no server of ours in the path. Your agent gets JSON with units, date ranges and coverage, and answers from your numbers.

<p align="center"> <a href="https://www.npmjs.com/package/health-export-mcp"><img alt="npm" src="https://img.shields.io/npm/v/health-export-mcp?color=cb3837" /></a> <a href="https://github.com/PhilipAD/health-export-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/PhilipAD/health-export-mcp/actions/workflows/ci.yml/badge.svg" /></a> <a href="SECURITY.md"><img alt="npm provenance" src="https://img.shields.io/badge/npm-provenance-2ea44f" /></a> <img alt="dependencies: 0" src="https://img.shields.io/badge/dependencies-0-2ea44f" /> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" /></a> <a href="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp"><img alt="Glama score" src="https://glama.ai/mcp/servers/PhilipAD/health-export-mcp/badges/score.svg" /></a> </p>

Docs and per-client config: healthexport.dev/mcp · agents can run the setup from SKILL.md · privacy: the server reads a local file and makes no network requests, so your health data never reaches us or a cloud AI through it.

Install: one command

claude mcp add health-export -- npx -y health-export-mcp

On a Mac that is the whole install: since 1.7.3 the server finds the MetricBridge app's iCloud Drive folder by itself. On Windows or Linux, or for an export in another folder, add --env "HEALTH_DATA_DIR=/path/to/folder" before the --. Needs Node.js 18 or later. Claude Desktop: open health-export.mcpb instead (no JSON, no Node on your PATH). Cursor, VS Code, opencode, OpenClaw, Hermes: AGENTS.md.

Then ask "Use health-export: how did my HRV this week compare with last week?" The agent calls get_trends and gets numbers that carry their own provenance: unit, exact date ranges, whether each window was complete, and how much history the export holds. This is the real output on 1.7.3 (from the built-in --demo dataset, which is synthetic so it can be published; a real export answers with the same fields and without the watermark):

[SYNTHETIC DEMO DATA] {"metric":"heart_rate_variability","unit":"ms","window":7,"recent":50.859,"prior":51.306,
 "change":-0.447,"changePercent":-0.871,"direction":"flat","recentRange":{"from":"2026-08-12","to":"2026-08-18"},
 "recentDays":7,"priorDays":7,"windowSatisfied":true,"coverage":{"firstDate":"2025-07-15","lastDate":"2026-08-18","days":400}}

No iPhone yet? claude mcp add health-export-demo -- npx -y health-export-mcp --demo serves that watermarked synthetic dataset, so you can try every tool in 30 seconds before installing anything on a phone.

Use your real data (about 5 minutes the first time, needs an iPhone)

1. Export. Install MetricBridge on the iPhone, allow Health read access and tap Export now. It writes .health-cache.json to iCloud Drive (or a folder, or your LAN). The app has a 7-day free trial, then one purchase ($24.99), no subscription. This server is MIT and free.
2. Connect. The one command above (Claude Code), the .mcpb (Claude Desktop), or the block for your client in AGENTS.md.
3. Check it arrived. npx -y health-export-mcp --doctor prints the folder it chose and why, each file's age, and freshness. iCloud can take a few minutes to bring a new export to the Mac.

<p align="center"> <img src="assets/architecture.svg" alt="Apple Health exports to iCloud, a folder, or your LAN; health-export-mcp reads it and serves 18 tools to your AI agent" width="100%" /> </p>

---

What is health-export-mcp?

It's an MCP server that turns your Apple Health export into tools your AI agent can query in natural language: HRV, sleep, resting heart rate, steps, workouts, VO₂ max and 180+ more.

• Who it's for: anyone who wants their AI to reason over their real health data instead of a stale CSV.
• What it isn't: a cloud service. There's no developer server in the path, your data goes only where you point it.
• Setup: point the server at your exported data and add it to your AI client.
• Where the data comes from: the MetricBridge iOS app (formerly Health Export AI), available on the App Store, writes the export this server reads. The server still reports itself as health-export-ai in serverInfo, and the npm package and repository names are unchanged.

Just exported and the Mac has not seen it yet? iCloud can take a few minutes to sync the file across, so a check 60 seconds after tapping Run in the app can still show the old timestamp. get_mcp_status reports lastDataDate and the intraday lastWrite, which is the quickest way to tell "still syncing" from "never arrived".

Try it with no iPhone needed: npx -y health-export-mcp --demo (or node server.mjs --demo in a clone) serves a deterministic synthetic dataset (400 days, workouts, events, sleep sessions) with every answer watermarked as synthetic. Or run npm test to write a sample cache and exercise every tool.

---

Connect Apple Health to your AI agent: quickstart

1. Get your Apple Health data flowing

The companion iOS app MetricBridge exports your Apple Health data, read-only, automatic, private. For this MCP server, export to a destination it can read:

<p align="center"><a href="https://apps.apple.com/app/apple-store/id6784185201?pt=129083290&ct=githubreadme&mt=8&ppid=2c28f88a-d94f-48f9-8e6a-74a8d89ce66e"><img alt="Download MetricBridge on the App Store" src="https://img.shields.io/badge/Download_on_the-App_Store-0D96F6?style=for-the-badge&logo=apple&logoColor=white" height="38" /></a></p>

| Destination | Notes | |---|---| | iCloud Drive (default) | Your Mac reads the synced folder automatically | | Local folder | Any folder that syncs to your Mac (Dropbox, Google Drive, OneDrive, …) | | LAN (HTTP / WebSocket) | Direct push to the server, great over Tailscale |

Using a non-MCP tool (ChatGPT, n8n, Home Assistant)? The app can also POST to a webhook those tools read directly, see Works with.

2. Add the server to your agent

Fastest, one command (Claude Code):

claude mcp add health-export -- npx -y health-export-mcp
# Windows, Linux, or an export outside iCloud Drive:
claude mcp add health-export --env "HEALTH_DATA_DIR=/path/to/folder" -- npx -y health-export-mcp

Everything before -- is an option for claude mcp add, everything after it is the command that starts the server. On a Mac the server reads the app's iCloud Drive folder when HEALTH_DATA_DIR is unset (1.7.3+); if you set it to that folder by hand, double-quote it (the folder name contains a space) and use $HOME, because a quoted ~ is not expanded by the shell. Add --scope user to make the server available in every project (the default scope is the current project only). Check it with claude mcp list.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json), and any client that takes an mcpServers block:

{
  "mcpServers": {
    "health-export": {
      "command": "npx",
      "args": ["-y", "health-export-mcp"]
    }
  }
}

Off a Mac, or for another folder, add "env": { "HEALTH_DATA_DIR": "/path/to/folder" } to the entry (a leading ~ is expanded by the server). npx -y fetches the published package at run time without an install prompt (npm verifies package integrity), so it runs anywhere with no clone or absolute path. The server expands a leading ~ in HEALTH_DATA_DIR itself, so the JSON form can keep it. Prefer to pin a vetted local checkout instead? Use "command": "node", "args": ["REPLACE_WITH_ABSOLUTE_PATH/server.mjs"], get the path with node -e "console.log(process.cwd()+'/server.mjs')" inside the repo. Or skip JSON entirely, drag health-export.mcpb into Claude Desktop → Settings → Extensions.

Auto-configure from a clone:

git clone https://github.com/PhilipAD/health-export-mcp.git
cd health-export-mcp
node apply-mcp-config.mjs     # detects installed clients and writes the config for you

Cursor / VS Code: node gen-deeplinks.mjs prints one-click install links. opencode / OpenClaw / Hermes: see AGENTS.md for the exact block, same shape, one per client.

3. Ask your agent

Restart the client and try:

"Use health-export: what's my average HRV this week vs last week?"

---

Works with Claude, Cursor, ChatGPT, OpenClaw, Hermes

| Client / Agent | Integration | How | |---|---|---| | Claude Code | Native MCP | claude mcp add ... -- npx -y health-export-mcp | | Claude Desktop | Native MCP | .mcpb bundle, or mcpServers block | | Cursor | Native MCP | One-click deeplink, or ~/.cursor/mcp.json | | opencode | Native MCP | opencode.json mcp block | | OpenClaw | Native MCP | Add the server block to your MCP config | | Hermes | Native MCP | Add the server block to your agent's MCP config | | VS Code (Copilot / Continue) | Native MCP | One-click deeplink | | ChatGPT · Gemini · Grok | Webhook* | Consume the app's webhook export | | n8n · Home Assistant | Webhook* | Trigger automations on the exported JSON |

_{*MCP clients query this server directly over stdio. ChatGPT / Gemini / Grok / n8n / Home Assistant don't speak MCP, they consume the same Apple Health data via the iOS app's token-authenticated webhook export.}

---

The 18 MCP tools

Full reference with request/response examples: healthexport.dev/mcp.

| Tool | What it does | |---|---| | get_mcp_status | Health check: source, metric/workout counts, which context files exist, latest data date, and a freshness summary. Call first. | | get_freshness | How current the export is: stale judged on the core files (daily cache, sleep sessions) against a stated threshold (26 h by default, HEALTH_STALE_AFTER_HOURS, or maxAgeHours), age_hours, as_of, last_data_date, per-file write times. state: "stale_copy" (with a stale_copy list) when the phone's .health-manifest.json or iCloud says this Mac holds an older copy of a core file than the phone wrote. Same rule as the status --max-age cron gate. | | list_metrics | Every available metric with unit, day count, and date range. | | get_health_metrics | Daily values for a metric (or all) over a date range + an aggregate (avg/sum/min/max/latest). Supports filterDays (restrict to days covered by logged events, with negate). Blood pressure at day granularity also lists the individual readings (health-readings.json). | | get_trends | Recent N-day window vs the prior N days: change, % change, direction. Supports excludeTravelDays. | | compare_periods | A metric across two arbitrary date periods (A vs B), or around a logged event via anchor: {eventId, days} (the event day excluded from both sides). | | get_structured_export | Clean JSON for chosen metrics/range, paginated with a cursor. | | get_intraday | The hour-by-hour window from the app's hourly automations (health-intraday.json, app 1.4+): yesterday and today, replaced each ru