MetricBridge Apple Health

health-export-mcp

Query your own Apple Health data from any MCP client.

health-export-mcp is an open-source, zero-dependency Model Context Protocol (MCP) server. It reads the Apple Health / HealthKit export on your own machine and answers your agent's questions from it: 190 metrics, 16 tools and 22 prompts, as clean JSON. Read-only, local-first, no account, and no developer server in the path.

One command (Claude Code):

claude mcp add --transport stdio health-export \
  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
  -- npx -y health-export-mcp

Keep the double quotes: the iCloud folder name contains a space. No export yet? Try it on synthetic data first:

claude mcp add --transport stdio health-export-demo -- npx -y health-export-mcp --demo

Then ask: "Use health-export: compare my HRV this week vs last week." Using Claude Desktop, Cursor, VS Code, opencode, OpenClaw or Hermes? See the Quickstart.

Ask your agent: "Compare my HRV this week vs last week and tell me if I'm recovering.", it calls the tools and answers from your actual numbers.

What is health-export-mcp?

It's an MCP server that turns your Apple Health export into a tool 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:

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 --transport stdio health-export \
  --env "HEALTH_DATA_DIR=$HOME/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" \
  -- npx -y health-export-mcp

Everything before -- is an option for claude mcp add, everything after it is the command that starts the server. The path is double-quoted because the iCloud folder name contains a space, and $HOME is used because a quoted ~ is not expanded by the shell. Exporting somewhere else? Replace the path with your own folder. 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"],
      "env": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
    }
  }
}

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

*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 16 MCP tools

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

Coverage: 190 Apple Health metrics across activity, heart, HRV, mobility, respiratory, body, sleep, hearing, and nutrition, plus workouts. Data answers carry honest coverage blocks, and single-metric answers list logged events inside the window as segmentBoundaries so an average across a medication start or life change cannot masquerade as one regime.

Data files

The daily cache (.health-cache.json) and workouts cache are joined by optional context files, all read-only and all optional: health-events.json (the logging surface), health-profile.json (opt-in context), health-sessions.json (sleep sessions), health-cycles.json (observed cycle starts), health-days.json (timezone change log). An absent file is reported as available:false with a note, never as "no data". Formats: docs/SCHEMA-CONTRACTS.md.

Two patterns worth knowing: query a parent's Apple Health from your own AI (consent-first, the parent's phone is the authority) and logging data into Apple Health via Shortcuts (the server and app stay strictly read-only).

MCP prompts

The server ships 22 prompts over prompts/list / prompts/get: daily brief, weekly review, doctor visit prep, what changed since my last visit, sleep quality and regularity, HRV trend, training and race week reviews, zone minutes, n-of-1 experiment, medication before/after, GLP-1 dose-step compare, sobriety milestone, shift block compare, travel-honest monthly review, cycle-aware trend read, caregiver check-in, glucose day summary, long-term activity narrative, data coverage audit, and a profile-aware context bootstrap. Every prompt leads with coverage honesty and never turns data into diagnosis.

Demo mode

node server.mjs --demo (or HEALTH_DEMO=1) serves a deterministic synthetic dataset: ~15 metrics over 400 days, 30 workouts with intervals, 8 events, a profile, 60 sleep sessions, cycle starts and a timezone change, anchored to a fixed date with a seeded PRNG. Every answer carries demo: true and a [SYNTHETIC DEMO DATA] text prefix, so demo output can never pass for a real export.

CLI

node server.mjs --doctor            # diagnostics: files, sizes, schema, freshness, pairing
node server.mjs status --max-age 24 # exit 0 if data is fresh, 1 if stale (cron gate)
node server.mjs receive             # standalone LAN receiver (binds 127.0.0.1 by default)
node server.mjs --help

Example AI queries

"What has my resting heart rate done over the last 30 days?"
"Compare my deep sleep this week vs last week."
"Is my VO₂ max trending up or down this quarter?"
"Give me a clean JSON export of HRV, RHR and sleep for the last 14 days."
"Correlate my step count with my sleep duration this month."

Use cases

• AI health coach, let an agent reason over your real HRV, resting heart rate, and sleep to suggest when to push and when to recover, grounded in your actual numbers instead of generic advice.
• Training-load analysis, pull workouts, VO₂ max, and heart-rate trends so your agent can flag overreaching, plot fitness progression, and pace a training block.
• Sleep correlations, have your agent correlate deep-sleep duration against steps, caffeine, late workouts, or screen time to find what actually moves your sleep quality.
• Quantified-self dashboards, feed clean JSON for any metric set and date range straight into a notebook, spreadsheet, or LLM-built dashboard for your own self-tracking.
• Personal research & experiments, run n-of-1 experiments (supplement, routine, or protocol changes) and let an agent compare before/after periods across 190 metrics to see what changed.

Building a wellness or coaching product?

