内容
# 健康镜像 MCP
**English** · [简体中文](./README.zh.md)
一个本地的 [MCP](https://modelcontextprotocol.io) 服务器，暴露您自己的 Apple 健康数据 — 由 **健康镜像** iOS 应用导出到 iCloud Drive — 给在您的 Mac 上运行的 AI 工具（例如 Claude）。
它读取健康镜像写入到其 iCloud 容器的 JSONL 文件，并回答结构化查询（睡眠、心率指标、锻炼、每日恢复摘要）。您的健康数据不会离开您的机器：服务器在本地运行，没有网络访问权限，并且只向您连接的 MCP 客户端返回查询结果。
- **iOS 应用：** [健康镜像：自动同步 - App Store](https://apps.apple.com/app/id6779814305)
- **隐私政策：** [English](./PRIVACY.md) · [简体中文](./PRIVACY.zh.md)
- **支持：** [English](./SUPPORT.md) · [简体中文](./SUPPORT.zh.md)
## 工作原理
```
iPhone HealthKit
↓ 健康镜像 iOS 应用 （读取 HealthKit，写入 JSONL）
iCloud Drive 容器： iCloud.com.mlyz.HealthBridge
↓ macOS iCloud 自动同步
~/Library/Mobile Documents/iCloud~com~mlyz~HealthBridge/Documents/
↓ 此 MCP 服务器 （读取 JSONL，运行查询）
Claude / 任意 MCP 客户端
```
服务器对您的数据是只读的，并且不进行任何网络请求（通过沙盒配置文件强制执行 - 参见[安全模型](#安全模型)）。
## 要求
- macOS（Apple Silicon 或 Intel）。
- 在您的 iPhone 上安装 [**健康镜像**](https://apps.apple.com/app/id6779814305) 应用，并启用 iCloud 同步，以便健康数据同步到此 Mac。没有应用就没有数据可读。
- [uv](https://docs.astral.sh/uv/) — `brew install uv`。
- Python ≥ 3.12（uv 可以为您安装）。
## 安装
```bash
git clone https://github.com/mlyxz/healthmirror-mcp.git
cd healthmirror-mcp
uv sync
```
确认您的健康数据已实际同步到此 Mac — 此文件夹应存在并包含每个指标的子文件夹：
```bash
ls ~/Library/Mobile\ Documents/iCloud~com~mlyz~HealthBridge/Documents/raw/
```
如果它丢失或为空，请在 iPhone 上打开健康镜像应用，让它完成同步，并确保在 Mac 上启用了 iCloud Drive。
### 烟雾测试（无沙盒）
确认依赖项已解析并且服务器已启动：
```bash
uv run health-bridge-mcp
```
它通过 stdio 使用 MCP 协议，并且等待客户端，因此您将看不到可见的输出。如果它在没有导入错误的情况下启动，您就可以了 — 按 Ctrl+C 退出。
## 注册到 Claude（推荐：沙盒）
存储库自带 `run-sandboxed.sh`，它在 macOS `sandbox-exec` 配置文件中启动服务器，该文件**拒绝所有网络访问**并限制写入到一个小允许列表。这是推荐的运行方式。
```bash
claude mcp add healthmirror /ABSOLUTE/PATH/TO/healthmirror-mcp/run-sandboxed.sh
```
将 `/ABSOLUTE/PATH/TO/healthmirror-mcp` 替换为存储库的实际克隆路径。包装器自动解析您的主目录和存储库位置，因此您不必在 `sandbox.sb` 中编辑绝对路径。
要在**没有**沙盒的情况下运行（例如，在调试时），注册普通命令：
```bash
claude mcp add healthmirror -- uv run --directory /ABSOLUTE/PATH/TO/healthmirror-mcp health-bridge-mcp
```
其他 MCP 客户端：启动 `run-sandboxed.sh` 作为服务器命令；它通过 stdio 进行通信。
> **`uv: command not found`？** GUI 启动的 MCP 客户端有时不会继承您的 shell `PATH`。`run-sandboxed.sh` 尝试自动查找常用安装位置；如果仍然失败，请运行 `which uv` 并使用该完整路径。对于 **Claude Desktop**，请将其 MCP 配置 JSON 指向 `"command": "/ABSOLUTE/PATH/TO/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` 它）。有关[安全模型](#安全模型)的详细信息，请参阅它记录的内容。
## 安全模型
- **无网络。** 沙盒配置文件拒绝所有网络访问；服务器无法泄露数据。这是主要的保护措施。
- **写入是允许的。** 只有健康镜像应用支持目录、存储库的虚拟环境/字节码缓存和 Python 临时目录是可写的。
- **读取不受沙盒限制**（macOS 需要广泛的读取权限才能加载），但服务器代码只读取您本地的健康镜像数据 — 而且由于网络被阻止，读取操作无法进行任何操作。
- **审计日志。** 每个调用都会将工具名称、参数和结果摘要追加到本地日志 — 结果计数和几个派生数字（例如，每日恢复分数），但绝不会是原始健康样本。
`sandbox-exec` 被 Apple 标记为已弃用，但在当前的 macOS 上仍然功能正常。
## 为什么有两个名称？
产品和此存储库名为 **健康镜像**。Python 包和模块保留原始的开发代号 **`health_bridge`**（发行版 `health-bridge-mcp`，导入 `health_bridge_mcp`），而 iCloud 容器 ID 为 `iCloud.com.mlyz.HealthBridge`。这些标识符在早期被冻结，以避免破坏正常运行的数据管道，因此它们故意与产品名称不同。实际上，它都是同一个项目。
## 维护者
由 Xiao Zhang 开发，在 GitHub 上发布为 [@mlyxz](https://github.com/mlyxz)。联系方式：support@mlyz.me
## 许可证
[MIT](./LICENSE)
