<div align="center">

<img src="assets/brand/health-bridge-lockup.png" alt="Health Bridge logo" width="720">

Apple Health AI Bridge

Local-first Apple Health context for AI agents.

Website · Quickstart · MCP · iPhone path · HealthKit read types · Scope · Security · Support · Privacy · Docs

</div>

Apple Health AI Bridge turns HealthKit data into local, source-grounded context an agent can read without sending your health history to a hosted service.

The stack is intentionally boring: a read-only iOS companion, a receiver you run, SQLite on your machine, a CLI, and a read-only MCP server. Start with synthetic data in a minute; use the iPhone path only when you are ready to pair a private receiver.

Apple Health AI Bridge is the open-source project and repository. Health Bridge is the iPhone companion name, and Health Bridge for AI is the public website name.

flowchart LR
  HealthKit[iPhone HealthKit] -->|read permission| App[iOS companion]
  App -->|authorized batches| Receiver[local receiver]
  Receiver --> DB[(SQLite)]
  DB --> CLI[CLI / JSON / Markdown]
  DB --> MCP[read-only MCP]
  MCP --> Agent[local agent]

Why this exists

AI assistants are useful when they can see current context and cite where it came from. Apple Health already has that context, but raw exports, screenshots, and copy-pasted summaries are a bad interface for agents.

This project provides a local bridge instead:

• sync Apple Health data the user allows into a local SQLite store;
• keep provenance, units, time ranges, sync runs, and data families attached;
• expose fixed query and MCP tools instead of raw database access;
• use synthetic fixtures for public examples and tests;
• keep receiver credentials and real health values out of the repository.

Prerequisites

For the synthetic quickstart and MCP path:

• Git;
• Python 3.11+;
• uv.

Real Apple Health sync additionally requires an iPhone running iOS 18 or later, a Mac with Xcode 16 or later, local signing access, and a receiver URL the phone can reach.

Quickstart

The quickstart uses synthetic fixture data. No iPhone, Apple account, receiver token, or HealthKit permission is needed.

git clone https://github.com/roian6/apple-health-ai-bridge.git
cd apple-health-ai-bridge
uv sync --all-extras --dev

uv run health-bridge init --db .tmp/quickstart.sqlite
uv run health-bridge ingest-fixture \
  --db .tmp/quickstart.sqlite \
  --input fixtures/health_bridge_batch_v1.synthetic.json

uv run health-bridge status --db .tmp/quickstart.sqlite --markdown
uv run health-bridge mcp smoke --db .tmp/quickstart.sqlite

Expected result: the database initializes, the synthetic batch ingests, Markdown status renders aggregate counts, and MCP smoke returns a compact read-only summary with forbidden_hits: [].

Query

uv run health-bridge query daily-summary \
  --db .tmp/quickstart.sqlite \
  --start-date 2026-06-01 \
  --end-date 2026-06-08

uv run health-bridge query supported-timeseries-types --category body
uv run health-bridge status --db .tmp/quickstart.sqlite --json

supported-timeseries-types describes the bridge's public type catalog and aggregation semantics. It does not mean every listed HealthKit family is live-synced by the iOS companion today; see Scope.

MCP

Start the local MCP server against a private database:

uv run health-bridge mcp start --db .tmp/quickstart.sqlite

Typical client config:

{
  "command": "uv",
  "args": ["run", "health-bridge", "mcp", "start", "--db", ".tmp/quickstart.sqlite"],
  "cwd": "/absolute/path/to/apple-health-ai-bridge"
}

If your MCP client cannot set cwd, use uv --directory:

{
  "command": "uv",
  "args": ["--directory", "/absolute/path/to/apple-health-ai-bridge", "run", "health-bridge", "mcp", "start", "--db", ".tmp/quickstart.sqlite"]
}

The MCP surface is read-only. It exposes status, context Markdown, metric coverage, supported type metadata, daily summaries, timeseries, workouts, sleep, and source queries.

iPhone path

Real Apple Health sync is a developer-preview path today. It needs an iPhone running iOS 18 or later, a Mac with Xcode 16 or later and a signing environment, and a receiver URL the phone can reach. Follow docs/ios-self-build.md for the full self-build flow and docs/pairing.md for the QR-first pairing/fallback matrix.

prove the synthetic path
→ start a private receiver and verify its phone-facing /health URL
→ generate private pairing/setup material
→ install the iOS companion
→ pair the receiver
→ allow selected read-only Health permissions
→ run Sync Now
→ verify redacted CLI/MCP output locally

For a same-machine receiver smoke test, keep the receiver running in one terminal:

uv run health-bridge init --db .tmp/device.sqlite
uv run health-bridge receiver start --db .tmp/device.sqlite --host 127.0.0.1 --port 8765

For a physical iPhone, do not use 127.0.0.1 in setup material. Use a private LAN or private-network URL the phone can reach, verify /health, then generate setup material:

PHONE_REACHABLE_BASE_URL="http://<phone-reachable-private-host>:8765"
curl -fsS "$PHONE_REACHABLE_BASE_URL/health"

PHONE_REACHABLE_BATCH_URL="$PHONE_REACHABLE_BASE_URL/v1/batches"
uv run health-bridge dev device-session \
  --db .tmp/device.sqlite \
  --label ios-companion \
  --receiver-url "$PHONE_REACHABLE_BATCH_URL" \
  --setup-page .tmp/ios-companion-device-session.html

Generated setup pages, pairing links, tokens, receiver databases, and real-device logs are private. Do not commit them. Expert receiver commands that print tokens or pairing links require explicit secret-output flags; prefer dev device-session for onboarding.

No official public TestFlight invitation path has been published. Treat distribution as private/pending; the public developer-preview path is currently the documented self-build flow.

Scope

Implemented in the developer preview:

Area	Status
Local store	SQLite migrations, synthetic fixture ingest, receiver batch ingest
iOS companion	Pairing, Keychain token storage, local outbox retry, disconnect, privacy copy
Live Apple Health sync	Steps, workouts, sleep, and every runtime-available quantity type implemented by the companion and allowed through Apple Health, all in one foreground/automatic coverage plan
Background work	Observer registration requested across runtime-supported types, with per-type results, trigger-prioritized reconciliation, and iOS-controlled timing
Agent surfaces	CLI, JSON, Markdown, and read-only MCP
Metadata	Supported type catalog with aggregation semantics and iOS support labels

How to read the catalog:

Category	Meaning
Live today	Implemented receiver/CLI/MCP path and shared foreground/automatic iOS sync for the families listed above
Metadata supported	Type codes, units, sensitivity, aggregation semantics, and query labels that may be used by fixtures, stored data, or future iOS readers
Future work	HealthKit families that need separate readers, permissions, normalization, review copy, and real-device proof before being claimed

Not claimed yet:

• public App Store availability;
• TestFlight availability unless an official beta link or invitation path has been intentionally published;
• hosted sync, hosted relay, or remote MCP;
• full Apple Health coverage for every HealthKit family;
• guaranteed background freshness;
• medical decisions, scoring, or emergency use.

High-risk or structurally different families such as clinical records, ECG/waveforms, medications, symptoms, reproductive health, workout routes/location, nutrition, and generic category/profile/correlation data are future work.

Security model

• HealthKit access is read-only by default.
• The default data path is user-owned: iPhone → companion → your receiver → your SQLite database.
• Public examples use synthetic fixtures.
• Keep real health values, receiver DBs, pairing material, setup pages, bearer tokens, token hashes, cursor values, screenshots with health values, and local outbox payloads out of issues, PRs, docs, logs, and chat.
• The project does not add telemetry, analytics, hidden uploads, advertising hooks, data brokers, or third-party AI calls without an explicit project decision and privacy review.

See SECURITY.md and CONTRIBUTING.md.

Development

uv sync --all-extras --dev
uv run health-bridge --version
uv run ruff format --check .
uv run ruff check .
uv run basedpyright
uv run pytest

For iOS work, use the Xcode project under ios/HealthBridgeCompanion. A simulator build proves compile/config only; real HealthKit data and background execution require physical-device validation.

Docs

Try and integrate

• docs/architecture.md: data path, components, sync scope, and boundaries.
• docs/ios-self-build.md: full self-build flow for the iOS companion.
• docs/pairing.md: QR-first receiver pairing, fallback methods, and environment risks.
• docs/agent-assisted-setup.md: what a local agent can safely automate.

Contributor references

• docs/contracts/health-bridge-batch-v1.md: public batch contract.
• docs/contracts/sqlite-schema-v1.md: storage schema overview.
• docs/contribution-ideas.md: safe starter issue ideas and feedback lanes.
• docs/roadmap.md: current roadmap.
• scripts/README.md: iOS real-device helper scripts.
• docs/release-criteria.md: checks before publishing a preview or release.
• docs/qa/public-preview-qa.md: developer-preview QA guide.
• docs/brand.md: brand assets and usage.

Trademark notice

Apple, Apple Health, HealthKit, iPhone, and Xcode are trademarks of Apple Inc. This independent open-source project is not affiliated with, endorsed by, or sponsored by Apple Inc.

License

Apache License 2.0. See LICENSE.