Ask your agent about your real Apple Health data

Paste one command. Claude Code, Claude Desktop, Cursor, VS Code, opencode, OpenClaw or Hermes then reads your Apple Health export through 18 tools over 194 metrics, on your own machine. Nothing to host, no account, no cloud AI in the path.

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

Last updated 28 October 2026 · health-export-mcp 1.8.0 · source on GitHub · npm: health-export-mcp

What a real answer looks like

You ask in plain language; the agent picks a tool; the tool answers with numbers that carry their own provenance: the unit, the exact date ranges, whether each window was complete, and how much history the export holds. This is the real output of get_trends on health-export-mcp 1.7.3, captured on 27 October 2026 from the built-in --demo dataset (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}}

Every data tool answers this way. get_mcp_status names the file it read and the latest data date; compare_periods reports pointsInRange for each period and comparable: false when one side is too thin; correlate_metrics refuses below ten aligned days and says "association, not causation" in the payload. A number without its working does not come out of this server.

What your agent can answer: the 18 tools

All sixteen are read-only and none makes a network request. Your agent picks the tool from your question; you never name one. The left column is the question, the right is what answers it.

The server also ships 22 MCP prompts (daily brief, weekly review, doctor visit prep, an n-of-1 experiment protocol, medication before/after, shift block comparisons and more), a --doctor diagnostics command, and status --max-age <hours> as a freshness gate for cron jobs. Prompt and tool reference with every parameter: the README.

get_mcp_status

Reports the data source, how many metrics and workouts are available, the most recent data date and a freshness summary. Since 1.7.3 the source line also says why that folder was chosen (HEALTH_DATA_DIR, the iCloud default on a Mac, or the current directory).

{ "ok": true, "source": "file /Users/you/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents/.health-cache.json (default: the MetricBridge iCloud Drive folder)",
  "metricCount": 34, "workoutCount": 12, "lastDataDate": "2026-10-26",
  "freshness": { "state": "fresh", "stale": false, "age_hours": 3.2, "stale_after_hours": 26 } }

get_health_metrics

get_trends

get_intraday

The current hour-by-hour window written by the iOS app's hourly automations (app 1.4 or later) to health-intraday.json, beside the daily cache. The file is replaced on every hourly run (a live within-day view, not an accumulating history), so day-level questions still belong to get_health_metrics. Optional metric filters to one metric; when no hourly automation has delivered yet it answers available: false with setup guidance instead of an error.

{ "available": true, "file": "health-intraday.json", "replacedEachRun": true,
  "metrics": [ { "name": "heart_rate", "unit": "count/min",
                 "points": [ { "t": "2026-08-17 09:00:00 +0100", "v": 71 } ],
                 "latest": { "t": "2026-08-17 09:00:00 +0100", "v": 71 } } ] }

resolve_metric

Full setup, the first time

Under two minutes if the app is already exporting to iCloud Drive on a Mac: paste the command, restart the client, ask. The first time, add the app install and a few minutes for iCloud to bring the file to your Mac.

1. Install the MetricBridge iOS app. Install the MetricBridge iOS app on your iPhone and allow read access to the Apple Health types you want to share. It has a 7-day free trial, then costs $24.99 once. Download on the App Store.
2. Choose an export destination. In the app, choose where the export goes: iCloud Drive, a local folder, or your LAN. The app writes .health-cache.json there. On a Mac, iCloud Drive needs no further setup.
3. Add the server to your MCP client. In Claude Code run: claude mcp add health-export -- npx -y health-export-mcp. On a Mac the server finds the app's iCloud Drive folder by itself (since 1.7.3); on Windows or Linux, or for another folder, add -e HEALTH_DATA_DIR="/path/to/your/export/folder". Claude Desktop: open health-export.mcpb instead.
4. Check the connection. Ask your agent to call get_mcp_status. It reports the data source, the metric count and the most recent data date.

Client configuration

Every client runs the same command, npx -y health-export-mcp, over stdio. On a Mac no environment variable is needed; elsewhere set HEALTH_DATA_DIR. Prefer a pinned, checksum-verified copy instead of npm? Download the files under verify the download and replace npx -y health-export-mcp with node /path/to/server.mjs in any block below, keeping the nine .mjs files together in one folder.

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 -e HEALTH_DATA_DIR="/path/to/your/export/folder" -- npx -y health-export-mcp

