Apple Health Mcp Unofficial

Apple Health MCP

让你的 AI Agent 读取 Apple Health 中的活动、睡眠、HRV 和锻炼数据 — 数据来自本地的 export.zip。
本地优先的 MCP 服务 — 令牌绝不会离开你的设备。

⚡ 使用 Delx Wellness for Hermes 一键安装： npx -y delx-wellness-hermes setup — 在专用的 Hermes 配置中预先配置此连接器及另外 8 个连接器。

也可以将其独立接入 Claude Desktop / Cursor / ChatGPT Desktop — 请参阅下方的安装部分。

---

HTTP（v2 无状态）

默认传输方式为 stdio。可选的 Streamable HTTP — 无会话 ID，返回 JSON，仅限环回地址：

npx -y apple-health-mcp-unofficial --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

环境变量：APPLE_HEALTH_MCP_HOST、APPLE_HEALTH_MCP_PORT、APPLE_HEALTH_MCP_TRANSPORT=http。

本地优先的 MCP 服务，可读取 Apple Health 导出数据并将其提供给 AI Agent。

非官方项目。 与 Apple Inc. 无关联，未获其认可或支持。Apple Health 是 Apple Inc. 的商标。本软件包读取你通过 Apple Health 应用自行生成的导出文件。

无法实时访问 HealthKit。 此连接器读取从 iPhone 导出的 export.xml / export.zip 文件。原生 iOS HealthKit 桥接是未来单独开发的组件。

由 David Mosiah 为使用 Claude、Cursor、Hermes、OpenClaw 或其他兼容 MCP 的 Agent 的用户开发，帮助他们了解长期健康与活动趋势，无需从 Health 应用中手动复制粘贴数字。

这是 Delx Wellness 的一部分，这是一个本地优先的健康 MCP 连接器目录。

如果此连接器有助于你的 Agent 工作流，请为仓库点亮星标。星标能让其他 AI 开发者更容易发现此项目，并帮助 Delx 持续推出本地优先的健康基础设施。

为什么需要它

Apple Health 是大多数人拥有的最完整的个人健康数据集，涵盖多年的活动、心率、睡眠、锻炼、身体测量数据，甚至心电图。但 Apple 没有提供公开的云 API。数据保存在 iPhone 上，由 HealthKit 管理；目前，唯一切实可行的设备外导出方式，是使用“健康”App 中的 健康数据导出 功能。

此软件包会在本地读取导出数据——无论是原始 export.xml、解压后的文件夹，还是 export.zip——并通过 Model Context Protocol 提供 Apple Health 数据。无需令牌、无需 OAuth、无需云同步。导出数据不会离开你的设备。

60 秒完成设置

1. 在 iPhone 上导出 Apple Health 数据：

Health app → tap your profile picture → Export All Health Data

等待几分钟，然后使用 AirDrop 或其他方式将 zip 文件传输到这台设备。

2. 配置并验证：

npx -y apple-health-mcp-unofficial setup --export-path /path/to/export.zip
npx -y apple-health-mcp-unofficial doctor

也可以让 CLI 在 Downloads、Desktop 或 Documents 中找到最新的本地导出文件，将其复制到受管理的本地存储中，并保存该路径：

npx -y apple-health-mcp-unofficial setup --auto-import

支持的导出路径：

• /path/to/export.zip
• /path/to/apple_health_export/（解压后的文件夹）
• /path/to/export.xml（原始导出文件）

保持数据最新——监视文件夹（无需 macOS）：

Apple Health 需要手动导出，因此常见的问题是，一旦你不再重新运行设置，数据就会过时。将连接器指向一个用于放入新导出文件的文件夹：

npx -y apple-health-mcp-unofficial setup --watch-path /path/to/health-exports

