内容
# 健康导出MCP — 面向AI代理的苹果健康数据MCP服务器
**通过Claude、ChatGPT、Cursor、OpenClaw、Hermes等任意AI代理查询您的苹果健康数据。**
`health-export-mcp`是一个开源的、**零依赖**的[模型上下文协议（MCP）](https://modelcontextprotocol.io)服务器，允许任何兼容MCP的AI代理查询您的**苹果健康/HealthKit**数据 — **190个指标**，以干净的JSON格式呈现，采用纯文本语言。本地优先，只读，无需账号，也无需开发人员服务器介入。该服务器是[健康导出AI](https://www.healthexport.dev) iOS应用的开源服务器。
<p align="center">
<img alt="MCP" src="https://img.shields.io/badge/Model_Context_Protocol-server-6E56CF" />
<img alt="zero dependencies" src="https://img.shields.io/badge/dependencies-0-2ea44f" />
<img alt="Node ≥18" src="https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white" />
<img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue" />
<img alt="works with Claude, Cursor, ChatGPT, OpenClaw, Hermes" src="https://img.shields.io/badge/works_with-Claude_·_Cursor_·_ChatGPT_·_OpenClaw_·_Hermes-111" />
</p>
<p align="center">
<img src="assets/architecture.svg" alt="苹果健康数据导出到iCloud、文件夹或局域网；health-export-mcp读取并为AI代理提供7种查询工具" width="100%" />
</p>
> 询问您的代理： *"比较这周和上周我的心率变异性（HRV），告诉我是否正在恢复。"* — 它将调用工具并根据您的**实际数据**回答。
---
## 什么是health-export-mcp？
它是一个MCP服务器，将您的苹果健康数据导出转换为您的AI代理可以查询的工具，采用自然语言 — HRV、睡眠、静息心率、步数、锻炼、VO₂ max等180多个指标。
- **适用人群：** 任何希望其AI基于**真实**健康数据而非过时的CSV进行推理的人。
- **它不是什么：** 云服务。没有开发人员服务器介入 — 您的数据只会前往您**指定**的地方。
- **设置：** 将服务器指向您的导出数据，并将其添加到您的AI客户端。
> **无需iPhone即可试用：** `git clone https://github.com/PhilipAD/health-export-mcp.git && cd health-export-mcp && npm test` 将写入14天的样本缓存并测试每个工具。
---
## 连接苹果健康数据到您的AI代理 — 快速入门
### 1. 获取您的苹果健康数据流动
配套iOS应用 **[健康导出AI](https://www.healthexport.dev)** 导出您的苹果健康数据 — 只读、自动、私有。对于这个MCP服务器，请导出到它可以读取的目的地：
| 目的地 | 备注 |
|---|---|
| **iCloud Drive** （默认） | 您的Mac会自动读取同步的文件夹 |
| **本地文件夹** | 任何同步到您的Mac的文件夹（Dropbox、Google Drive、OneDrive等） |
| **局域网** （HTTP / WebSocket） | 直接推送到服务器 — 在Tailscale上效果很好 |
> 使用非MCP工具（ChatGPT、n8n、Home Assistant）？该应用还可以将数据**POST**到工具可以直接读取的** webhook** — 请参见[兼容性](#works-with-claude-cursor-chatgpt-openclaw-hermes)。
### 2. 将服务器添加到您的代理
**最快捷 — 自动配置：**
```bash
git clone https://github.com/PhilipAD/health-export-mcp.git
cd health-export-mcp
node apply-mcp-config.mjs # 自动检测已安装的客户端并为您编写配置
```
**手动 — Claude Desktop** （`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"health-export": {
"command": "node",
"args": ["REPLACE_WITH_ABSOLUTE_PATH/server.mjs"],
"env": { "HEALTH_DATA_DIR": "~/Library/Mobile Documents/iCloud~ai~healthexport~app/Documents" }
}
}
}
```
> 获取绝对路径以粘贴到上面： `node -e "console.log(process.cwd()+'/server.mjs')"` （在存储库内运行）。
> 或完全跳过JSON — 将 **`health-export.mcpb`** 拖到 **Claude Desktop → 设置 → 扩展**。
**Cursor / VS Code：** `node gen-deeplinks.mjs` 打印一键安装链接。
**opencode / OpenClaw / Hermes：** 请参阅 **[AGENTS.md](AGENTS.md)** 获取确切的代码块 — 形状相同，每个客户端一个。
### 3. 询问您的代理
重启客户端并尝试：
> *"使用health-export：这周我的平均HRV是多少，相比上周？"*
---
## 兼容Claude、Cursor、ChatGPT、OpenClaw、Hermes
| 客户端 / 代理 | 集成 | 方法 |
|---|---|---|
| **Claude Desktop** | 原生MCP | `.mcpb` 包，或 `mcpServers` 代码块 |
| **Cursor** | 原生MCP | 一键深链接，或 `~/.cursor/mcp.json` |
| **opencode** | 原生MCP | `opencode.json` `mcp` 代码块 |
| **OpenClaw** | 原生MCP | 将服务器代码块添加到您的MCP配置中 |
| **Hermes** | 原生MCP | 将服务器代码块添加到您的代理的MCP配置中 |
| **VS Code** （Copilot / Continue） | 原生MCP | 一键深链接 |
| **ChatGPT · Gemini · Grok** | Webhook* | 消费应用的webhook导出 |
| **n8n · Home Assistant** | Webhook* | 在导出的JSON上触发自动化 |
<sub>*MCP客户端直接通过stdio查询此服务器。ChatGPT / Gemini / Grok / n8n / Home Assistant不支持MCP — 它们通过iOS应用的基于令牌身份验证的**webhook**导出消费相同的数据。</sub>
---
## 7种MCP工具
| 工具 | 功能 |
|---|---|
| `get_mcp_status` | 健康检查 — 来源、指标/锻炼次数、最新数据日期。 **请先调用此工具。** |
| `list_metrics` | 每个可用指标及其单位、日期计数和日期范围。 |
| `get_health_metrics` | 指定日期范围内的每日指标值（或所有指标）+聚合值（平均值/总和/最小值/最大值/最新值）。 |
| `get_trends` | 最近N天窗口与前N天窗口的比较 — 变化、百分比变化、方向。 |
| `compare_periods` | 两个任意日期范围内的指标比较（A vs B）。 |
| `get_structured_export` | 指定指标/范围的干净JSON — 直接放入上下文。 |
| `query_health_data` | 自然语言便利功能： *"上个月的平均HRV是多少？"* → 路由结构化结果。 |
**覆盖范围：** 190个苹果健康指标，涵盖活动、心率、HRV、移动性、呼吸、身体、睡眠、听力、营养等 — 另加锻炼。
---
## 示例AI查询
```text
"最近30天我的静息心率变化如何？"
"比较这周和上周我的深度睡眠。"
"这个季度我的VO₂ max是上升还是下降？"
"给我最近14天的HRV、RHR和睡眠的干净JSON导出。"
"将我的步数与这个月的睡眠时长关联起来。"
```
---
## 用例
- **AI健康教练** — 让代理根据您的实际HRV、静息心率和睡眠数据进行推理，建议何时推动和何时恢复，基于您的实际数据而非通用建议。
- **训练负荷分析** — 拉取锻炼、VO₂ max和心率趋势，以便代理可以标记过度劳累、绘制健身进展和安排训练模块。
- **睡眠关联** — 让代理将深度睡眠时长与步数、咖啡因、晚间锻炼或屏幕时间关联起来，以找出真正影响睡眠质量的因素。
- **量化自我仪表盘** — 将任意指标集和日期范围的干净JSON数据直接馈入笔记本、电子表格或LLM构建的仪表盘，用于自我跟踪。
- **个人研究和实验** — 运行n-of-1实验（补充剂、例行程序或协议更改），让代理比较前后两个时段的190个指标，看看发生了什么变化。
---
## 为其提供数据的应用
<p align="center">
<img src="assets/screenshot-dashboard.png" alt="健康导出AI仪表盘" width="240" />
<img src="assets/screenshot-metrics.png" alt="190个苹果健康指标" width="240" />
<img src="assets/screenshot-destinations.png" alt="导出到iCloud、文件夹、局域网或webhook" width="240" />
</p>
<p align="center"><sub><a href="https://www.healthexport.dev">健康导出AI</a> — 自动将您的苹果健康数据导出到您的代理。</sub></p>
---
## 隐私和安全
- **只读。** 服务器仅读取导出的数据 — 它从不触及HealthKit，也不写回。
- **本地优先。** 它通过stdio在您的机器上运行。 **没有开发人员服务器** 介入。
- **可选配对。** 将 `PAIRING_SECRET` 设置为iOS应用显示的代码（设置 → 代理配对），以便访问权限。
- **可审计。** 零依赖和几百行可读的JavaScript — 请阅读每一行。
- **签名发布。** 主机上的工件使用minisign签名并进行校验和 — 请参见 [验证发布](#verifying-releases)。
---
## 验证发布
托管在 `healthexport.dev/mcp/` （由 [设置技能](https://healthexport.dev/SKILL.md) 使用）的服务器工件是 **minisign-signed** 的，并且每个下载都是 **SHA-256 checksummed** 的。签名公钥在此存储库中发布（`minisign.pub`）并在 `SKILL.md` 中发布 — **从此处获取，不要仅从网站获取**，以防止网站被篡改而同时替换工件和密钥。
```bash
PUBKEY='RWS6TxVWSKUblYkx7Db6ZpmvHALwHpznZpjaED/FlZj+PpxSlel0MxHZ' # = 此存储库中的minisign.pub
curl -fsSL https://healthexport.dev/mcp/SHA256SUMS -o SHA256SUMS
curl -fsSL https://healthexport.dev/mcp/SHA256SUMS.minisig -o SHA256SUMS.minisig
minisign -Vm SHA256SUMS -P "$PUBKEY" || { echo "签名无效 — 请勿运行"; exit 1; } # 失败关闭
curl -fsSL https://healthexport.dev/mcp/server.mjs -o server.mjs
shasum -a 256 --ignore-missing -c SHA256SUMS || { echo "校验和不匹配 — 请勿运行"; exit 1; }
```
上述经过校验和验证的下载是锁定路径。 `npx health-export-mcp` 相反会在运行时解析发布到npm的最新版本（npm提供其自己的包完整性）。完整的安全性概述： <https://healthexport.dev/security>。将漏洞报告给 **security@healthexport.dev**。
---
## 要求
- **Node.js ≥ 18** （`node -v`）。
- 包含由[健康导出AI](https://www.healthexport.dev)导出的 `.health-cache.json` 的文件夹 — 或运行 `npm test` 生成样本。
- 兼容MCP的客户端（Claude Desktop、Cursor、opencode、OpenClaw、Hermes、VS Code） — 或任何可以读取webhook导出的工具。
---
## 常见问题
**如何将我的苹果健康数据导入Claude / ChatGPT / 我的AI代理？**
安装 `health-export-mcp`，使用[健康导出AI](https://www.healthexport.dev) iOS应用导出您的苹果健康数据（到iCloud、文件夹或局域网），然后将MCP服务器添加到您的AI客户端。您的代理可以以自然语言查询您的苹果健康指标。（非MCP工具如ChatGPT直接读取应用的webhook导出。）
**我的健康数据是否发送到服务器？**
不会发送到我们的服务器。MCP服务器在本地运行，仅读取您配置的导出文件或端点 — 没有开发人员服务器介入。您的iOS导出到达的位置（iCloud、您的局域网、webhook）完全由您选择。
**哪些代理受支持？**
任何MCP客户端 — Claude Desktop、Cursor、opencode、OpenClaw、Hermes、VS Code — 原生支持。ChatGPT、Gemini、Grok、n8n和Home Assistant通过webhook消费相同的数据。
**我需要iOS应用吗？**
该应用是获取苹果健康数据离开iPhone到此服务器读取的格式的最简单方法。您也可以将 `HEALTH_DATA_DIR` 指向包含兼容 `.health-cache.json` 的任何文件夹。
---
## 故障排除
- **"未找到指标"** — 确认 `HEALTH_DATA_DIR` 指向包含 `.health-cache.json` 的文件夹，并且应用至少导出过一次。运行 `get_mcp_status` 查看已解析的源和最新日期。
- **客户端中服务器不可见** — 使用 `server.mjs` 的**绝对**路径，确保Node ≥18，并完全重启客户端。
- **数据锁定错误** — 导出文件在重启后首次解锁之前受到保护；解锁设备一次。
---
## 在本地运行
```bash
# Node ≥18，无需安装
HEALTH_DATA_DIR=~/Library/Mobile\ Documents/iCloud~ai~healthexport~app/Documents node server.mjs
# 集成测试 — 写入14天的样本缓存并测试每个工具
npm test
```
stdio传输（换行分隔的JSON-RPC 2.0）— 通用MCP传输。可选设置 `HEALTH_LISTEN=1` 以在同一进程中接受来自iOS应用的局域网推送（请参见 [`receiver.mjs`](receiver.mjs)）。
---
## 工作原理
iOS应用读取苹果健康数据（只读）并写入紧凑的 `.health-cache.json` 到您选择的目的地。此服务器读取该文件并通过MCP公开上述7种工具。无需桥接、无需Docker、无需数据库 — 只有文件和stdio。
```
苹果健康 → 健康导出AI（iOS）→ .health-cache.json → health-export-mcp → MCP客户端 → 您
```
---
## 相关项目
其他苹果健康MCP服务器在生态系统中 — 根据您的设置值得一看：
- **[neiltron/apple-health-mcp](https://github.com/neiltron/apple-health-mcp)** — 一个MCP服务器，对苹果健康导出运行SQL风格的查询。
- **[the-momentum/apple-health-mcp-server](https://github.com/the-momentum/apple-health-mcp-server)** — 一个MCP服务器，用于分析从健康应用导出的苹果健康数据。
- **[HealthyApps/health-auto-export-mcp-server](https://github.com/HealthyApps/health-auto-export-mcp-server)** — 健康自动导出应用数据的MCP服务器。
**`health-export-mcp`的不同之处：** 零依赖、干净的结构化JSON、190个苹果健康指标以及最广泛的代理支持（Claude、Cursor、opencode、OpenClaw、Hermes、VS Code原生支持 — 以及通过webhook支持ChatGPT/Gemini/Grok/n8n/Home Assistant）。
---
## 相关
- **配套iOS应用：** [健康导出AI](https://www.healthexport.dev) — 自动将190个苹果健康指标导出到您的代理。
- **模型上下文协议：** [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **每个代理的设置：** [AGENTS.md](AGENTS.md)
如果这有助于您的设置，请⭐使其更容易被其他人发现。
## 许可证
MIT — 请参见 [LICENSE](LICENSE)。欢迎贡献。
<sub>苹果健康MCP服务器 · 将苹果健康数据导出到AI · HealthKit MCP服务器 · 使用Claude / ChatGPT / Cursor查询苹果健康数据 · 模型上下文协议健康服务器 · 苹果健康到LLM · HRV、睡眠和心率用于AI代理。</sub>
