How health4.ai works

Apple has no server-side HealthKit API — there is no webhook, no OAuth flow, no REST endpoint that lets a remote server pull your health data. health4.ai solves this with a tiny iOS app that syncs HealthKit directly to a Postgres database you control, then an open-source MCP server gives any AI structured access to it. Your data never touches health4.ai's servers.

Setup — step by step

1

Create a free Supabase project

Go to supabase.com and create a free project. Open its SQL editor and run the health4.ai schema (tables, row-level security, grants), then deploy the ingest function and add the user you will sign in as:

# 1. SQL editor → run https://health4.ai/schema.sql
# 2. Deploy the ingest function (Supabase CLI):
supabase functions deploy healthkit-ingest \
  --project-ref <ref> --no-verify-jwt
# 3. Authentication → Users → add the user you will sign in as

Supabase only: the app signs in with Supabase Auth and writes through a Supabase Edge Function. Download schema.sql · Full setup guide

2

Install the iOS app and connect your database

Download health4.ai from the App Store. Tap through the Welcome and Privacy screens, then open the Connect tab. If asked for a backend, choose Supabase. Paste your project URL and anon key, then tap Sign In as the user you added.

Project URL: https://abc123.supabase.co — Settings → API
Anon key: eyJ… — Settings → API → anon public
3

Grant HealthKit access — sync begins

Tap Allow Health Access during onboarding. iOS shows the standard HealthKit permission sheet — you choose which types to share. The app immediately begins a full historical backfill (your entire Apple Health archive), then switches to live incremental sync via HKObserverQuery — iOS wakes the app in the background whenever new data arrives.

4

Run the MCP server on your Mac

Clone the repo and configure the server with your Supabase credentials:

git clone https://github.com/jefflitt1/health4ai
cd health4ai/mcp-server
pip install -r requirements.txt
cp .env.example .env
# Edit .env: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, HEALTHKIT_USER_ID
5

Add to your AI client

Add one block to your AI's MCP config. Works with Claude Desktop, Cursor, Continue, and any MCP-compatible client:

{
  "mcpServers": {
    "health4ai": {
      "command": "python3",
      "args": ["/path/to/health4ai/mcp-server/main.py"]
    }
  }
}
✓

Ask your AI about your health

Once the backfill completes (usually 2–10 minutes depending on your history), go to your AI and ask:

›"How was my sleep this week?"
›"Show me my HRV trend over the last 30 days"
›"What were my worst recovery days this year?"
›"Compare my resting HR before and after I started training"

Common questions

Can I use Neon or a local Postgres instead of Supabase?▾

No. The iOS app signs in with Supabase Auth and sends data to a Supabase Edge Function, so it needs a Supabase project you own. Neon, local Docker and other plain Postgres hosts have no way to receive data from the app. Full setup guide

Can I use health4.ai with multiple AI clients?▾

Yes. The MCP server is a local stdio process — point as many AI clients as you like at the same main.py. Add the server entry to Claude Desktop, Cursor, Continue, or any MCP-compatible client. All clients read from the same Supabase database.

Does health4.ai ever see my health data?▾

No. The iOS app syncs directly from your iPhone to your Supabase database — health4.ai's servers are never in the path. The MCP server runs locally on your Mac and reads from your database. We never see your health data.

How do I revoke HealthKit access?▾

Go to iPhone Settings → Privacy & Security → Health → health4ai and toggle off any or all data types. The app stops receiving new data immediately. Your historical data stays in your own Supabase database — delete it there directly if you want it gone.

Under the hood

iPhone (health4.ai iOS app)
  └─ HKObserverQuery ──► fires on every new HealthKit sample
  └─ BGProcessingTask ──► runs full sync while charging
         │  POST /functions/v1/healthkit-ingest  (your Edge Function)
         ▼
  Your Supabase project (you own this — health4.ai has no access)
  ├── healthkit_metrics          (raw samples, 30-day rolling window)
  └── healthkit_daily_summaries  (pre-aggregated, multi-year)
         │  read over a direct Postgres connection
         ▼
  health4ai MCP server (local stdio, runs on your Mac)
  tools: get_sleep · get_hrv_trend · get_workouts · get_daily_snapshot
            query_metric · get_health_summary · get_long_term_trend
            search_records · get_metric_stats · compare_periods
            get_coaching_brief
         │
         ▼
  Claude Desktop / Cursor / Continue / Ollama

Open source, MIT licensed. The full source for the iOS app and MCP server is at github.com/jefflitt1/health4ai.

GitHub →Join the waitlist