samsung-health-mcp

Samsung Health MCP

在本地读取 Samsung Health 导出的 CSV/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 samsung-health-mcp-unofficial --http
# GET  http://127.0.0.1:3000/health
# POST http://127.0.0.1:3000/mcp   (sessionless)

环境变量：SAMSUNG_HEALTH_MCP_HOST、SAMSUNG_HEALTH_MCP_PORT、SAMSUNG_HEALTH_MCP_TRANSPORT=http。

这是一款非官方、本地优先的 MCP 服务，可读取 Samsung Health 个人数据 CSV/ZIP 导出文件，并安全地向 AI Agent 提供这些数据。

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

不提供 Samsung Health 云端实时 API。 Samsung 为合作伙伴应用提供 Android SDK 接入途径，但此 Node MCP 不会登录 Samsung、抓取账号数据，也不会直接读取 Health Connect。它目前读取本地导出文件；未来可以配合 Android 桥接程序使用。

由 David Mosiah 开发，是 Delx Wellness 的一部分。Delx Wellness 是一个本地优先的健康类 MCP 连接器目录，适用于 Claude、Cursor、Hermes、OpenClaw 及其他兼容 MCP 的 Agent。

为什么需要它

Samsung Health 可以从 Galaxy Watch、Galaxy Ring 和手机收集高价值健康数据：步数、睡眠、运动、心率、血氧饱和度、身体测量数据等。Samsung 官方 Health Data SDK 可在获得用户许可后，从 Android 应用访问其中许多类型的数据，但要分发应用，则需要经过 Samsung 的应用审核流程和合作流程。对于当前的桌面 MCP，可靠且保护隐私的做法是下载个人数据到本地。

此连接器会在本地读取下载的数据，支持包含 CSV 文件的文件夹、单个 CSV 文件或包含 CSV 文件的 zip 文件，然后通过 MCP 提供范围受限的摘要和记录。无需 Samsung 凭据、OAuth 令牌或云端代理。

60 秒内完成设置

1. 在 Android 上，从 Samsung Health 导出数据：

Samsung Health -> More options -> Settings -> Download personal data

2. 将下载的 Samsung Health 文件夹或 zip 文件传输到这台机器。

3. 配置并验证：

npx -y samsung-health-mcp-unofficial setup --export-path /path/to/SamsungHealth
npx -y samsung-health-mcp-unofficial doctor

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

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

支持的导出路径：

• /path/to/SamsungHealth/ 或其他包含 CSV 文件的文件夹
• /path/to/samsung_health_export.zip
• /path/to/com.samsung.health.step_count.csv

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

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

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

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

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

之后，每当你从 Samsung Health 应用下载个人数据，并将新的 SamsungHealth 文件夹（或其 .zip 文件，或任何 *samsung*health*.zip 文件）放入该文件夹时，连接器都会在服务启动时以及运行期间实时将最新导出文件设为活动导出文件，并刷新缓存的摘要。你也可以通过 samsung_health_reimport 工具按需重新扫描。这是跨平台的定期刷新方式；要实现 Samsung Health 完全实时同步，仍需要原生 Android Health Connect 桥接程序。

与你的 Agent 一起试用

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

Call samsung_health_data_inventory first. What Samsung Health signals and date ranges
are available in this export?

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

数据可用性

此解析器有意采用灵活的设计，因为 Samsung 个人数据下载内容可能因应用版本、语言区域和设备而异。它会根据 CSV 文件名和表头推断记录类型。

数据	可用	备注
步数	是	samsung_health_steps
距离 + 活动能量	是	CSV 文件或运动记录中存在时可用
心率 + 静息心率	是	有 Galaxy Watch 导出数据时可用
HRV、呼吸频率、血氧饱和度	是	视设备和地区而定
睡眠 + 睡眠阶段	是	有 Galaxy Watch 睡眠导出数据时可用
锻炼 / 运动	是	包含时长、距离、卡路里和活动类型
体重 + 体脂	是	记录或同步后可用
实时读取 Health Connect	否	计划通过独立的 Android 桥接程序实现
Samsung 账户登录	否	有意不支持

工具

从以下工具开始：

• samsung_health_connection_status - 读取数据前验证导出路径
• samsung_health_data_inventory - 查找可用记录类型、日期范围、数据源数量和导出过期风险
• samsung_health_daily_summary - 根据导出数据生成每日健康简报
• samsung_health_weekly_summary - 每周对比和习惯趋势

诊断：

• samsung_health_capabilities
• samsung_health_agent_manifest
• samsung_health_privacy_audit

记录：

• samsung_health_list_records - 根据 type、start、end、limit 查询范围受限的记录
• samsung_health_list_workouts - 查询范围受限的锻炼记录

维护：

• samsung_health_reimport - 重新扫描监视文件夹（SAMSUNG_HEALTH_WATCH_PATH），并将最新导出文件设为活动导出文件，同时刷新摘要；传入 check_only: true 可预览而不进行切换

