vaultbeat-apple-health

Vaultbeat Apple Health MCP 服务

你的 Apple Health 数据——睡眠阶段、周期、HRV、静息心率、锻炼、体重、VO₂ max、餐食、举重训练、笔记、症状、情绪（State of Mind）——可由你自己的 AI Agent（Claude Code、Claude Desktop、Codex、Hermes、OpenClaw，以及任何支持 MCP 的工具）读取和写入，并进行端到端加密，只有你的设备能看到明文。

Vaultbeat iPhone 应用会读取 HealthKit，并在手机上加密每条记录。此软件包是你的 Agent 连接的本地服务：它下载密文，在你的设备上解密，并通过 MCP 提供服务。

iPhone (HealthKit → Vaultbeat app, encrypts) ──► cloud (ciphertext only) ──► this server (decrypts locally) ──MCP──► your agent

云端存储的是无法读取的密文。用于解密的密钥会在配对时于你的设备上生成，并且永远不会离开该设备。

要求

• Vaultbeat iOS 应用，版本 1.2.3 或更高，且已登录 — App Store
• uv（用于 uvx）。服务需要 Python 3.11+；如果系统中的 Python 版本较旧，uvx 会自行下载合适的解释器。
• 使用 Agent 需要 Vaultbeat Pro。 配对设备会开启 AI 界面的 3 天试用期；之后，读取和写入都需要 Pro，可在 iOS 应用中购买（Settings → Membership）。访问权限到期后，任何数据都不会被删除；购买 Pro 即可恢复此设备的访问权限，无需重新配对。

此服务可读取的历史数据量取决于应用上传的内容。使用 Pro 时，可读取全部历史数据。试用期间，应用 1.2.9 及更高版本会上传全部历史数据，应用 1.2.8 及更早版本则会上传最近 7 天的数据。未使用 Pro 或试用时，应用 1.2.8 及更早版本会上传最近 7 天的数据，应用 1.2.9 及更高版本则不会上传任何数据。因此，历史数据较少通常是套餐权限所致，而非同步延迟——vaultbeat_doctor 会帮你区分原因。

快速开始

1. 将此设备与 iPhone 配对。

uvx vaultbeat-apple-health@latest bind

命令会显示二维码并等待。在 Vaultbeat 应用中打开 MCP tab → Connect an AI server（应用 1.2.8 及更早版本：Settings → Data & AI）并扫描二维码。命令会等待 5 分钟（可使用 --timeout 修改）；扫描后有 10 分钟完成配对。

2. 将服务添加到 MCP 客户端。

将其作为插件添加到 Claude Code（会添加服务和设置指南，引导 Claude 完成配对）：

/plugin marketplace add Fino-wind/vaultbeat-apple-health
/plugin install vaultbeat-apple-health@vaultbeat

然后运行 /vaultbeat-apple-health:setup。或者只添加服务：

claude mcp add vaultbeat-health -- uvx vaultbeat-apple-health@latest serve --transport stdio

Claude Desktop — 将其添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json），然后重启：

{
  "mcpServers": {
    "vaultbeat-health": {
      "command": "uvx",
      "args": ["vaultbeat-apple-health@latest", "serve", "--transport", "stdio"]
    }
  }
}

Claude Desktop 不会继承 shell 的 PATH。如果提示找不到 uvx，请将 which uvx 返回的绝对路径填入 "command"。

其他任何 MCP 客户端：将 uvx vaultbeat-apple-health@latest serve --transport stdio 作为 stdio 服务运行。@latest 很重要——如果省略，uvx 会一直运行它首次缓存的版本。

3. 检查是否正常工作。 让你的 Agent 调用 vaultbeat_doctor，或运行：

uvx vaultbeat-apple-health@latest doctor

它会检查配置、私钥、云端连通性、配对状态，以及实际的数据获取和解密流程，并列出目前没有可读取数据的类型。刚完成配对后，手机仍在为新设备加密你的历史数据，因此部分类型可能暂时为空；在应用中选择 MCP tab → Re-sync all health data to AI（应用 1.2.8 及更早版本：Settings → Data & AI）可加快这一过程。

无需 iPhone 即可试用

uvx vaultbeat-apple-health@latest --demo doctor
uvx vaultbeat-apple-health@latest --demo serve --transport stdio   # wire this into a client

--demo 是一个全局标志——必须放在子命令之前——并提供固定的合成数据集：无需配对、云端或密钥。每项结果都会标明 demo_mode: true，并带有 [SYNTHETIC DEMO DATA] 标记；写入工具 log_* 会拒绝执行。