This server reads a file the MetricBridge iOS app writes on the user's own device, with no central health-data processor in the path. The same app can POST signed JSON (Standard Webhooks v1, published JSON Schemas) straight to your endpoint, so your users bring their own Apple Health to your product without an SDK in your app and without any vendor server holding the data. The offer, flat pricing and boundaries: healthexport.dev/platforms. The integration guide and the zero-dependency conformance kit: healthexport.dev/docs/platforms. Wellness-scoped and end-user-directed; no clinical or HIPAA work.

The app that feeds it

Privacy & security

The one non-health thing the server reads from the export is _meta.license, a marker the app writes with exactly two shapes: {"state": "trial", "daysRemaining": N} or {"state": "unlocked"}. A fresh export from a trial adds one sentence to get_freshness naming when the trial ends; an unlocked export adds nothing. No network call is involved and nothing is sent anywhere.

• Read-only. The server only reads your exported data, it never touches HealthKit and never writes back.
• Local-first. It runs on your machine over stdio. There is no developer server in the path.
• Optional pairing. Set PAIRING_SECRET to the code the iOS app shows (Settings → Agent pairing) to gate access.
• Encrypted exports (optional). If you switch on Export encryption in the iOS app, set HEALTH_EXPORT_PASSPHRASE (or HEALTH_EXPORT_PASSPHRASE_FILE) to the same passphrase and the server decrypts on your machine. See Encrypted exports.
• No telemetry. The server makes no network requests. get_mcp_status always includes one static link to the companion app's website (and its App Store page), so the bridge is attributable back to install. Both links carry fixed campaign labels (utm_source=mcp, utm_medium=agent-tool, utm_campaign=mcp-unlock; ct=mcpserver, ppid=…) that are identical for every user and contain nothing about you or your data; they only count if you choose to open one.
• Auditable. Zero dependencies and a few hundred lines of readable JavaScript, read every line.
• Signed releases. Hosted artifacts are minisign-signed and checksummed, see Verifying releases.

Encrypted exports

The iOS app can encrypt what it exports with a passphrase you choose (Settings > Export encryption, switched on per destination: iCloud Drive, a folder, your server, the local network). Give the server the same passphrase and every file is decrypted transparently, in memory, on this machine:

HEALTH_EXPORT_PASSPHRASE='your passphrase' HEALTH_DATA_DIR=... node server.mjs
# or keep it out of your shell history and process list:
HEALTH_EXPORT_PASSPHRASE_FILE=~/.config/metricbridge/passphrase HEALTH_DATA_DIR=... node server.mjs

If both are set, HEALTH_EXPORT_PASSPHRASE wins; one trailing newline in the file is ignored and an empty value counts as unset. The .mcpb bundle has an optional Export passphrase field. Plaintext exports keep working either way. A missing or wrong passphrase, or a file that fails its integrity check, is reported as such (get_mcp_status says encrypted: true plus the reason, --doctor prints an encryption: line), never as "no data". The passphrase is never logged or echoed.

The LAN receiver (HEALTH_LISTEN=1) decrypts encrypted pushes with the same variable and answers 422 with a machine reason (passphrase_missing, passphrase_mismatch, tampered, malformed, unsupported_version, passphrase_file_unreadable, encryption_required). The pairing token rides in a plain http header on that leg, so set HEALTH_REQUIRE_ENCRYPTED=1 to refuse plaintext pushes once the app encrypts that leg. To decrypt one body yourself (a webhook you run, a script):

HEALTH_EXPORT_PASSPHRASE='...' node envelope.mjs open body.json     # prints the decrypted JSON

Format (metricbridge.enc v1, envelope.mjs, node:crypto only): a JSON object {format, v, alg: "A256GCM", kdf: "PBKDF2-HMAC-SHA256", iter, salt, kcv, nonce, ct}. master = PBKDF2-HMAC-SHA256(NFC(passphrase), salt[16], iter) (600,000 iterations, the OWASP figure); an AES-256-GCM key and an 8-byte key-check value come off it with HKDF-SHA256; each message gets a random 12-byte nonce; every header field is bound in as AAD as the string metricbridge.enc|v=1|alg=A256GCM|kdf=PBKDF2-HMAC-SHA256|iter=<n>|salt=<b64>|kcv=<b64>|nonce=<b64>. Base64 is canonical with padding. test/fixtures/ holds envelopes made by the iOS app's Swift encoder and by this module; envelope.test.mjs proves both open and regenerate byte for byte.

