apple-health-mcp

<!-- delx-wellness header v2 --> <h1 align="center">苹果健康MCP</h1> <div align="center"> <img src="assets/banner.png" alt="苹果健康MCP — 苹果健康MCP适用于AI代理" width="85%" /> </div> <h3 align="center"> 为您的AI代理提供苹果健康活动、睡眠、心率变异性和运动数据 — 来自本地的export.zip。<br> 本地优先的MCP服务器 — <strong>令牌从不离开您的机器</strong>。 </h3> <p align="center"> <a href="https://www.npmjs.com/package/apple-health-mcp-unofficial"><img src="https://img.shields.io/npm/v/apple-health-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white" alt="npm版本" /></a> <a href="https://www.npmjs.com/package/apple-health-mcp-unofficial"><img src="https://img.shields.io/npm/dm/apple-health-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white" alt="npm下载量" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A" alt="MIT许可证" /></a> <a href="https://wellness.delx.ai/connectors/apple-health"><img src="https://img.shields.io/badge/SITE-wellness.delx.ai-0EA5A3?style=for-the-badge&labelColor=0F172A" alt="站点" /></a> </p> <p align="center"> <a href="https://github.com/davidmosiah/apple-health-mcp/stargazers"><img src="https://img.shields.io/github/stars/davidmosiah/apple-health-mcp?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github" alt="GitHub星星" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A" alt="为MCP构建" /></a> <a href="https://github.com/davidmosiah/delx-wellness-hermes"><img src="https://img.shields.io/badge/HERMES-one--command_setup-10B981?style=for-the-badge&labelColor=0F172A" alt="Hermes一键设置" /></a> <a href="https://github.com/davidmosiah/delx-wellness"><img src="https://img.shields.io/badge/苹果健康-FA243C?style=for-the-badge&labelColor=0F172A&logoColor=white&logo=apple&logoColor=white" alt="苹果健康" /></a> </p> > ⚡ **一键安装** 使用 [Delx Wellness for Hermes](https://github.com/davidmosiah/delx-wellness-hermes)： > `npx -y delx-wellness-hermes setup` — 预配置此连接器和其他8个连接器在一个专用的Hermes配置文件中。 > > 或将其单独连接到Claude Desktop / Cursor / ChatGPT Desktop — 请参见下面的安装部分。 --- <!-- /delx-wellness header v2 --> **本地优先的MCP服务器，读取您的苹果健康导出并将其暴露给AI代理。** > **非官方项目。** 不隶属于、不由苹果公司支持或认可。苹果健康是苹果公司的商标。本软件读取您从苹果健康应用程序生成的导出。 > > **无实时HealthKit访问。** 此连接器读取`export.xml` / `export.zip`文件从您的iPhone导出。原生iOS HealthKit桥接是一个单独的未来组件。 由 [David Mosiah](https://github.com/davidmosiah) 为使用Claude、Cursor、Hermes、OpenClaw或其他MCP兼容代理来考虑长期健康和活动趋势的人构建 — 无需从健康应用程序复制粘贴数字。 [Delx Wellness](https://github.com/davidmosiah/delx-wellness)的一部分 — 一个本地优先的健康MCP连接器注册表。 > 如果此连接器有助于您的代理工作流，请给仓库加星。星星使项目更容易被其他AI构建者发现，并帮助Delx继续提供本地优先的健康基础设施。 ## 为什么存在 苹果健康是大多数人拥有的最完整的个人健康数据集 — 多年的活动、心率、睡眠、运动、身体测量，甚至心电图。但是，苹果不提供公共云API。数据存储在iPhone上的HealthKit中，今天唯一实用地下设备的方法是健康应用程序中的**健康导出**功能。 该软件包读取该导出 — 本地 — 无论是原始`export.xml`、解压文件夹还是`export.zip` — 并通过模型上下文协议暴露苹果健康。无需令牌、无需OAuth、无需云同步。导出从不离开您的机器。 ## 60秒设置 **1. 在iPhone上导出您的苹果健康数据：** ```text 健康应用程序 → 点击您的个人资料图片 → 导出所有健康数据 ``` 等待几分钟。通过AirDrop或将zip传输到此机器。 **2. 配置和验证：** ```bash npx -y apple-health-mcp-unofficial setup --export-path /path/to/export.zip npx -y apple-health-mcp-unofficial doctor ``` 或者让CLI在`Downloads`、`Desktop`或`Documents`中找到最新的本地导出，复制到托管的本地存储中，并保存该路径： ```bash npx -y apple-health-mcp-unofficial setup --auto-import ``` 支持的导出路径： - `/path/to/export.zip` - `/path/to/apple_health_export/` （解压文件夹） - `/path/to/export.xml` （原始导出文件） **保持新鲜 — 监视文件夹（无需macOS）：** 苹果健康是一种手动导出，因此通常的痛点是您停止重新运行设置后数据就会过时。将连接器指向您丢弃新导出的文件夹： ```bash npx -y apple-health-mcp-unofficial setup --watch-path /path/to/health-exports ``` 现在，每次您从iPhone导出并将新的`export.zip`（或`export.xml`，或解压的`apple_health_export/`）放入该文件夹时，连接器会自动将最新的导出文件提升为活动导出 — 在服务器启动时和运行时（通过文件系统事件）以及调用`apple_health_reimport`工具时 — 并刷新缓存的摘要。您还可以按需触发重新扫描。 然后将以下内容添加到您的MCP客户端配置中： ```json { "mcpServers": { "apple_health": { "command": "npx", "args": ["-y", "apple-health-mcp-unofficial"] } } } ``` 对于Claude Desktop，运行`setup --client claude --export-path /path/to/export.zip`，该代码段为您写入。 ## 与您的代理一起试用 首先询问三个问题： ```text 使用apple_health_connection_status检查设置，然后运行apple_health_daily_summary。 给我今天的5行健康简报。 ``` ```text 首先调用apple_health_data_inventory。有哪些苹果健康信号和日期范围 可用于此导出？ ``` ```text 调用apple_health_weekly_summary，响应格式为json。比较过去7天 的步数、睡眠、运动和心脏信号。 ``` ```text 使用apple_health_weekly_review提示，days=14。 查找最大的习惯模式并建议一个实验。 ``` ## 数据可用性 该软件包解析来自健康应用程序的苹果健康导出。当本README说`raw`时，它指的是上游XML记录字段 — 而不是原始HealthKit数据。 | 数据 | 可用 | 备注 | |---|:---:|---| | 活动（步数、距离、能量、运动） | ✓ | 标准`HKQuantityType`记录 | | 心率（静息+样本） | ✓ | 记录的心率样本和静息心率 | | 睡眠分析+睡眠阶段 | ✓ | 当iPhone/Watch记录睡眠时 | | 运动+运动元数据 | ✓ | 所有`HKWorkout`条目 | | 身体测量（体重、BMI、体脂） | ✓ | 当用户记录时 | | HRV（SDNN）+呼吸率 | ✓ | 当Watch支持时 | | 心电图记录 | ✓（元数据） | Apple Watch心电图事件；原始波形需要PDF导出 | | 实时HealthKit访问 | — | 苹果不提供公共实时API | | iCloud健康同步 | — | 导出文件不暴露 | ## 工具 **从这些开始：** - `apple_health_connection_status` — 在读取数据之前验证导出路径 - `apple_health_data_inventory` — 发现可用的记录类型、日期覆盖范围、来源数量和过时导出风险 - `apple_health_daily_summary` — 从导出数据中获取每日健康简报 - `apple_health_weekly_summary` — 每周比较和习惯信号 **诊断** - `apple_health_capabilities`, `apple_health_agent_manifest`, `apple_health_privacy_audit` **记录** - `apple_health_list_records` — 按`type`（例如`HKQuantityTypeIdentifierStepCount`）、`start`、`end`、`limit`限制记录 - `apple_health_list_workouts` — 有限的运动记录 **保持数据新鲜** - `apple_health_reimport` — 重新扫描监视文件夹（`APPLE_HEALTH_WATCH_PATH`）并提升最新的导出，刷新摘要；传递`check_only: true`以预览而不提升 ## 提示 - `apple_health_daily_review` — 具有非医学框架的每日健康回顾 - `apple_health_weekly_review` — 每周习惯信号和趋势比较 ## 资源 - `apple-health://capabilities`, `apple-health://agent-manifest` - `apple-health://inventory`, `apple-health://summary/daily`, `apple-health://summary/weekly` ## 隐私和安全 - 苹果健康导出是高度敏感的个人健康数据。请保持本地。 - 永远不要将`export.xml` / `export.zip`提交到GitHub，在聊天中粘贴原始导出或将它们上传到问题。 - 导出路径是只读的；MCP永远不会修改您的导出。 - `APPLE_HEALTH_PRIVACY_MODE`默认为此连接器的`summary`（比其他Delx Wellness连接器更保守），因为数据集丰富且敏感。在摘要模式下，低级列表工具返回聚合数据而不是单个记录。原始记录转储是按需开启的。 - **这不是医疗建议**。服务器公开您自己导出的数据，用于个人AI工作流，而不是用于诊断或紧急监控。 ## 配置 ```bash APPLE_HEALTH_EXPORT_PATH=/path/to/export.zip # 或export.xml或apple_health_export/ APPLE_HEALTH_PRIVACY_MODE=summary # summary | structured | raw APPLE_HEALTH_TIMEZONE=America/Fortaleza # 本地日摘要；默认为UTC，除非设置保存时区 APPLE_HEALTH_WATCH_PATH=/path/to/health-exports # 可选：自动重新导入最新的导出到此处 ``` `setup`将这些设置写入`~/.apple-health-mcp/config.json`，权限为`0600`。 `setup --auto-import`扫描常见的本地文件夹以获取最新的苹果健康导出，并将其复制到`~/.apple-health-mcp/exports/`，权限为`0600`。此操作在您将导出从iPhone传输后自动完成本地导入步骤。完全实时的HealthKit同步仍然需要一个单独的原生桥；此Node MCP故意只读取本地导出。 `setup --watch-path <dir>`（或`APPLE_HEALTH_WATCH_PATH`）使连接器将文件夹视为一个放置区。在启动时、在运行时（通过文件系统事件）和调用`apple_health_reimport`工具时，它会将找到的最新苹果健康导出文件 — `export.xml`、`export.zip`、`apple_health_export/`目录或任何`*apple*health*.zip` — 提升为活动导出，并清除快照和增量缓存，以便下一个摘要反映新数据。`apple_health_connection_status`报告监视文件夹状态，并在有新导出文件等待时发出警告。 ## Hermes / 远程设置 ```bash npx -y apple-health-mcp-unofficial setup --client hermes --export-path /path/to/export.zip npx -y apple-health-mcp-unofficial doctor --client hermes hermes mcp test apple_health ``` 在Hermes配置更改后，使用`/reload-mcp`或`hermes mcp test apple_health`。不要为正常导出访问重启网关。 如果Hermes服务器在与您的iPhone不同的机器上运行，请将导出文件传输到那里并指向 `--export-path`。导出文件应为 `chmod 600`。 ## 要求 - Node.js 20+ - 来自您的iPhone的苹果健康导出（健康应用程序 → 个人资料 → 导出所有健康数据） ## 开发 ```bash git clone https://github.com/davidmosiah/apple-health-mcp.git cd apple-health-mcp npm install npm test npm run build ``` 使用MCP检查器进行测试： ```bash npx @modelcontextprotocol/inspector node dist/index.js ``` 可选的本地HTTP传输： ```bash APPLE_HEALTH_MCP_TRANSPORT=http APPLE_HEALTH_MCP_PORT=3000 node dist/index.js curl http://127.0.0.1:3000/health ``` ## 链接 - npm： <https://www.npmjs.com/package/apple-health-mcp-unofficial> - 文档站点： <https://wellness.delx.ai/connectors/apple-health> - GitHub： <https://github.com/davidmosiah/apple-health-mcp> - Delx Wellness注册表： <https://github.com/davidmosiah/delx-wellness> - 连接器质量标准： <https://github.com/davidmosiah/delx-wellness/blob/main/docs/connector-quality-standard.md> - 苹果健康导出方法： <https://support.apple.com/guide/iphone/share-health-and-fitness-data-iph27f6325b2/ios> <!-- delx-wellness see-also --> ## 参见 完整的 [Delx Wellness](https://wellness.delx.ai) 连接器库： | 提供商 | 软件包 | 仓库 | |---|---|---| | WHOOP | [`whoop-mcp-unofficial`](https://www.npmjs.com/package/whoop-mcp-unofficial) | [whoop-mcp](https://github.com/davidmosiah/whoop-mcp) | | Oura | [`oura-mcp-unofficial`](https://www.npmjs.com/package/oura-mcp-unofficial) | [ouramcp](https://github.com/davidmosiah/ouramcp) | | Garmin | [`garmin-mcp-unofficial`](https://www.npmjs.com/package/garmin-mcp-unofficial) | [garminmcp](https://github.com/davidmosiah/garminmcp) | | Strava | [`strava-mcp-unofficial`](https://www.npmjs.com/package/strava-mcp-unofficial) | [strava-mcp](https://github.com/davidmosiah/strava-mcp) | | Fitbit | [`fitbit-mcp-unofficial`](https://www.npmjs.com/package/fitbit-mcp-unofficial) | [fitbitmcp](https://github.com/davidmosiah/fitbitmcp) | | Withings | [`withings-mcp-unofficial`](https://www.npmjs.com/package/withings-mcp-unofficial) | [withingsmcp](https://github.com/davidmosiah/withingsmcp) | | 苹果健康 | [`apple-health-mcp-unofficial`](https://www.npmjs.com/package/apple-health-mcp-unofficial) | [apple-health-mcp](https://github.com/davidmosiah/apple-health-mcp) | | Polar | [`polar-mcp-unofficial`](https://www.npmjs.com/package/polar-mcp-unofficial) | [polarmcp](https://github.com/davidmosiah/polarmcp) | | Nourish（营养） | [`wellness-nourish`](https://www.npmjs.com/package/wellness-nourish) | [wellness-nourish](https://github.com/davidmosiah/wellness-nourish) | **Hermes一键设置** — 预配置上述每个连接器以及健康技能+ onboarding： [`delx-wellness-hermes`](https://github.com/davidmosiah/delx-wellness-hermes). <!-- /delx-wellness see-also --> ## 📧 联系&支持 - 📨 **support@delx.ai** — 一般问题、集成帮助、合作伙伴 - 🐛 **错误报告/功能请求** — [GitHub Issues](https://github.com/davidmosiah/apple-health-mcp/issues) - 🐦 **更新** — [@delx369](https://x.com/delx369) on X - 🌐 **站点** — [wellness.delx.ai](https://wellness.delx.ai) ## 许可证 MIT — 参见 [LICENSE](LICENSE). ## 免责声明 该软件按原样提供。它不是医疗设备，不提供医疗建议，不应用于诊断、治疗或紧急监控。始终咨询合格的专业人员以获取医疗问题。