# io.github.PhilipAD/health-export-mcp [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/PhilipAD/health-export-mcp  
**GitHub Stars:** 4  
**npm Downloads (last month):** 273  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/io-github-philipad-health-export-mcp

## Description
Query 190 Apple Health metrics from any MCP agent — zero-dependency, read-only, local-first.

## Tools
Capabilities this server exposes over MCP:

- **get_mcp_status** — Health check: data source, how many metrics/workouts are available, which optional context files exist, and the most recent data date. Call this first to confirm the bridge is connected.
- **list_metrics** — List every available Apple Health metric with its unit, day count, and date range. Use this to discover metric names before querying.
- **get_health_metrics** — Get values for a metric (or all metrics) over an optional date range, with an aggregate (avg/sum/min/max/latest). The core data-retrieval tool. Every result carries a `coverage` block giving the metric's real firstDate/lastDate/days: check it before trusting a long window, and note that `aggregate` is always computed over the full range even when `points` are rolled up. Single-metric answers also list any logged point events inside the window as segmentBoundaries.
- **get_trends** — Compare the most recent N-day window against the prior N days for a metric: change, percent change and direction (up/down/flat). Also returns `daysAvailable` and `windowSatisfied`: if windowSatisfied is false the file does not hold enough history for the window you asked for, and the comparison is over less data than requested. Logged point events inside the compared span are listed as segmentBoundaries.
- **compare_periods** — Compare a metric between two arbitrary date periods (A vs B): each aggregate plus the change and percent change. Pass periodA/periodB explicitly, or pass anchor {eventId, days} to build both periods around a logged event (the before/after question, with the event day excluded from both sides).
- **get_structured_export** — Return clean structured JSON for the chosen metrics/date range. Paginated: the result carries `nextCursor` when more metrics remain; pass it back as `cursor` for the next page. Prefer naming the metrics you need and a date range; calling it bare over a full history is a lot of data.
- **get_intraday** — The current hour-by-hour window from the iOS app's HOURLY automations (health-intraday.json, app 1.4+): each metric's hourly points plus its latest value. The file is REPLACED on every hourly run, so this is a live within-day view, not history; use get_health_metrics for day-level questions. Returns available:false with setup guidance when no hourly automation has delivered yet.
- **query_health_data** — Natural-language convenience: pass a question and get routed structured results. Prefer the specific tools above when you can, and call list_metrics first to see how much history exists, since this tool answers over whatever the file holds.
- **list_events** — Logged context events from health-events.json: medication starts, habit changes, doctor visits, life events, shift blocks, episodes, travel, and any type a newer app adds. Optional {type, tag, start, end} filters; a range event matches a window it overlaps. Sorted ascending by date. Returns available:false when the file was never exported; absence means nothing was exported, not that nothing happened.
- **get_profile** — The context fields the user explicitly opted in to sharing (health-profile.json): conditions, medications, goals, allergies, notes. Returns the fields plus a presentFields list. An absent field was withheld by the user or never enabled; absence must never be read as "none".
- **get_workouts** — Query the workouts cache with {activityType (a name like Running, or a raw HealthKit id like 37), start, end} filters and pagination ({limit} default 50 max 200, {cursor} from a previous nextCursor). Records are returned exactly as stored, including the newer optional keys (avgHeartRate, maxHeartRate, running dynamics, cycling power, intervals, hasRoute) when the app exported them; older caches simply lack those keys and nothing is fabricated. Also returns summary {count, byActivityType} over everything that matched.
- **get_sleep_sessions** — Clustered sleep sessions from health-sessions.json with {start, end, day} filters. Sessions are attributed to the WAKING day, matching the daily cache's sleep_analysis, so the two surfaces never disagree; a split night appears as multiple sessions with the same day, returned as-is. Timestamps carry the local UTC offset at the time of the sample.
- **get_cycle_context** — Cycle context derived from user-logged period starts (health-cycles.json): day-in-cycle and a coarse phase label (follicular from day 1 to the observed midpoint of that cycle, luteal for the remainder). Derived from logged periods only, never predictive, and no ovulation estimate is made. Optional {date} for a single day; default returns per-day context for the last cycle.
- **correlate_metrics** — Pearson correlation between two metrics' daily values: {metricA, metricB, lag (0 to 3, default 0), start, end}. lag pairs metricA on day d with metricB on day d+lag, so lag 1 compares against the FOLLOWING day. Returns alignedPairs, r (withheld below 10 aligned pairs), and both means. The answer always carries the association-not-causation caveat; treat every r as alignment in this file, not mechanism.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `HEALTH_DATA_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What io.github.PhilipAD/health-export-mcp MCP server does