MCP 工具

共有 29 个工具。读取操作返回你自己的数据——即与此设备配对的账户数据。标记为 partner 的工具还可通过 partner=true 读取伴侣选择在其应用中与你分享的数据——睡眠、饮水和体重；只有在对方开启分享后，才会包括月经周期、症状、心情和备注。两人的数据绝不会混在同一项结果中。每个读取工具都接受 fresh=true，用于跳过本地缓存。

诊断

工具	功能
vaultbeat_doctor	对此安装进行端到端诊断，报告哪些数据类型没有数据及可能的原因，并显示配对状态。在告知任何人其数据缺失之前，应先调用此工具。

健康记录

工具	返回内容
get_sleep_nights partner	每晚以一行紧凑数据展示：上床和起床时间、睡眠时长、深睡 / REM / 核心睡眠 / 清醒时长、醒来次数、最长连续睡眠时长、睡眠期间的心率和呼吸频率，以及小睡。一年数据可在一次调用中获取；使用 since="YYYY-MM-DD" 指定日历时间范围。
get_sleep_detail partner	深入查看一到两晚的数据：各睡眠阶段的时间段，以及每个阶段的心率和呼吸频率。可查询最近几晚，或按日期查询任意一晚（since / until）。
get_menstrual_cycle partner	月经周期样本和下一次经期预测。敏感信息。
get_symptoms partner	Apple Health 中的症状，以及个人报告的症状发作记录（类型、严重程度、开始和结束时间、地点、疑似诱因）。敏感信息。
get_state_of_mind partner	心情——Apple Health 的「心理状态」数据：每种感受的愉悦程度（效价和 Apple 的七个区域）、Apple 的感受词和生活领域，数据来源包括 Watch、健康 App 或其他 App，以及由 AI 记录的数据；按天统计数量和平均值。默认返回最新的 100 条，也可通过 since / until 查询较早数据。敏感信息。
get_notes partner	按天记录的自由文本备注，并标明记录者。敏感信息。
get_strength_log	力量训练课程：运动、组数 × 次数、每次训练的训练量。
get_food_log	按天记录的餐食和食物，可选包含 kcal / 蛋白质 / 脂肪 / 碳水化合物。默认返回有记录的最近 14 天（并非日历上的两周），也可通过 since / until 查询指定范围。
get_workouts	训练：类型、时长、卡路里、距离。
get_user_profile	性别、年龄、出生日期和身高。需要 Vaultbeat for iOS 1.2.9 或更高版本。

每日数值与分析

工具	返回内容
get_metric partner	获取一个、多个或全部系列的每日数值：睡眠时长、时间和阶段、静息 HR、HRV、腕部温度、VO₂ max、体重和身体成分、饮水量、步数、活动 / 基础 / 总能量、锻炼和站立时长、距离、正念。aggregation（avg / sum / min / max / latest）和 granularity（day / week / month / weekday）由服务端计算；使用 since / until 指定日历时间范围。对于持续累积的系列，今天的数据会标记为部分数据，并从聚合计算中排除。
get_intraday	获取一天内的样本。对于 HRV，按有样本的每小时返回一行（granularity="hourly"），或按每个样本返回一行（"raw"）。每天约 8–14 行；limit 按行数计算。
list_metric_series partner	列出上方和下方工具接受的所有系列名称，并附上单位及其数据量。
get_metric_trend partner	最小二乘斜率、端点、平均值 / 中位数 / 最小值 / 最大值。
compare_metric_periods partner	比较最近 N 天与之前的 N 天，或比较两个指定时间范围。
correlate_metric_series partner	计算两个系列在都有数据的日期上的 Pearson r；lag_days 用于将某一天与之后的某一天配对。
分析工具仅返回数字——不提供分数、评级或判定；如果只有两个点，也会拒绝拟合直线。

写入——所有数据都写入与此设备配对的账户，不会写入其他任何地方。

工具	功能
log_food_append / log_strength_append / log_note_append	添加到某一天。无法删除任何内容——当某天可能已有记录时，这是安全的默认选项。
log_food_entry / log_strength_entry / log_note	用传入的内容替换整天的记录，并准确报告删除了哪些内容。
log_weight_entry	记录一次称重，同时保留当天的身体成分数据。
log_symptom	将用户报告的一项症状记录为结构化字段，后续读取时可据此与睡眠、饮食和心率进行匹配。
update_symptom / delete_symptom	修改已报告的症状（通常是结束时间），或删除误记的症状。
log_state_of_mind	按照 Apple Health 的心理状态词汇（情绪效价、感受词、生活领域）记录用户自述的感受。只有在用户启用了“允许 AI 更新 Apple Health”（iOS app 1.3.0 或更高版本）时，其 iPhone 才会将记录写入 Apple Health。
delete_state_of_mind	删除 AI 误记的心情记录；iPhone 也会移除写入 Apple Health 的副本。

