health4.ai — Apple Health × AI

---

What it does

iPhone HealthKit → Your Supabase project → MCP server → Any AI

Apple Health holds years of your biometric data — sleep stages, HRV, heart rate, workouts, VO₂ max, and 150+ other metrics. health4.ai makes all of it queryable from Claude, ChatGPT, Cursor, Ollama, or any MCP-compatible client through purpose-built MCP tools.

You control the data. It syncs to a Supabase project you create and own. health4.ai runs no backend and never stores or has access to your health data.

---

Why it exists

Problem	health4.ai fix
Apple has no HealthKit server API — all access requires an on-device app	Native iOS app with HKObserverQuery + BGTaskScheduler background sync
Health Auto Export only works on the same WiFi	Your data lands in Postgres — queryable from any AI, anywhere
The claude.ai Apple Health connector doesn't reach Claude Code CLI or Cursor	Standard MCP (stdio) — one config block works everywhere
Most solutions require a managed cloud service	Bring your own Supabase project — health4ai runs no server

---

Demo

Demo video coming. Here's what a typical conversation looks like:

You:     How was my recovery this week? Anything standing out?

Claude:  Your recovery this week was mixed but trending positive.
         • HRV averaged 58ms (Tue–Thu strong at 64–68ms; Monday low at 44ms after Saturday's long run)
         • Sleep averaged 7h 12m — Wednesday and Thursday were your best nights (7h 40m+)
         • Resting HR dropped from 54bpm Monday to 49bpm Friday — a good sign
         Recommendation: today looks like a solid day for a moderate-intensity session.

---

Quick start

health4ai needs a Supabase project you own. The app signs in with Supabase Auth and writes through a Supabase Edge Function, so plain Postgres (Neon, a local Docker container) is not a supported backend. Full walkthrough: docs/SETUP.md.

1. Create the schema. Create a project at supabase.com, open its SQL editor, and run web/public/schema.sql (also at https://health4.ai/schema.sql). It is generated from supabase/bootstrap/: tables, row-level security, and grants that deny clients direct access. Do not use supabase db push — the numbered migrations do not apply to a fresh project.

2. Deploy the ingest function (needs the Supabase CLI):

git clone https://github.com/jefflitt1/health4ai.git
cd health4ai
supabase functions deploy healthkit-ingest --project-ref <your-project-ref> --no-verify-jwt

--no-verify-jwt is deliberate: the function verifies the signed-in user's token itself and writes only under that user's ID.

3. Create your user. In the dashboard, Authentication → Users → add a user, and copy its UID. The app signs in; it does not sign up.

Then set up the MCP server (from the same checkout):

cp mcp-server/.env.example mcp-server/.env

Edit mcp-server/.env:

DATABASE_URL=postgresql://...  # your project's pooler connection string (database password, not a key)
HEALTHKIT_USER_ID=...           # your Supabase Auth user's UID (see mcp-server/.env.example)

Add to your AI client:

{
  "mcpServers": {
    "health4ai": {
      "command": "python",
      "args": ["/path/to/health4ai/mcp-server/main.py"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "HEALTHKIT_USER_ID": "<your auth user UID>"
      }
    }
  }
}

Same block → ~/.cursor/mcp.json

Pair with mcphost or mcp-client-for-ollama:

mcphost --model ollama/llama3.2 \
  --mcp-server "health4ai:python /path/to/health4ai/mcp-server/main.py"

The model runs on your hardware and the MCP server runs locally; your health data is read from your own Supabase project.

Install the iOS app from the App Store, then connect it to that Supabase project (Project URL + anon key), sign in as the user you created, and tap Start Sync. For a TestFlight beta build, follow the tester-isolation guide; never use another person's backend or credentials.

---

MCP tools

Tool	What it answers
get_health_summary	Overview of key metrics for the past N days
get_sleep	Per-night sleep breakdown with REM, Deep, Core stages. One source per night: Oura > Apple Watch > Whoop > Garmin > Withings > whichever other source (iPhone included) has the most stage records
get_hrv_trend	Daily HRV (SDNN) with rolling comparison and trend
get_daily_snapshot	Everything recorded for a specific date
get_workouts	Recent workouts with type, duration, distance, calories
query_metric	Raw time-series for any HealthKit metric type
get_long_term_trend	Monthly aggregates over years (raw + summary tiers)
get_coaching_brief	Recovery status, sleep quality (same one-source-per-night rule as get_sleep), training load, fitness markers
search_records	Find days where a metric crossed a threshold
get_metric_stats	Personal baseline: min/max/mean/percentiles
compare_periods	Compare a metric between two date ranges

If a metric is empty, read data_status before believing it

iOS never tells an app that a Health permission was denied. A type you have not shared returns an empty result, byte-for-byte identical to a day where you genuinely did nothing. Nothing in HealthKit's API can distinguish the two, so an assistant reading a bare 0 will confidently tell you that you took no steps.

Tools that can return an empty result therefore attach a data_status block:

This is the beginning of the README. Read the rest at the original. Read the full README ↗