Everything after -- is the command Claude Code runs. Add --scope user before the -- to make the server available in every project; the default is the current project. Check with claude mcp list. Claude Code also reads a project-scoped .mcp.json using the same mcpServers shape as Claude Desktop. If pairing is on, do not pass PAIRING_SECRET on the command line: it would land in your shell history and in ps output. Put it in the config file instead.

Claude Desktop

Easiest: open health-export.mcpb, click Install, and it asks for the export folder (and the pairing code, if you use one) itself. Desktop runs it with its own Node, so nothing goes on your PATH. Or edit claude_desktop_config.json, merge into mcpServers, then quit and reopen Claude Desktop:

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

Drop the env line on a Mac using iCloud Drive. If Desktop logs spawn npx ENOENT, its PATH cannot see Node (common with nvm or Homebrew): set "command" to the full path from which npx, or use the bundle.

Cursor

Cursor reads ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project), using the same mcpServers block as Claude Desktop.

VS Code

VS Code reads .vscode/mcp.json in the workspace. The top key is servers, and a secret can be prompted for rather than stored:

{
  "servers": {
    "health-export": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "health-export-mcp"],
      "env": { "HEALTH_DATA_DIR": "/path/to/your/export/folder" }
    }
  }
}

opencode

Add the server to opencode.json (project) or ~/.config/opencode/opencode.json. The top key is mcp, command is an array and the env key is environment:

{
  "mcp": {
    "health-export": {
      "type": "local",
      "command": ["npx", "-y", "health-export-mcp"],
      "enabled": true,
      "environment": { "HEALTH_DATA_DIR": "/path/to/your/export/folder" }
    }
  }
}

OpenClaw, Hermes and any other MCP client

The server speaks standard MCP over stdio, so any compliant client works. Add a health-export entry with command npx, args ["-y", "health-export-mcp"] and, outside a Mac with iCloud Drive, HEALTH_DATA_DIR in its environment, in whatever shape that client's MCP config uses. Per-client blocks are kept current in AGENTS.md. Agents can also set this up for you from the setup skill.

ChatGPT, Gemini, Grok, n8n and Home Assistant do not run local MCP servers. They read the same data through the app's webhook export to an endpoint you run.

Environment variables

From health-export-mcp --help at 1.8.0. None is required on a Mac that exports to iCloud Drive.

Transports (stdio only)

stdio is the only MCP transport. Every client config above uses it, and there is no hosted endpoint. The server only ever runs on your machine, reading a local file.

Verifying the download

The copy hosted here is minisign-signed and checksummed, so you can confirm you are running exactly what was published before you execute it. The signing key is also published in the GitHub repo (minisign.pub); pin it from there, not only from this site.

• SHA256SUMS: checksums for each file
• SHA256SUMS.minisig: minisign signature
• minisign.pub: the public key

minisign -Vm SHA256SUMS -p minisign.pub
shasum -a 256 -c SHA256SUMS

npx -y health-export-mcp resolves the latest npm release at run time instead; npm verifies package integrity and each release carries npm provenance linking the tarball to its commit. Policy: security.

What agents can see

An agent never talks to your iPhone. It reads the files in the place you chose (iCloud Drive, a folder, or the local-network receiver), through this server on your own computer: the files the MetricBridge app writes, and any events your agent adds there. This is everything those files contain. The same list is in the app under Settings, What agents can see.

Agents can read