io.github.PhilipAD/health-export-mcp MCP server gives an MCP client structured, read-only access to Apple Health data exported by the MetricBridge iOS app. It covers 190 metrics across areas such as activity, heart, HRV, mobility, respiratory measurements, body data, sleep, hearing, and nutrition. Workouts are exposed separately, with exported fields preserved when available.

The server also reads optional context files. These can contain logged events, user-approved profile fields, clustered sleep sessions, observed cycle starts, hourly data, and timezone changes. Missing optional files are reported as unavailable or absent; they should not be interpreted as proof that no event or profile item exists.

## How it works

The MCP process reads files from a directory selected through configuration and responds over stdio to the connected client. The usual data flow is an Apple Health export from MetricBridge to iCloud Drive, another folder synchronized to the computer, or a LAN destination that the server can read. No account or developer-hosted server is required for the MCP connection, and the server does not mutate the health data.

Call `get_mcp_status` first to verify the source, available metric and workout counts, optional context files, and latest data date. `list_metrics` then reveals metric names, units, date coverage, and available day counts. Query results include coverage details, which helps identify whether a requested date range is fully represented. Aggregates apply to the complete requested range even if returned points are rolled up.

The tool set supports daily metric queries, recent-versus-prior trend comparisons, arbitrary period comparisons, event-anchored before-and-after comparisons, paginated structured exports, and a natural-language routing tool. Additional tools cover intraday hourly data, events, opted-in profile fields, workouts, sleep sessions, cycle context, and Pearson correlations with optional lags. Correlations describe alignment in the available data and do not establish causation.

## Setup and configuration

Install or run the published package with Node.js 18 or newer. A Claude Desktop configuration can start it with `npx -y health-export-mcp` and set `HEALTH_DATA_DIR` to the exported-data directory. The repository also includes an automatic configuration script that detects supported clients, while Claude Desktop can use the provided MCP bundle. Cursor and VS Code installation links can be generated from the repository; other documented clients use the same MCP server configuration shape.

MetricBridge is the documented source for Apple Health exports. Its destinations include iCloud Drive, a local folder synchronized by another service, and LAN delivery. Synchronization may delay the newest file, so `get_mcp_status` can be used to distinguish an old synced timestamp from a source that has never delivered data.

For testing, the repository documents `node server.mjs --demo`, which serves a deterministic synthetic dataset containing health history and related records. Synthetic responses are marked as such. The repository also documents `npm test` for writing a sample cache and exercising the tools.

## Limitations and notes

The server is read-only and answers only from the files available to it. A long requested window may contain less history than expected; inspect `coverage`, `daysAvailable`, and `windowSatisfied` before relying on comparisons. Intraday data is replaced on each hourly automation run, so it represents a current within-day view rather than historical hourly storage.

Cycle context is derived from logged period starts and supplies a coarse observed phase; it is not predictive and does not estimate ovulation. Sleep sessions are assigned to the waking day, and split nights remain separate records. Workout fields such as heart rate, power, running dynamics, intervals, or route availability appear only when the export contains them. Profile data reflects only fields the user opted to share. The io.github.PhilipAD/health-export-mcp MCP server is therefore best suited to analysis of an available local export, not to filling gaps or inferring unrecorded health information.

_Full upstream README: https://allmcps.com/mcp/io-github-philipad-health-export-mcp/readme_