提示词和资源

提示词：

• samsung_health_daily_review
• samsung_health_weekly_review

资源：

• samsung-health://capabilities
• samsung-health://agent-manifest
• samsung-health://inventory
• samsung-health://summary/daily
• samsung-health://summary/weekly

隐私与安全

• Samsung Health 导出文件包含敏感的个人健康数据。请将其保留在本地。
• 切勿将 Samsung Health CSV/ZIP 导出文件提交到 GitHub、将原始导出内容粘贴到聊天中，或上传到议题中。
• 导出路径为只读；MCP 不会修改源导出文件。
• SAMSUNG_HEALTH_PRIVACY_MODE 默认值为 summary；原始记录转储需主动选择启用。此设置适用于所有数据路径：samsung_health_list_records、samsung_health_list_workouts 和 samsung_health_daily_summary（仅当 privacy_mode 为 structured 或 raw 时，才会返回单条锻炼记录）。
• samsung_health_weekly_summary 接受 privacy_mode，但始终进行聚合——30 天的原始锻炼数据并不适合用于每周汇总。为了避免回显并未实际应用的模式，响应中包含 requested_privacy_mode（你请求的模式）、privacy_mode（始终为 summary，即实际应用的模式）和说明此覆盖行为的 privacy_disclosure。如需访问记录级数据，请使用 samsung_health_daily_summary 或 samsung_health_list_workouts。
• 记录和锻炼的 metadata 使用允许列表，而非拒绝列表。解析器只会输出已识别的健康数据列（时间、时长、距离、卡路里、心率／睡眠／身体指标、来源名称）。GPS 坐标、海拔、deviceuuid 和用户自由文本字段会在解析时被剔除，永远不会到达任何工具、资源或 raw 响应；withheld_metadata_count 字段会报告被剔除的列数。
• 这不是医疗建议。此服务端向你的个人 AI 工作流提供你自行导出的数据，并非用于诊断或紧急监测。

配置

SAMSUNG_HEALTH_EXPORT_PATH=/path/to/SamsungHealth  # folder, csv, or zip
SAMSUNG_HEALTH_PRIVACY_MODE=summary                # summary | structured | raw
SAMSUNG_HEALTH_TIMEZONE=America/Fortaleza          # local-day summaries
SAMSUNG_HEALTH_WATCH_PATH=/path/to/health-exports  # optional: auto-reimport the newest export dropped here

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

setup --auto-import 会扫描常见的本地文件夹，查找最新的 Samsung Health 导出文件，并以限制性权限将其复制到 ~/.samsung-health-mcp/exports/。要实现 Samsung Health 完全实时同步，仍需单独的 Android 桥接程序。

监视文件夹（定期自动重新导入）

setup --watch-path <dir>（或 SAMSUNG_HEALTH_WATCH_PATH）会让连接器将某个文件夹视为投放区。启动时、运行期间（通过文件系统事件），以及每次调用 samsung_health_reimport 工具时，连接器都会将其中找到的最新 Samsung Health 导出文件设为活动导出文件——可以是包含 CSV 文件的 SamsungHealth 导出目录、单个 *.csv，或任意 *samsung*health*.zip——并清除快照和增量缓存，使下一次汇总反映新数据。samsung_health_connection_status 会报告监视文件夹的状态，并在有更新的导出文件等待处理时发出警告。要实现完全实时同步，仍需原生 Android Health Connect 桥接程序。

Hermes／远程配置

npx -y samsung-health-mcp-unofficial setup --client hermes --export-path /path/to/SamsungHealth
npx -y samsung-health-mcp-unofficial doctor --client hermes
hermes mcp test samsung_health

更改 Hermes 配置后，请使用 /reload-mcp 或 hermes mcp test samsung_health。正常访问导出文件无需重启网关。

开发

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

可选的本地 HTTP 传输：

SAMSUNG_HEALTH_MCP_TRANSPORT=http SAMSUNG_HEALTH_MCP_PORT=3000 node dist/index.js
curl http://127.0.0.1:3000/health

官方参考资料

• Samsung 个人数据导出：https://www.samsung.com/us/support/answer/ANS10001379/
• Samsung Health Data SDK：https://developer.samsung.com/health/data/overview.html
• Samsung Health Data SDK 应用流程：https://developer.samsung.com/health/data/process.html
• Android Health Connect：https://support.google.com/android/answer/12201227

链接

• npm：https://www.npmjs.com/package/samsung-health-mcp-unofficial
• 文档网站：https://wellness.delx.ai/connectors/samsung-health
• GitHub：https://github.com/davidmosiah/samsung-health-mcp
• Delx Wellness 注册表：https://github.com/davidmosiah/delx-wellness

---

📧 联系与支持

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

技能还是 MCP

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

npx -y samsung-health-mcp-unofficial call samsung_health_connection_status --json '{}'

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