health4ai

health4.ai — Apple 健康 × AI

用日常语言向 AI 询问睡眠、HRV、恢复情况和健身状态。
免费 iOS 应用 · 使用你自己的数据库 · 兼容任何 MCP 客户端

在 App Store 下载 health4ai

功能介绍

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

Apple 健康保存着你多年积累的生物特征数据——睡眠阶段、HRV、心率、锻炼、VO₂ max 以及 150 多种其他指标。health4.ai 通过专门打造的 MCP 工具，让 Claude、ChatGPT、Cursor、Ollama 或任何兼容 MCP 的客户端都能查询这些数据。

数据由你掌控。 数据会同步到由你创建并拥有的 Supabase 项目。health4.ai 不运行任何后端，也不会存储或访问你的健康数据。

项目缘起

演示

演示视频即将推出。以下是典型对话示例：

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.

快速开始

health4ai 需要一个由你拥有的 Supabase 项目。应用使用 Supabase Auth 登录，并通过 Supabase Edge Function 写入数据，因此不支持纯 Postgres（Neon、本地 Docker 容器）作为后端。完整操作指南：docs/SETUP.md。

1. 创建数据库架构。 在 supabase.com 创建项目，打开 SQL 编辑器并运行 web/public/schema.sql（也可访问 https://health4.ai/schema.sql）。该文件由 supabase/bootstrap/ 生成：包含表、行级安全策略，以及禁止客户端直接访问的授权设置。请勿使用 supabase db push——编号迁移文件不适用于全新项目。

2. 部署 ingest 函数（需要 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 是有意设置的：函数会自行验证已登录用户的令牌，并且只会以该用户的 ID 写入数据。

3. 创建用户。 在控制面板中依次选择 Authentication → Users → add a user，并复制其 UID。应用会登录，不会注册。

然后设置 MCP 服务（在同一份检出代码中）：

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

编辑 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)

添加到你的 AI 客户端：

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

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

从 App Store 安装 iOS 应用，然后将其连接到该 Supabase 项目（Project URL + anon key），使用你创建的用户登录，并轻点 Start Sync。如需 TestFlight 测试版，请遵循测试人员隔离指南；切勿使用他人的后端或凭据。

MCP 工具

如果指标为空，请先查看 data_status，再判断其含义

iOS 不会告知应用某项 Health 权限已被拒绝。 对于你尚未分享的类型，系统会返回空结果，与某一天你确实什么都没做时的结果逐字节相同。HealthKit 的 API 无法区分这两种情况，因此，助手如果只读到一个 0，就会信誓旦旦地告诉你没有走过任何步。

因此，可能返回空结果的工具都会附带一个 data_status 区块：

• never_recorded — 此指标从未为你生成过样本。对于步数、心率、活动能量或步行距离，如果数据正在分享，就不可能出现这种情况，因此几乎可以肯定并非如此。打开 健康 → 共享 → App → health4ai，开启该指标，然后从应用的“主页”选项卡重新运行导入。
• empty_window — 你查询的时间范围内没有数据，但该指标在其他时间有数据。这是真实的数据缺口，不是权限问题。

这并非假设情形。作者自己的账户中，步数、心率、活动能量和步行距离在将近三个月内都被悄悄取消了共享，而其他所有指标仍正常同步，应用始终显示绿色的“Complete”。

架构

┌─────────────────────────────────────────────────────────────┐
│  iPhone                                                      │
│  HKObserverQuery + BGTaskScheduler                          │
│  → continuous background sync                               │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS → your healthkit-ingest Edge Function
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  Your Supabase project (you own it)                         │
│  healthkit_metrics · healthkit_daily_summaries              │
│  row-level security on · no direct client access            │
└──────────────────────────┬──────────────────────────────────┘
                           │ Postgres connection (database password, from your machine)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  FastMCP server  (mcp-server/main.py)                       │
│  FastMCP tools · stdio transport                             │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP
                           ▼
              Claude · ChatGPT · Cursor · Ollama · any client

数据层级： 最近 30 天内的查询会返回原始样本。更早的日期会使用 healthkit_daily_summaries 中已有的预聚合行；如果没有，则在 Postgres 中根据原始样本按天聚合。因此，无论项目是否运行过汇总程序，结果都完整（在全新且可自托管的项目中，汇总程序从未运行过）。响应中包含一个 tier 区块，说明每个层级提供了多少天的数据。日历日期遵循 HEALTH4AI_TZ（默认为 UTC；在 mcp-server/.env 中设置）。

仓库结构

health4ai/
├── ios/                         # Swift/SwiftUI iOS app (iOS 17+)
│   └── Health4AI/               # HealthKit sync engine, auth, settings
├── mcp-server/
│   ├── main.py                  # FastMCP server entry point
│   ├── tools.py                 # MCP tool implementations
│   └── .env.example             # Required environment variables
├── web/
│   ├── public/schema.sql        # Generated from supabase/bootstrap (Supabase only)
│   └── src/                     # Astro marketing site
├── scripts/
│   ├── import_health_export.py  # One-time XML backfill from Apple Health export
│   └── summarize_historical.py  # Backfill daily summaries table
└── docs/
    └── SETUP.md                 # Detailed setup guide

隐私

你的健康数据会直接从 iPhone 发送到你自己的 Supabase 项目。health4.ai 从不接收、存储或访问这些数据。MCP 服务使用你自己的凭据在本地运行——你的数据不会经过我们的基础设施。

详情请参阅隐私政策。

贡献

采用 MIT 许可证。欢迎提交 PR。

适合入门的领域：增加指标聚合、支持通过 JWT/RLS 实现多用户、支持 Android，以及编写更多 MCP 客户端集成指南。

SQL 更改需要显式授权。 Supabase 不再自动授予 anon / authenticated / service_role 对新建 public 表的访问权限（适用于 2026-10-30 起创建的项目），因此，在 SQL 中明确允许哪些角色使用表之前，无法通过 Data API 访问该表。请从 scripts/migration-templates/public_table.sql 开始；供客户安装的表应放在 supabase/bootstrap/ 中（然后运行 scripts/build_schema_sql.sh）。scripts/lint-migration-grants.sh 会检查 web/public/schema.sql 和迁移目录；如果表没有授权，CI 将失败。旧编号迁移中的检查结果已固定在 scripts/migration-grants-baseline.txt 中。

许可证

MIT——参见 LICENSE。