现在，每当你从 iPhone 导出数据并将新的 export.zip（或 export.xml，或解压后的 apple_health_export/）放入该文件夹，连接器就会自动将最新文件设为当前活动导出——无论是在服务启动时，还是运行期间实时更新——并刷新缓存的摘要。你也可以随时使用 apple_health_reimport 工具触发重新扫描。这是跨平台的定期刷新方案；要实现完全实时的 HealthKit 桥接，仍需要原生 macOS/iOS 组件。

然后将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "apple_health": {
      "command": "npx",
      "args": ["-y", "apple-health-mcp-unofficial"]
    }
  }
}

对于 Claude Desktop，运行 setup --client claude --export-path /path/to/export.zip，系统会为你写入配置片段。

用你的 Agent 试试

先问这三个问题：

Use apple_health_connection_status to check setup, then run apple_health_daily_summary.
Give me a 5-line wellness brief for today.

Call apple_health_data_inventory first. What Apple Health signals and date ranges
are available in this export?

Call apple_health_weekly_summary with response_format=json. Compare steps,
sleep, workouts and heart signals across the last 7 days.

Use the apple_health_weekly_review prompt, days=14.
Find the biggest habit pattern and suggest one experiment.

数据可用性

此软件包会解析“健康”App 导出的 Apple Health 数据。本 README 中的 raw 指的是上游 XML 记录字段，而非原始 HealthKit 数据。

数据	是否可用	备注
活动（步数、距离、能量、锻炼）	✓	标准 HKQuantityType 记录
心率（静息心率 + 样本）	✓	记录的心率样本和静息心率
睡眠分析 + 睡眠阶段	✓	iPhone/Watch 记录睡眠时可用
锻炼 + 运动元数据	✓	所有 HKWorkout 条目
身体测量数据（体重、BMI、体脂）	✓	用户记录时可用
HRV（SDNN）+ 呼吸频率	✓	Watch 支持时可用
ECG 记录	✓（元数据）	Apple Watch 心电图事件；原始波形需要导出 PDF
实时 HealthKit 访问	—	Apple 没有提供公开的实时 API
iCloud Health 同步	—	导出文件未提供此功能

工具

从这些工具开始：

• 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 获取有界记录。limit 仅限制返回的列表：在默认的 summary 隐私模式下，aggregate 块（count_by_type、units、date_range、numeric）会基于所有符合筛选条件的记录计算，而 truncated / limit_applied / matched_count 会告知列表本身是否已截断。统计数据位于 numeric 之下（numeric.min / numeric.max / numeric.sum / numeric.average / numeric.count），而不在 aggregate 顶层 — 请参阅载荷示例
• apple_health_list_workouts — 按 start、end、limit 获取有界锻炼记录。规则相同：limit 仅限制返回的列表；在 summary 隐私模式下，aggregate 总计（count_by_activity、date_range、total_duration_minutes、total_distance、distance_units、total_energy_kcal、workout_count）会涵盖所有符合筛选条件的锻炼记录，而 truncated / limit_applied / matched_count 会报告列表是否已截断

保持数据最新

• apple_health_reimport — 重新扫描监视文件夹（APPLE_HEALTH_WATCH_PATH）并提升最新导出数据，以刷新摘要；传入 check_only: true 可预览而不进行提升

列表调用的开销

limit 限制的是输出，而非处理工作。在默认的 summary 隐私模式下，聚合结果必须涵盖所有符合条件的记录，因此扫描不会在达到上限时停止 — 它会将 export.xml 读取至末尾。使用 type、start 或 end 缩小范围不会缩短扫描时间：匹配项仍可能位于文件最后一个字节，因此无论如何都会读取整个文件。

在合成导出数据上测得（Node 23、macOS、暖页缓存），在摘要模式下调用一次 apple_health_list_records 的耗时如下：

export.xml	首次调用，摘要模式	重复同一调用	同一调用，privacy_mode: "raw"
84 MB（353k 条记录）	~3.0 s	<1 ms	~1 ms
336 MB（1.4M 条记录）	~11.3 s	<1 ms	~2 ms

