Bring Apple Health history into an AI workflow with MCP

#opensource #mcp #ios #selfhosted

I maintain Apple Health AI Bridge, a free, open-source project that makes Apple Health records available to AI tools and scripts. An iPhone companion sends the categories you permit to a receiver on your Mac or Linux computer. The receiver stores the history in SQLite and exposes a CLI and local read-only MCP server.

The useful part is returning to the history with a new question. You can compare two periods, choose a different metric, or revisit the comparison after more records arrive, without preparing another archive for each conversation.

Ask about a period

An example prompt for a compatible AI client is:

Compare my recorded activity in October 1-7 with September 24-30. Show the sleep and workout records behind the comparison.

The client can request the periods through get_daily_summary, then use get_sleep_summary and get_workouts for the relevant records. These tools accept start_date and end_date.

For the first period, the get_daily_summary argument object is:

{
  "start_date": "2026-10-01",
  "end_date": "2026-10-08"
}

For the comparison period:

{
  "start_date": "2026-09-24",
  "end_date": "2026-10-01"
}

The start date is inclusive and the end date is exclusive. Each call covers seven days. Daily summaries include sample_totals for sum-safe metrics and sample_statistics for other sample metrics, along with source information.

Go beyond the weekly summary

get_timeseries retrieves selected metrics using type_codes and UTC start_time and end_time values. You can inspect heart rate or weight observations for a chosen interval, while sleep and workouts have their own tools.

list_synced_metrics shows which metrics have reached your receiver. list_supported_timeseries_types provides the catalog for time-series queries, and explain_sources describes where the records came from. The CLI provides another way to inspect the same stored history.

Connect your client

You'll need an iPhone on iOS 18+ and a Mac or Linux receiver. The install guide walks through the companion, routing, pairing and first upload.

Setup generates a local stdio MCP descriptor with the executable command and database arguments. Use that descriptor to configure a compatible client on the receiver host. Once connected, you can ask about the stored history, including while the iPhone app is closed.

The tool definitions show the input schemas. The repository contains the receiver, iPhone source and supported-data reference.