log_note 和 log_note_append 接受 partner=true，用于记录关于伴侣的笔记。笔记会保留在你自己的账户中，不会发送给对方，并且会与你自己的笔记分开保存。

读取结果

• 每次读取都会包含一个 coverage 区块。 days_covered 表示结果所依据的不同天数——引用任何平均值或趋势时，请一并注明。more_available: true 表示存在更早的记录，而你的 limit 未能覆盖这些记录（oldest_available 会说明最早可追溯到何时）；这绝不表示数据缺失。
• 结果大小有限制。 如果结果超过约 60 KB，就不会发送；工具会返回 result_too_large，并建议缩小请求范围（减小 limit、指定 since 日期，或只请求一个序列而非全部序列）。get_metric 和 get_intraday 会将行作为紧凑表格（columns + rows）返回。
• 不接受未知参数。 拼写错误或已弃用的参数会导致错误，绝不会被静默忽略。

MCP 提示词

该服务还会通过 prompts/list 提供八个提示词——daily_brief、sleep_review、energy_balance、training_block_review、cycle_aware_read、partner_check_in、log_from_conversation 和 why_is_this_empty。每个提示词都会列出要调用的工具，并包含相同的两条规则：下结论前说明数据覆盖范围；将空结果视为需要解释的情况（空结果可能有多种原因），绝不能将其视为零。所有参数均为可选项。

隐私与安全

• 仅在此设备上解密。 云端保存的是密文和按接收方封装的密钥；配对时会在此设备上生成用于解密的私钥。
• 健康数据只会通过 MCP 离开此软件包。 命令行子命令用于配对设备、报告配对状态并启动服务；这些子命令都不会输出健康数据。
• 敏感类别。 只有在 iOS app 中按类别启用后，你的月经周期数据和 Apple Health 记录的症状才会传到此服务；这些类别默认关闭。你自己的笔记、心情（来自 Apple Health 和 log_state_of_mind 的心理状态记录）以及你自行报告的症状（在 app 中或通过 log_symptom 记录）始终可由你自己的 Agent 读取。除非你启用与伴侣共享，否则这些内容都不会传到伴侣的 Agent。
• 可随时取消配对：在 app 的 MCP 标签页中操作（app 1.2.8 及更早版本：Settings → Data & AI）；之后，该设备将无法解密任何新数据。
• 工具结果中绝不会包含私钥或服务令牌。

私钥存放位置

不在 config.json 中。查找顺序如下：

1. 如果已设置 VAULTBEAT_PRIVATE_KEY 环境变量，则从中读取（只读，不会写回）——适用于从密钥存储注入密钥的运维人员；
2. 系统密钥环——桌面环境下的常见情况；
3. ~/.tether/mcp-local/identity.key，权限模式为 0600——在没有密钥环的机器上自动使用的备用方案。

~/.tether/mcp-local/config.json（权限模式为 0600）保存云端签发的服务令牌和你的公钥。.tether 是该应用的旧名称，并且特意保留此路径：现有安装会通过它找到密钥。

**切勿删除 config.json 来“清理环境”。**私钥不在其中，因此删除它无法清除有问题的密钥，反而会创建新的身份，导致所有已加密给旧身份的记录永久无法读取。要修复配对，请重新运行 bind：它会在当前机器上重新配对，并保留已为该机器加密的内容。

**无头服务器。**如果无法访问密钥环，请使用 identity.key 备用方案——它会自动启用。不要将 PYTHON_KEYRING_BACKEND 设置为 null 后端：它会接受写入却不存储任何内容，因此只会隐藏一个你可能能够访问的密钥环。如果存在 D-Bus 会话，但此进程无法看到它（服务器由 Agent 框架、systemd 或 cron 启动时很常见），请显式传入 DBUS_SESSION_BUS_ADDRESS——先解析其值（echo "unix:path=/run/user/$(id -u)/bus"），再将解析出的字面值放入客户端的 env 块中，因为该块是 JSON，而不是 shell。

遥测