约为每 MB 33 ms，与文件大小呈线性关系。首次冷读大型导出文件 — 即操作系统尚未缓存该文件时 — 耗时会明显更长（336 MB 的文件测得约 ~29 s）。

实用建议：

• 完全相同的重复查询无需额外开销。 结果会按导出文件在内存中进行记忆化，键为路径 + 大小 + mtime。提升新的导出数据（或调用 apple_health_reimport）会使其失效，因此不会返回过时的导出数据。
• apple_health_daily_summary、apple_health_weekly_summary 和 apple_health_data_inventory 共用单独的快照缓存，且本就会进行一次完整解析；不受此影响。
• 只需要快速查看页面，而不需要统计数据？ 设置 privacy_mode: "structured" 或 "raw"，扫描会在达到 limit 时停止，并在约一毫秒内返回 — 代价是返回单条记录，而非聚合结果。
• apple_health_list_workouts 在所有模式下都会读取至文件末尾，因为锻炼记录较为稀疏：导出文件很少包含足够多的 Workout 元素，甚至连默认的 50 条页面都填不满。
• incremental_cache: true 永远不会进行记忆化 — 它会推进每个类别持久化的游标，因此每次调用都必须实际执行。

负载示例

使用合成值，呈现真实结构。npm run test:readme-contract 会使用仓库测试夹具调用实际服务；如果下方任一键不再存在，或服务开始返回本节未展示的键，测试就会失败。

{
  "source": "apple_health_export",
  "type": "HKQuantityTypeIdentifierHeartRate",
  "privacy_mode": "summary",
  "count": 50,
  "limit_applied": 50,
  "truncated": true,
  "matched_count": 2847,
  "records": [],
  "aggregate": {
    "count_by_type": { "HKQuantityTypeIdentifierHeartRate": 2847 },
    "units": ["count/min"],
    "date_range": {
      "first": "2026-04-01T03:12:00.000Z",
      "last": "2026-04-30T23:41:00.000Z",
      "first_date": "2026-04-01",
      "last_date": "2026-04-30"
    },
    "numeric": { "count": 2847, "sum": 202137, "average": 71, "min": 48, "max": 174 }
  },
  "aggregate_scope": "all_matching_records",
  "disclosure": "summary_mode_omits_individual_records_aggregate_covers_all_matching_records"
}

在 summary 模式下，records 按设计为空——汇总数据会取代单独的样本。count 仍会报告扫描分页读取的记录数；matched_count 则是汇总数据涵盖的完整匹配集数量。

{
  "source": "apple_health_export",
  "privacy_mode": "summary",
  "count": 12,
  "limit_applied": 50,
  "truncated": false,
  "matched_count": 12,
  "workouts": [],
  "aggregate": {
    "count_by_activity": {
      "HKWorkoutActivityTypeRunning": 8,
      "HKWorkoutActivityTypeTraditionalStrengthTraining": 4
    },
    "date_range": {
      "first": "2026-04-02T21:10:00.000Z",
      "last": "2026-04-29T22:05:00.000Z",
      "first_date": "2026-04-02",
      "last_date": "2026-04-29"
    },
    "total_duration_minutes": 486.5,
    "total_distance": 62.4,
    "distance_units": ["km"],
    "total_energy_kcal": 5820,
    "workout_count": 12
  },
  "aggregate_scope": "all_matching_workouts",
  "disclosure": "summary_mode_omits_individual_workouts_aggregate_covers_all_matching_workouts"
}

提示词

• 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

隐私与安全

• Apple Health 导出包含高度敏感的个人健康数据。请将其保存在本地。
• 切勿将 export.xml / export.zip 提交到 GitHub、将原始导出内容粘贴到聊天中，或上传到问题单。
• 导出路径为只读；MCP 不会修改你的导出文件。
• 对于此连接器，APPLE_HEALTH_PRIVACY_MODE 默认值为 summary（比其他 Delx Wellness 连接器更保守），因为数据集内容丰富且敏感。在 summary 模式下，低级列表工具会返回汇总数据，而非单独的记录。原始记录转储需主动选择启用。
• 这不是医疗建议。该服务提供你自行导出的数据，供个人 AI 工作流使用，不用于诊断或紧急监测。

