MetricBridge (formerly Health Export AI)
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HEALTH_LISTEN | No | Set to '1' to enable LAN push receiver | |
| PAIRING_SECRET | No | Optional pairing code from the iOS app to gate access | |
| HEALTH_DATA_DIR | No | Path to the directory containing .health-cache.json from Health Export AI. Default: ~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents | ~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Apple Health export bridge. Call get_mcp_status (its freshness block says whether the export is stale; get_freshness has the detail), then list_metrics, then the data tools (get_health_metrics, get_trends, compare_periods, get_structured_export, get_workouts, correlate_metrics). The context tools (list_events, get_profile, get_check_ins, get_sleep_sessions, get_strength_log, get_cycle_context, list_tags) read optional files: absence is reported explicitly, never read as "no data". add_event and remove_event are the only tools that write, and only health-events-agent.json: log an event only when the user stated it. prompts/list serves ready-made analysis prompts.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_mcp_statusA | Health check: data source, how many metrics/workouts are available, which optional context files exist, the most recent data date, a compact |
| get_freshnessA | How current the exported files are, so you can decide whether to trust what you read or ask the user to refresh. |
| list_metricsA | List every available Apple Health metric with its unit, day count, and date range. Use this to discover metric names before querying. |
| get_health_metricsA | 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 |
| get_trendsA | 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 |
| compare_periodsA | 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_exportA | Return clean structured JSON for the chosen metrics/date range. Paginated: the result carries |
| get_intradayA | The current hour-by-hour window from the iOS app's HOURLY automations (health-intraday.json, app 1.4+): each metric's hourly points (t, v = the hour's value) plus its latest value. The window covers a 48-hour span, yesterday 00:00 local to now, and the file is REPLACED on every run, so this is a live recent view, not history; use get_health_metrics for day-level questions. Discrete metrics (heart rate, SpO2, respiratory rate, HRV, resting heart rate) carry the hour's Min and Max beside v (the hour's mean) when the app version writes them; older exports cover today only and have no Min/Max. Returns available:false with setup guidance when no hourly automation has delivered yet. |
| query_health_dataA | 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_eventsA | Logged context events: medication starts, habit changes, doctor visits, life events, shift blocks, episodes, travel, and any type a newer app adds. Merges the app's health-events.json with health-events-agent.json (events logged with add_event); every event carries source "app" or "agent". Optional {type, tag, start, end} filters; a range event matches a window it overlaps. Sorted ascending by date. Returns available:false when neither file exists; absence means nothing was logged or exported, not that nothing happened. |
| add_eventA | Log a context event the user tells you about (a medication start, a habit change, a visit, a trip) so later analysis can segment around it. Writes ONLY health-events-agent.json in the export folder, never Apple Health and never a file the iOS app writes; the app shows these events read-only. Returns the stored event with its id (starting "agent-"). Idempotent: repeating a call with the same clientEventId (or, without one, the same date, type, title and endDate) returns the event already logged instead of adding a duplicate. Ask the user before logging anything they did not state. Refused in demo mode, when the folder is not writable, and on an encrypted export without HEALTH_EXPORT_PASSPHRASE (the file is sealed like the rest of the export when the passphrase is set). |
| remove_eventA | Remove an event that was logged with add_event (id starting "agent-", source "agent" in list_events) from health-events-agent.json. Events logged in the iOS app are refused: they are edited in the app. Removing an id that is already gone changes nothing and says so. Refused in demo mode and when the folder is not writable. |
| get_profileA | 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_check_insA | Morning check-ins the user chose to share (health-check-ins.json): per day a self-rated feeling (1 rough to 5 great), an optional note, an intention for the day and whether it happened (answered the next morning). Optional {start, end} filters. Returns the rows plus a summary (rated, averageFeeling, intentionsAnswered, intentionsMet). Opt-in in the iOS app and off by default, so available:false is the usual answer and means not shared, never "felt nothing". A self-rating is the person's own words, not a measurement. |
| get_workoutsA | 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_sessionsA | 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 separate sessions with the same day. Duplicate copies of one night left by older app versions (sharing an end time with, or lying inside, a longer session on the same day) are collapsed to the longer one and counted in |
| get_strength_logA | The strength log the user keeps in the MetricBridge app (health-strength.json, opt-in, off by default): each session with its exercises and every set as entered (reps, kg, warmup or working, RPE), plus volumeKg, workingSets and an Epley bestEstimateKg per exercise, all-time records per exercise, and the routines the user saved (their own templates). Filters: {exercise (exact name, case-insensitive, e.g. "Back squat"), start, end (local days, inclusive)}. Sessions come oldest first; above 150 matches the most recent 150 are listed and |
| list_tagsA | Tags the user logged in the iOS app (health-tags.json): lifestyle tags such as Alcohol or Sauna, and supplements such as Creatine or Magnesium, by name only and never an amount. Optional {kind: all | supplement | lifestyle, start, end}. Returns one row per tag (kind, days logged, firstDay, lastDay, most logged first) and the tag names per day. Tag export is opt-in in the app and off by default, so available:false is the usual answer and means the file was not exported, not that nothing was tagged. Treat any difference after tagged days as an association in this person's own data, never as evidence that a supplement works. |
| get_cycle_contextA | 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_metricsA | 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. |
| resolve_metricA | Look a metric name up in the canonical naming and unit table. Accepts the export's own name (step_count), a HealthKit identifier (StepCount, HKQuantityTypeIdentifierStepCount), a display title (Step Count) or a common alias (steps, hrv, spo2, weight) and returns the canonical metric, its unit (percentages are 0 to 1 fractions), the unit variants other apps use with the exact formula into the canonical unit, and whether this export holds it. Pass {value, unit} to convert one value, e.g. 180 lb to kg. A word naming several metrics (distance, calories) comes back ambiguous with candidates, and a different measure (RMSSD vs the SDNN that Apple Health stores) is refused with the reason: nothing is guessed. get_health_metrics, get_trends, compare_periods, get_structured_export and correlate_metrics accept the same aliases and report |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| daily_brief | A short morning readout of the most recent day against its trailing week. |
| weekly_review | This week against last week across sleep, heart and activity. |
| doctor_visit_prep | A one-page data brief to bring to an upcoming appointment. |
| what_changed_since_last_visit | Changes in the data since the most recent logged doctor visit. |
| sleep_quality | A descriptive read of recent sleep: duration, stages, split nights. |
| sleep_regularity | How consistent sleep and wake times are, in minutes, with the sessions cited. |
| hrv_trend | Heart rate variability over the last month, segment-honest. |
| training_week_in_review | The last 7 days of workouts with intensity and structure. |
| race_week_prep | The training block a coach would want to see before race week. |
| zone_minutes_summary | Time by heart rate band across recent workouts, relative to this file. |
| experiment | Run an n-of-1 before/after read around a logged intervention event. |
| medication_before_after | Before/after read around a logged medication start. |
| glp1_dose_step_compare | Per-dose-step segments for weight and related metrics, honestly bounded. |
| sobriety_milestone | The data story since a logged quit date, with the early window reported separately. |
| shift_block_compare | On-shift days against off days using the day filter. |
| travel_honest_monthly_review | A monthly review with timezone-change days excluded and accounted for. |
| cycle_aware_trend_read | Read a metric trend against cycle phase, comparing like phase with like phase. |
| caregiver_daily_checkin | A calm daily check-in that separates data gaps from changes in the numbers. |
| glucose_day_summary | One day of glucose in the consensus reporting metrics, no advice. |
| nutrition_week_summary | The last 7 days of food logged by another app, as daily means over logged days only. |
| long_term_activity_narrative | The multi-year activity story at monthly resolution. |
| data_coverage_audit | What this export actually contains: surfaces, ranges, gaps. |
| profile_aware_context_bootstrap | Open a session with the user's opted-in context loaded and its limits stated. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 21 tools
Several pairs overlap: get_trends is essentially a fixed-window case of compare_periods, get_health_metrics / get_structured_export / query_health_data all retrieve metric values over a range, and get_mcp_status embeds a freshness block that get_freshness covers in depth. The descriptions do a good job steering between them ('prefer the specific tools above', 'use get_health_metrics for day-level questions'), but an agent still has to read carefully to pick correctly.
Every tool is snake_case verb_noun (get_*, list_*, add_event, remove_event, resolve_metric, correlate_metrics, compare_periods), with no camelCase or bare-noun outliers. The verb choice also reflects action type consistently (get for single lookups, list for enumerations).
21 tools is at the heavy end, and the domain breadth (metrics, trends, correlations, events, profile, check-ins, workouts, sleep, strength, tags, intraday, freshness) justifies most of them. However, a handful are redundant surface area: query_health_data duplicates routing already done by the specific tools, get_structured_export heavily overlaps get_health_metrics, and get_mcp_status overlaps get_freshness.
Coverage is strong: metric discovery/resolution, retrieval, aggregation, trends, period comparison, correlation, events with add/list/remove, plus workouts, sleep, strength, tags, check-ins, profile, intraday and freshness. Minor gaps remain: no update_event (only add/remove), and workout routes/interval detail are only exposed as flags rather than retrievable.