服务器会向 PostHog（欧盟）发送使用事件：调用了哪个工具、是否成功、耗时范围，以及 AI 客户端和软件包版本——这些信息会关联到此机器所配对的账户。工具参数、结果和健康数据绝不会发送。设置 VAULTBEAT_TELEMETRY=0（或 DO_NOT_TRACK=1）即可关闭遥测。详情：vaultbeat.app/privacy。

故障排查

先运行 doctor。uvx vaultbeat-apple-health@latest doctor 会输出带有修复建议的 [OK] / [FAIL] 列表，指出第一个故障项；doctor --json 会为 Agent 输出相同的报告。退出代码为 0 表示运行正常。

**读取结果不完整或为空。**先查看 coverage.more_available：true 表示已达到 limit 边界——请请求更多数据。若为 false 且历史记录较短，则可能是 Requirements 中所述的套餐限制，或配对仍在同步数据。vaultbeat_doctor 会列出没有数据的数据类型及其可能原因。

二维码显示异常（乱码或行距不均——通常是 Windows 使用了非 UTF-8 代码页）。配对仍在等待中，因此不要重新运行 bind：这样会替换屏幕上的二维码。请将二维码上方打印的 JSON 载荷渲染为图像（qrencode -o pair.png '<payload>'），发送到手机，并在应用的扫描器中选择从照片导入；或者在新的终端中运行 chcp 65001；也可以运行 bind --no-qr，以文本形式显示载荷。

**读取失败并显示访问权限提示。**试用期或 Pro 会员资格已过期。没有任何数据被删除；在 iOS 应用中购买 Pro（设置 → 会员资格）即可恢复此机器的访问权限，无需重新配对。

HTTP 传输

对于通过网络连接，而不是启动子进程的客户端：

vaultbeat-apple-health serve --generate-token            # mint and store a bearer token, print client config
vaultbeat-apple-health serve --transport http            # 127.0.0.1:8000/mcp, bearer token required

令牌从 VAULTBEAT_MCP_HTTP_TOKEN（优先使用，可避免将令牌留在 shell 历史记录中）或已保存的配置中读取，客户端通过 Authorization: Bearer <token> 发送令牌。--show-token 会打印已保存的令牌。--no-token 会在回环地址上提供无需身份验证的服务。

绑定到回环地址之外（在 LAN 或 VPS 上使用 --host 0.0.0.0）时会默认拒绝启动：必须同时提供令牌和 --allow-remote。令牌以明文形式通过网络传输，因此请在其前面配置 TLS（Caddy、nginx、Cloudflare）。其他标志：--sse-response 用于 SSE 风格的响应；--stateful-http 用于需要会话的客户端。

mcp.json 示例（VS Code / Cursor 风格）：

{
  "servers": {
    "vaultbeat-health": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

仅支持 stdio 的客户端可以通过 mcp-remote 连接到 HTTP 服务：npx -y mcp-remote http://127.0.0.1:8000/mcp --header "Authorization: Bearer <token>"。

报告问题

本仓库同时受理 MCP 服务和 Vaultbeat iPhone 应用的问题 — 包括安装失败、工具错误、绑定始终无法完成、doctor 报告异常，以及应用问题（UI、订阅、HealthKit 权限提示、同步内容未显示在手机上）。 提交问题 并选择合适的模板。问题和想法可以发布到 讨论区。

这是一个公开仓库：切勿粘贴健康数据、配对码或账户详细信息。

开发

命令行包含六个子命令，它们都不会读取健康数据：

vaultbeat-apple-health bind      # pair this machine with the iOS app (QR)
vaultbeat-apple-health status    # local pairing state
vaultbeat-apple-health doctor    # self-diagnosis
vaultbeat-apple-health init      # generate a keypair and config without pairing
vaultbeat-apple-health poll      # poll once for a pending pairing
vaultbeat-apple-health serve     # run the MCP server (stdio or http)

解密后的记录按数据类型缓存在 ~/.tether/mcp-local/cache/ 下（文件权限为 0600，目录权限为 0700），缓存 600 秒；VAULTBEAT_MCP_CACHE_TTL 可以覆盖该设置（设为 0 可禁用缓存）。首次读取后，刷新时只会下载已更改的记录。配对到不同的服务身份时会清除缓存。

从克隆的仓库运行检查：

uv sync --frozen --all-extras
uv run --frozen pytest -q tests
uv run --frozen ruff check src tests
uv run --frozen mypy src

对于在软件包更名为 vaultbeat-apple-health（0.6.2）之前安装的用户，vaultbeat-mcp 和 vaultbeat-mcp-local 仍保留为控制台脚本别名。