配置

APPLE_HEALTH_EXPORT_PATH=/path/to/export.zip   # or export.xml or apple_health_export/
APPLE_HEALTH_PRIVACY_MODE=summary              # summary | structured | raw
APPLE_HEALTH_TIMEZONE=America/Fortaleza        # local-day summaries; defaults to UTC unless setup saves a timezone
APPLE_HEALTH_WATCH_PATH=/path/to/health-exports # optional: auto-reimport the newest export dropped here

setup 会将这些设置写入 ~/.apple-health-mcp/config.json，并设置 0600 权限。

setup --auto-import 会扫描常见的本地文件夹，查找最新的 Apple Health 导出，并将其复制到 ~/.apple-health-mcp/exports/，并设置 0600 权限。iPhone 导出文件传输完成后，此选项会自动执行本地导入步骤。要实现完全实时的 HealthKit 同步，仍需单独的原生桥接；此 Node MCP 则仅读取本地导出文件。

setup --watch-path <dir>（或 APPLE_HEALTH_WATCH_PATH）会将某个文件夹设为投放目录。服务启动时、运行期间（通过文件系统事件），以及每次调用 apple_health_reimport 工具时，连接器都会将该目录中找到的最新 Apple Health 导出设为当前导出——支持 export.xml、export.zip、apple_health_export/ 目录，或任意 *apple*health*.zip 文件——并清除快照和增量缓存，让下一次汇总反映新数据。apple_health_connection_status 会报告监视文件夹的状态，并在有较新的导出等待处理时发出警告。

Hermes / 远程配置

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 的 Apple Health 导出（健康 App → 个人头像 → 导出所有健康数据）

开发

git clone https://github.com/davidmosiah/apple-health-mcp.git
cd apple-health-mcp
npm install
npm test
npm run build

使用 MCP Inspector 测试：

npx @modelcontextprotocol/inspector node dist/index.js

可选的本地 HTTP 传输：

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
• Apple Health 导出指南：https://support.apple.com/guide/iphone/share-health-and-fitness-data-iph27f6325b2/ios

另请参阅

完整的 Delx Wellness 连接器库：

提供商	软件包	仓库
WHOOP	whoop-mcp-unofficial	whoop-mcp
Oura	oura-mcp-unofficial	ouramcp
Garmin	garmin-mcp-unofficial	garminmcp
Strava	strava-mcp-unofficial	strava-mcp
Fitbit	fitbit-mcp-unofficial	fitbitmcp
Withings	withings-mcp-unofficial	withingsmcp
Apple Health	apple-health-mcp-unofficial	apple-health-mcp
Polar	polar-mcp-unofficial	polarmcp
Nourish（营养）	wellness-nourish	wellness-nourish

Hermes 一键配置——预先配置上述所有连接器，以及健康技能和入门指引：delx-wellness-hermes。

📧 联系与支持

• 📨 [email protected] — 一般问题、集成协助、合作洽谈
• 🐛 错误报告 / 功能请求 — GitHub Issues
• 🐦 动态 — X 上的 @delx369
• 🌐 网站 — wellness.delx.ai

许可证

MIT — 参见 LICENSE。

免责声明

本软件按原样提供。它不是医疗器械，不提供医疗建议，也不应用于诊断、治疗或紧急监测。遇到医疗问题时，请务必咨询合格的专业人士。

技能或 MCP

同一个软件包，两种使用方式。MCP 通过 stdio/HTTP 注册工具。技能 可在客户端不支持 MCP 时，通过 CLI 调用相同的工具：

npx -y apple-health-mcp-unofficial call apple_health_connection_status --json '{}'

将 skill/SKILL.md 复制到你的 Agent 技能目录。