Health Data (your own Supabase)

health-mcp

将你的健康数据（体重、身体成分、卡路里、宏量营养素、水分）作为 MCP 数据层，供 AI 查询。零托管：数据存储在由 你 创建并拥有的 Supabase 项目中的 Postgres 数据库里——除你之外，没有人会持有你的数据或密钥。iOS 快捷指令每天从 Apple Health 同步数据；Claude（或任何 MCP 客户端）通过完全运行在你自己的项目中的连接器读取数据。

开始设置（四个步骤，约 20 分钟）

1. 创建数据库和连接器

有三种方式，任选其一——最终都会得到相同内容：连接器 URL，以及摄取 URL 和摄取密钥。

• 设置页面 — 无需终端，可在 Supabase 控制面板中按引导操作。
• npx @almostjacked/health-mcp setup — 最快捷，需要 Node ≥ 18。引导你登录 Supabase、选择或创建项目、应用架构、部署两个函数并生成密钥，最后显示连接器 URL 和快捷指令配置。
• 手动控制面板操作指南 — 与设置页面中的步骤相同，以文字形式列出，方便想先阅读或手动操作的人。

Supabase 免费套餐允许创建 2 个活跃项目，因此你可以在已有的一个免费项目之外再使用它。

2. 导入历史数据

如果不导入，adaptive-TDEE 需要约两周的每日同步，才能积累足够的数据。导入后，所有功能都能立即使用。

1. 在 iPhone 上：健康 App → 你的个人资料照片 → 导出所有健康数据。这会生成一个 export.zip 文件（如果历史数据较长，可能需要几分钟）。
2. 将该文件传到用于设置的设备，然后将其拖放到设置页面的 导入面板。先勾选 试运行，预览将要发送的内容，然后再确认导入。

3. 设置每日同步

快捷指令面板上有一个下载按钮——无需签名，也无需终端。下载快捷指令并安装到 iPhone 上（iOS 会在导入时提示你粘贴摄取 URL 和密钥），然后开启每天上午 9 点的自动化。完整的逐步说明（包括 iOS 导入时某个步骤未能保留的处理方法）：docs/shortcut.md。

**最简单的安装方式（优先使用 Mac）：**在 Mac 上下载已签名的快捷指令并双击——两个导入提示会直接出现在页面的复制按钮旁边，iCloud 会自动将快捷指令同步到 iPhone。（没有 Mac？将文件发送到手机，然后在手机上完成提示操作。）

4. 连接 Claude

1. 打开 claude.ai → 设置 → 连接器 → 添加自定义连接器。
2. 粘贴第 1 步中的连接器 URL。
3. 保存。现在 Claude 可以使用 health-mcp 工具了。

如果添加连接器时出现 “无法向 [name] 的登录服务注册”，这是 claude.ai 的临时问题，并非连接器有问题——再次尝试添加即可。

使用方法

可以向 Claude 提出这类问题：

我本周的平均卡路里摄入量与上周相比如何？

显示我过去 90 天的体重趋势。

我的每日同步是否停止了？检查 get_sync_status。

与 fitness-tools 搭配使用

health-mcp 回答“发生了什么”（你记录的体重和卡路里）； fitness-tools 回答“这意味着什么”（TDEE、宏量营养素、体脂、1RM）。get_energy_inputs 工具会返回 {date, weight, kcal} 条目，其格式与 fitness-tools 的 adaptive-tdee 完全一致——无需重新格式化。向 Claude 提问：

获取我过去 90 天的能量输入，然后使用 fitness-tools 计算我的自适应 TDEE。

adaptive-tdee 至少需要 10 天的数据，且这些天都必须同时有称重记录和 卡路里总量——如果你跳过了步骤 2，预计需要同步约 2 周后才能搭配使用。

如果你也使用 Hevy 训练，可以搭配 hevy-mcp，补全训练方面的数据 （训练计划、记录的组数、1RM 趋势）。

工具

工具	描述
get_schema	Postgres 架构（两张表）和指标注册表（名称、单位、类别）。编写查询工具的 SQL 前请先调用。
get_sync_status	每项指标的最新日期、行数以及距离上次录入的天数。分析前可用于检测每日同步是否停滞。
get_recent	过去 N 天的记录（默认 30 天），可选指定一项指标。每日总量和单项测量值会列在同一个按日期排序的列表中。
get_daily_summary	某一天的所有指标（默认：有数据的最近一天）：总量及每一条称重/测量记录。
get_stats	在指定日期范围内，某项指标的最小值/最大值/平均值以及滚动平均值序列（按日/周/月汇总）。
query	应急入口：针对 get_schema 提供的架构运行一条只读 SQL 语句（SELECT 或 WITH…SELECT）。拒绝写入/DDL；强制限制 LIMIT 500。
get_energy_inputs	返回同时有卡路里总量和称重记录的日期对应的每日 (date, weight, kcal) 条目——格式与 fitness-tools 的 adaptive-tdee 完全一致。

架构

Apple Health --> "Sync Health Data" Shortcut --> your health-ingest function --> your Postgres
                                                                                      |
Claude  <-- run_readonly (SELECT-only) <-- your health-mcp connector function <------+

以上内容都不会接触我们运营的基础设施。两个 Edge Functions 都运行在你的 Supabase 项目中；唯一会离开你设备的，是 Shortcut 直接向你自己的项目 URL 发送的 HTTP POST。

隐私政策

零托管。 health-mcp 是你运行在自己所拥有的基础设施上的软件——我们（维护者）从不运营任何能够查看你健康数据或密钥的服务器，而且你无需与我们断开连接，因为你从未连接过我们。

• 你的数据只存储在你创建的 Supabase Postgres 项目中。我们无法访问、没有副本，也无法查看。
• 你的密钥（MCP_TOKEN、INGEST_KEY、你的 Supabase secret key）由你或在你设备上运行的向导生成，作为密钥存储在你自己的 Supabase 项目中；对于 stdio/.mcpb 安装方式，密钥还会保存在本地 MCP 客户端（Claude Desktop / Claude Code）中，并且只会发送到你自己项目的 URL。
• Shortcut 会将数据从你的手机直接发送到你的 Edge Function URL；绝不会经过我们的任何服务器。
• query 工具受 SQL 保护，只允许执行只读语句；它使用的数据库角色 (health_reader) 仅获授 SELECT 权限——这是由 Postgres 层强制执行的，而不仅仅依靠应用代码。

其他客户端

更喜欢使用 Claude Desktop，或自己运行服务，而不是使用托管连接器？两种方式都使用步骤 1 中的同一个 Supabase 项目——只是连接方式不同。

**Claude Desktop：**下载 health-mcp.mcpb， 双击打开，并在提示时粘贴你的 Supabase 项目 URL 和 secret key。

任何 stdio MCP 客户端（Claude Code 等）：

claude mcp add health-mcp -e SUPABASE_URL=<url> -e SUPABASE_SECRET_KEY=<key> -- npx -y @almostjacked/health-mcp

仓库结构

packages/core   @almostjacked/health-mcp-core — tools, ingest/normalization, setup.sql
apps/mcp        @almostjacked/health-mcp       — stdio server, .mcpb, setup wizard
web             the setup page (provision + import + Shortcut panels)
supabase/functions/health-mcp     the read connector (deployed to your project)
supabase/functions/health-ingest  the write endpoint the Shortcut posts to

开发

corepack enable
pnpm install
pnpm -r test
pnpm -r typecheck

许可证

MIT — 参见 LICENSE。