• Daily values per metric (.health-cache.json, and the same data as health-export.json, plus yesterday's copy, .health-cache.prev.json, for recovery): only the Apple Health types you allowed, one value per day, across the activity, heart, respiratory, body, mobility, nutrition, vitals and lab, hearing, sleep, mindfulness, symptoms, environment and characteristics families, plus a few types that fit none of these, and the reproductive family only with sensitive categories on.
• Workout summaries (.health-workouts-cache.json): type, time, duration, distance, energy, heart rate, elevation, running and cycling averages, laps, pauses and sub-activities.
• Sleep sessions (health-sessions.json): start, end and stage totals for each night and nap.
• Blood pressure readings (health-readings.json): each reading with its time and source, so several readings in a day stay separate.
• Device sources (health-sources.json): which device or app recorded each value, such as Apple Watch or a ring, with each device's own reading when two recorded the same thing.
• Yesterday and today, hour by hour (health-intraday.json): only from hourly exports, and replaced each time. Each hour has an average and, for vitals such as heart rate and blood oxygen, the lowest and highest reading.
• Events and profile fields you entered (health-events.json, health-profile.json): only what you typed, and only the profile fields you switched on.
• Events your agent logged (health-events-agent.json): added by your agent on your computer with add_event, never by the app. You see them in the app under Events.
• Export check (.health-manifest.json): when the iPhone last wrote each file, so this server can tell an old copy from a current one. It includes when last night's sleep ended, unless exports are encrypted.
• Cycle start dates (health-cycles.json): only with sensitive categories on.
• Time zone changes (health-days.json): so travel days can be flagged.

Reproductive health, sexual activity and alcohol are included only if you switch on sensitive categories in the app. They are off by default.

Never included

• No write access to Apple Health. The app asks for read permission only, and no tool here can write to it. The one file this server writes is health-events-agent.json, for events your agent logs.
• No workout routes or GPS locations. A route leaves the phone only as a GPX file you share yourself from the app. It is never written to a destination, and this server reads no route file.
• No medication records from Apple Health. The app does not read them. A medication reaches an agent only if you type it into an event or your profile, or your agent logs one.
• No individual raw samples, except your blood pressure readings. Agents get daily values, one summary per workout and per sleep session, and hour-by-hour summaries.
• No health data sent to us. There is no MetricBridge account.

This covers the files an agent reads. A webhook, if you set one up, sends to a server you run, and the app lists every destination under Settings, What leaves this phone.

Who can read it: pairing

With pairing on (Settings, Agent pairing), this server serves your data only when PAIRING_SECRET matches the current code; otherwise every data tool answers “Locked”. The app writes only a SHA-256 hash of the code beside your data, never the code itself. Regenerating the code in the app cuts off every agent using the old one as soon as the new pairing file reaches your computer. Pairing covers the iCloud Drive and folder exports; it does not cover a copy saved by the local-network receiver. Pairing protects this server, not the files: anyone who can open the files can read them, unless you turn on export encryption in the app.

Is it private?

The server makes no network requests, has no dependencies, requires no account, and reads a local file you control, so your health data never reaches us or a cloud AI through it. Apple Health access happens only in the iOS app, which requests read-only HealthKit permission and never writes back. The export goes only to the destination you choose; what your agent then does with an answer is governed by that agent, not by this server. Full data-flow table: privacy.

Frequently asked questions

What is an Apple Health MCP server?

An Apple Health MCP server is a Model Context Protocol server that exposes your Apple Health data to AI agents as tools they can call on demand, rather than as a file you paste into a chat.

How do I install health-export-mcp in Claude Code?

Run one command: claude mcp add health-export -- npx -y health-export-mcp. On a Mac it finds the app's iCloud Drive folder by itself; on Windows or Linux add -e HEALTH_DATA_DIR="/path/to/your/export/folder". It requires Node.js 18 or later.

Do I need the iOS app?

For your own data, yes. This server reads a file and does not talk to your iPhone directly. The MetricBridge iOS app writes the JSON export, and without the app there is no export for this server to read. To try the tools first, the --demo mode serves a watermarked synthetic dataset.

How many tools and prompts does the server have?

The server has 18 tools and 22 MCP prompts. 16 only read; add_event and remove_event write one file, health-events-agent.json, beside your export. None of the tools can write to Apple Health, and none of them make network requests.

Is the MCP server free?

The MCP server is free and open source under the MIT license. The MetricBridge iOS app that writes the export is a separate purchase: a 7-day free trial, then a single $24.99 one-time unlock, with no subscription.

Does the server send my health data anywhere?

No. The server makes no network requests, has no dependencies, requires no account, and reads a local file you control. Your health data never reaches us or a cloud AI through this server.

Does it work on Windows or Linux?

Yes, anywhere Node.js 18 runs. Only the iCloud Drive default is Mac-only: on Windows or Linux set HEALTH_DATA_DIR to the folder your export syncs to.

Related

• The setup skill (SKILL.md): lets an agent do this install for you, with your review.
• Webhook contract: the same data POSTed to an endpoint you run, for non-MCP tools.
• MetricBridge for platforms: let your users bring their own Apple Health to your product.
• Ask on the iPhone: the app's own on-device answers, no agent needed.
• All 194 metrics and how the numbers are computed.
• Connect Apple Health to Claude with an MCP server
• Export Apple Health to JSON for AI: the complete guide