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

**Category:** 📊 Monitoring  
**Repository:** https://github.com/PhilipAD/health-export-mcp  
**GitHub Stars:** 11  
**npm Downloads (last month):** 3233  
**Views:** 13  
**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 does

Apple Health data becomes queryable JSON for MCP-compatible agents. The server reads an export directory rather than connecting directly to an Apple account or HealthKit, and supports 190 health metrics along with workouts and optional context files.

The companion MetricBridge iOS app exports the source data to a destination the server can read. Supported destinations include iCloud Drive, a local folder, and LAN delivery over HTTP or WebSocket. The server is read-only and local-first: an agent queries the files available at the configured location, while the data remains under the operator's control.

## How it works

The server runs over MCP, with stdio configuration examples for Claude Code and Claude Desktop. An MCP client invokes tools that read the current export. Start with `get_mcp_status` to confirm the bridge, inspect available files, and check the latest data date. `list_metrics` then shows metric names, units, coverage, and date ranges before a query is made.

Daily metric queries include coverage information so an agent can distinguish a genuinely long history from a short file. Trend and period-comparison tools return changes and percentage changes. Correlation results describe alignment rather than causation and withhold the coefficient when fewer than 10 aligned pairs are available.

A demo mode supplies deterministic synthetic data without an iPhone or export. It includes 400 days of sample data, workouts, events, and sleep sessions, with results marked as synthetic.

## Setup and configuration

Install Node.js 18 or newer, make Apple Health data available through MetricBridge, and set `HEALTH_DATA_DIR` to the exported folder. For a typical iCloud setup, the server can be added to Claude Code with `npx -y health-export-mcp` and the directory passed through that environment variable. The path should be quoted when it contains spaces.

Claude Desktop accepts the same command and environment in an `mcpServers` configuration block. Cursor and VS Code installation links can be generated with `node gen-deeplinks.mjs`. A cloned repository can also run `node apply-mcp-config.mjs` to detect clients and write configuration. The package has no runtime dependencies; a local checkout can be started with Node directly.

Use `npx -y health-export-mcp --demo` to test the server with synthetic data. After an iOS export, iCloud synchronization may take several minutes; the status response exposes the latest data date, while intraday data includes its latest write time.

## Tools and capabilities

- Inspect bridge health, data freshness, available metrics, units, coverage, and date ranges.
- Retrieve one or all metrics over a date range with average, sum, minimum, maximum, or latest aggregation.
- Compare recent and prior windows, arbitrary periods, or periods anchored around a logged event.
- Export selected metrics as paginated structured JSON.
- Read the current hourly intraday window from the iOS app's hourly automation output.
- Query workouts with activity, date, and pagination filters, including optional heart-rate, power, interval, route, and running-dynamics fields when exported.
- Read sleep sessions, logged events, opted-in profile fields, and cycle context derived from logged period starts.
- Calculate Pearson correlation between daily metrics with optional lags from zero through three days.

## Limitations and notes

Intraday data is replaced on each hourly automation run, so it represents the current within-day window rather than historical hourly data. Use daily metric queries for day-level history. Sleep sessions are attributed to the waking day, and split nights are returned as separate sessions when the export contains them.

Cycle context uses logged period starts and provides a coarse observed phase; it is not predictive and does not estimate ovulation. Missing context fields indicate that the user withheld them or did not enable them. An absent events file means no event export is available, not that no events occurred.

For long exports, request specific metrics and dates. Structured results are paginated, and the cursor must be supplied to retrieve later pages. Metric aggregates cover the full requested range even when returned points are rolled up. Correlation describes association in the exported data, not a causal relationship.

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