healthmirror-mcp

HealthMirror MCP

English · 简体中文

一个跑在本地的 MCP server，把 HealthMirror iOS app 同步到 iCloud 的 Apple Health 数据，开放给你 Mac 上的 AI 工具（比如 Claude）查询。

HealthMirror app 会把健康数据写成 JSONL 放进 iCloud 容器；这个 server 就读这些文件，回答结构化的查询——睡眠、心率类指标、运动、每日恢复摘要。整个过程数据不出本机：server 只在本地跑、不联网，只把查询结果交给你接上的那个 MCP 客户端。

• iOS app： App Store 上的 HealthMirror: Auto Sync
• 隐私政策： English · 简体中文
• 使用支持： English · 简体中文

数据是怎么流的

iPhone HealthKit
  ↓  HealthMirror iOS app   （读 HealthKit，写成 JSONL）
iCloud 容器：  iCloud.com.mlyz.HealthBridge
  ↓  macOS 自动同步
~/Library/Mobile Documents/iCloud~com~mlyz~HealthBridge/Documents/
  ↓  这个 MCP server         （读 JSONL，跑查询）
Claude / 任意 MCP 客户端

server 对你的数据只读，也不会主动联网（由 sandbox 配置兜底，见安全设计）。

开始之前

• 一台 macOS（Apple 芯片或 Intel 都行）。
• iPhone 上装好 HealthMirror app 并开了 iCloud 同步——这样健康数据才会同步到这台 Mac，没有 app 就没有数据可读。
• uv：brew install uv。
• Python ≥ 3.12（没装的话 uv 会帮你装）。

安装

git clone https://github.com/mlyxz/healthmirror-mcp.git
cd healthmirror-mcp
uv sync

确认数据真的同步到这台 Mac 了——下面这个目录应该存在，里面有按指标分的子目录：

ls ~/Library/Mobile\ Documents/iCloud~com~mlyz~HealthBridge/Documents/raw/

要是这个目录不在、或者是空的，打开 iPhone 上的 HealthMirror app 等它同步完，再确认这台 Mac 开着 iCloud Drive。

先裸跑一下（不带 sandbox）

确认依赖都装好了、server 能起来：

uv run health-bridge-mcp

它走 stdio、按 MCP 协议等客户端连进来，所以屏幕上不会有任何输出——只要没报 import 错误就说明没问题，按 Ctrl+C 退出就行。

接入 Claude（推荐带 sandbox）

仓库里带了 run-sandboxed.sh，它会把 server 套进一层 macOS sandbox-exec：完全禁网，能写的地方也只放行一个很小的白名单。推荐用这种方式跑。

claude mcp add healthmirror /你克隆仓库的绝对路径/healthmirror-mcp/run-sandboxed.sh

把前面那段换成你实际克隆下来的路径就行。脚本会自己算出你的 home 目录和仓库位置，所以你不用去动 sandbox.sb 里的任何路径。

如果想不带 sandbox 跑（比如调试的时候），就注册裸命令：

claude mcp add healthmirror -- uv run --directory /你克隆仓库的绝对路径/healthmirror-mcp health-bridge-mcp

用别的 MCP 客户端：把 run-sandboxed.sh 当成 server 启动命令就行，它走 stdio 通信。

碰到 uv: command not found？ 从图形界面启动的 MCP 客户端，有时拿不到你 shell 里的 PATH。run-sandboxed.sh 会自动找几个常见的安装位置；要还是不行，跑一下 which uv 拿到完整路径。Claude Desktop 用户：在它的 MCP 配置 JSON 里，把 "command" 指到 "/绝对路径/healthmirror-mcp/run-sandboxed.sh"。

有哪些工具

工具	干什么
ping	测连接通不通。
get_sleep	睡眠片段（主睡眠 + 小睡）、各阶段时长、数据覆盖情况。
get_metric	查某个数值指标（heart_rate、hrv_sdnn、resting_heart_rate、active_energy、steps、weight），支持聚合、可按天分桶、可按数据来源拆开看。
get_workouts	运动记录（多来源自动去重），外加按类型的汇总。
get_daily_summary	一次性给出当天摘要：恢复评分、周期阶段、当天活动、昨晚睡眠。

查询默认只看最近 30 天，要查更早的就传 allow_historical=true。每次调用都会往 ~/Library/Application Support/HealthBridge/audit.log 追加一行，方便你回头看 AI 都查了什么（tail -f 一下就行）。具体记了哪些内容，见安全设计。

安全设计

• 不联网。 sandbox 把网络整个掐掉，server 没法把数据发出去——这是最关键的一道防线。
• 写入只放行白名单。 只有 HealthMirror 的 app-support 目录、你克隆下来这个仓库自己的 venv / 字节码缓存、以及 Python 临时目录是可写的。
• 读取不受 sandbox 限制（macOS 加载程序本身要用大范围读权限），但 server 代码只会去读你本地的 HealthMirror 数据；何况网都断了，读到也送不出去。
• 审计日志。 每次调用往本地日志追加：工具名、参数、再加一小段结果摘要——也就是结果条数和个别派生值（比如当天的恢复评分），绝不写原始的健康数据本身。

sandbox-exec 被 Apple 标成了 deprecated，但在当前 macOS 上照样能用。

为什么是两个名字

产品和这个仓库都叫 HealthMirror，但 Python 包和模块沿用了开发期的老代号 health_bridge（发行名 health-bridge-mcp、import 名 health_bridge_mcp），iCloud 容器 ID 也还是 iCloud.com.mlyz.HealthBridge。这些标识符很早就定死了，改名会打断一条一直在跑的数据管道，所以故意没跟产品名保持一致——本质上是同一个项目。

维护者

由 Xiao Zhang 开发，在 GitHub 上以 @mlyxz 发布。 联系方式：support@mlyz.me

许可证

MIT

This site is open source. Improve this page.