Skip to main content
Glama
MetricBridge (formerly Health Export AI)

MetricBridge (formerly Health Export AI)

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
HEALTH_LISTENNoSet to '1' to enable LAN push receiver
PAIRING_SECRETNoOptional pairing code from the iOS app to gate access
HEALTH_DATA_DIRNoPath 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

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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 freshness block (its state is stale_copy, with a stale_copy list, when this machine holds an older copy of the export than the phone last wrote), and a recompute summary of past days rebuilt after late-arriving samples (with any days too old to rebuild; supported: null when the cache cannot tell). Call this first to confirm the bridge is connected. The result also includes app.unlockUrl and app.appStoreUrl, the website and App Store page of the companion iOS app that writes the export; both links carry fixed campaign attribution labels.

get_freshnessA

How current the exported files are, so you can decide whether to trust what you read or ask the user to refresh. stale is judged on the core files (the daily cache and health-sessions.json), never on the hourly intraday file: true when their newest write is older than stale_after_hours (default 26, or HEALTH_STALE_AFTER_HOURS, or your maxAgeHours), or when this machine holds a stale copy. state is fresh, stale, stale_copy, no_data, locked or demo. stale_copy means the phone's manifest (.health-manifest.json) or iCloud says the phone wrote a newer version of a core file than the one on this machine (stale_copy lists each file with localWrittenAt, phoneWrittenAt and reason); relay the recommendation, which says how to make iCloud Drive download it. Also returns age_hours, as_of (when the phone wrote the daily cache), last_data_date, data_lag_days, per-file write times with each file's match against the manifest, stale_files, manifest_behind (the manifest lags the data, not stale), sessions_last_night (present or absent; without a manifest, advisory only, people skip nights) and, on a Mac, an advisory icloud status per core file. Same rule as the status --max-age cron gate. When no export is found, recommendation also names the companion iOS app's App Store page and website (the same links as app.appStoreUrl and app.unlockUrl); when the newest readable export is older than the server's own window (not a stricter maxAgeHours), it names the website. Both carry fixed campaign labels. Cheap: call it again before a long analysis.

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 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. For blood_pressure_systolic or blood_pressure_diastolic at day granularity, the individual readings behind the daily mean are attached as readings [{t, systolic, diastolic, source, manual}] when the app exported them (health-readings.json), the most recent 150 in range, with readingsOmitted counting the rest. A day the app rebuilt after samples arrived late (or were deleted) carries recomputed_at, and a metric with rebuilt or possibly stale past days carries a recompute block (backfilled_days, recomputed_at, capped); untouched days carry neither.

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 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_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 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_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 collapsedDuplicates. A session with manualInBed:true was built from an In Bed entry typed into the Health app with no asleep sample. Timestamps carry the local UTC offset at the time of the sample.

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 sessionsOmitted counts the rest. An unknown exercise returns count 0 with knownExercises. Logged by hand, never read from Apple Health; when the file is missing the answer is available:false, which means the user has not switched the export on, not that they do not train.

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 resolvedFrom when they used one; other tools take the export's own names. The export holds one value per metric per day, merged across sources by Apple Health, so this tool states honestly whether per-source disagreement can be seen in the file (exports that record per-source attribution carry src/by and a sources block; others report it as not available) rather than inventing it.

Prompts

Interactive templates invoked by user choice

NameDescription
daily_briefA short morning readout of the most recent day against its trailing week.
weekly_reviewThis week against last week across sleep, heart and activity.
doctor_visit_prepA one-page data brief to bring to an upcoming appointment.
what_changed_since_last_visitChanges in the data since the most recent logged doctor visit.
sleep_qualityA descriptive read of recent sleep: duration, stages, split nights.
sleep_regularityHow consistent sleep and wake times are, in minutes, with the sessions cited.
hrv_trendHeart rate variability over the last month, segment-honest.
training_week_in_reviewThe last 7 days of workouts with intensity and structure.
race_week_prepThe training block a coach would want to see before race week.
zone_minutes_summaryTime by heart rate band across recent workouts, relative to this file.
experimentRun an n-of-1 before/after read around a logged intervention event.
medication_before_afterBefore/after read around a logged medication start.
glp1_dose_step_comparePer-dose-step segments for weight and related metrics, honestly bounded.
sobriety_milestoneThe data story since a logged quit date, with the early window reported separately.
shift_block_compareOn-shift days against off days using the day filter.
travel_honest_monthly_reviewA monthly review with timezone-change days excluded and accounted for.
cycle_aware_trend_readRead a metric trend against cycle phase, comparing like phase with like phase.
caregiver_daily_checkinA calm daily check-in that separates data gaps from changes in the numbers.
glucose_day_summaryOne day of glucose in the consensus reporting metrics, no advice.
nutrition_week_summaryThe last 7 days of food logged by another app, as daily means over logged days only.
long_term_activity_narrativeThe multi-year activity story at monthly resolution.
data_coverage_auditWhat this export actually contains: surfaces, ranges, gaps.
profile_aware_context_bootstrapOpen a session with the user's opted-in context loaded and its limits stated.

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A3.9/5.0

Scored across 21 tools

Disambiguation3/5

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.

Naming Consistency5/5

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).

Tool Count3/5

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.

Completeness4/5

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.

Maintenance

ActivityNo data
ResponsivenessLimited data