What it protects: the export at rest in the destination (iCloud Drive, a synced folder, a webhook host's storage) and the LAN push on the wire, plus integrity of every sealed file. What it does not: an unlocked phone, this computer (it holds the passphrase), metadata (sizes, timing), rollback or replay of a whole sealed file, files you share by hand from the app, or a weak passphrase (anyone with the files can guess offline; the app requires at least 8 characters).

Verifying releases

The server artifacts hosted at healthexport.dev/mcp/ (used by the setup skill) are minisign-signed, and every download is SHA-256 checksummed. The signing public key is published in this repo (minisign.pub) and in SKILL.md, pin it from here, not only from the website, so a compromise of the website alone cannot swap both an artifact and its key.

PUBKEY='RWS6TxVWSKUblYkx7Db6ZpmvHALwHpznZpjaED/FlZj+PpxSlel0MxHZ'   # = minisign.pub in this repo
curl -fsSL https://healthexport.dev/mcp/SHA256SUMS         -o SHA256SUMS
curl -fsSL https://healthexport.dev/mcp/SHA256SUMS.minisig -o SHA256SUMS.minisig
minisign -Vm SHA256SUMS -P "$PUBKEY" || { echo "signature INVALID, do not run"; exit 1; }   # fail closed
curl -fsSL https://healthexport.dev/mcp/server.mjs -o server.mjs
shasum -a 256 --ignore-missing -c SHA256SUMS || { echo "checksum mismatch, do not run"; exit 1; }

The pinned, checksum-verified download above is the locked-down path. npx -y health-export-mcp instead resolves the latest version published to npm at run time (npm provides its own package integrity). Each GitHub release also carries a SHA256SUMS file and its SHA256SUMS.minisig signature made with the same key. Full policy, including npm provenance and how to report a vulnerability privately: SECURITY.md. Security overview: https://healthexport.dev/security.

Requirements

• Node.js ≥ 18 (node -v).
• A folder containing a .health-cache.json exported by MetricBridge, or run npm test to generate a sample one.
• An MCP-compatible client (Claude Desktop, Cursor, opencode, OpenClaw, Hermes, VS Code), or any tool that can read the webhook export.

FAQ

How do I get my Apple Health data into Claude / ChatGPT / my AI agent? Install health-export-mcp, export your Apple Health data with the MetricBridge iOS app (to iCloud, a folder, or your LAN), then add the MCP server to your AI client. Your agent can then query your Apple Health metrics in natural language. (Non-MCP tools like ChatGPT read the app's webhook export instead.)

Is my health data sent to a server? Not to us. The MCP server runs locally and reads only the export files or endpoints you configure, there's no developer server in the path. Where your iOS export is delivered (iCloud, your LAN, a webhook) is entirely your choice.

Which agents are supported? Any MCP client, Claude Desktop, Cursor, opencode, OpenClaw, Hermes, VS Code, natively. ChatGPT, Gemini, Grok, n8n, and Home Assistant consume the same data via webhook.

Do I need the iOS app? The app is the easiest way to get Apple Health data off your iPhone in the format this server reads. You can also point HEALTH_DATA_DIR at any folder containing a compatible .health-cache.json.

Troubleshooting

• "No metrics found", confirm HEALTH_DATA_DIR points at the folder containing .health-cache.json, and that the app has exported at least once. Run get_mcp_status to see the resolved source and latest date.
• Server not visible in the client, use an absolute path to server.mjs, ensure Node ≥18, and fully restart the client.
• Locked data error, the export file is protected until first unlock after reboot; unlock your device once.

Run it locally

# Node ≥18, no install needed
HEALTH_DATA_DIR=~/Library/Mobile\ Documents/iCloud~ai~healthexport~app/Documents node server.mjs

# integration test, writes a 14-day sample cache and exercises every tool
npm test

stdio transport (newline-delimited JSON-RPC 2.0), the universal MCP transport. Optionally set HEALTH_LISTEN=1 to also accept LAN pushes from the iOS app in the same process (see receiver.mjs).

How it works

The iOS app reads Apple Health (read-only) and writes a compact .health-cache.json (plus optional context files) to the destination you choose. This server reads those files and exposes the 16 tools above over MCP. No bridge, no Docker, no database: just files and stdio.

Apple Health → MetricBridge (iOS) → .health-cache.json → health-export-mcp → MCP client → you

Related projects

Other Apple Health MCP servers in the ecosystem, worth a look depending on your setup:

• neiltron/apple-health-mcp, an MCP server that runs SQL-style queries over an Apple Health export.
• the-momentum/apple-health-mcp-server, an MCP server for analyzing Apple Health data exported from the Health app.
• HealthyApps/health-auto-export-mcp-server, an MCP server for the Health Auto Export app's data.

How health-export-mcp differs: zero dependencies, clean structured JSON, 190 Apple Health metrics, and the widest agent support (Claude, Cursor, opencode, OpenClaw, Hermes, VS Code natively, plus ChatGPT/Gemini/Grok/n8n/Home Assistant via webhook).

Related

• Companion iOS app: MetricBridge, exports 190 Apple Health metrics to your agent, automatically.
• Model Context Protocol: modelcontextprotocol.io
• Per-agent setup: AGENTS.md

If this helps your setup, a ⭐ makes it easier for others to find.

License

MIT, see LICENSE. Contributions welcome.

Apple Health MCP server · export Apple Health to AI · HealthKit MCP server · query Apple Health with Claude / ChatGPT / Cursor · Model Context Protocol health server · Apple Health to LLM · HRV, sleep & heart rate for AI agents.