内容
<!-- delx-wellness header v2 -->
<h1 align="center">三星健康MCP</h1>
<div align="center">
<img src="assets/banner.png" alt="三星健康MCP — 为AI代理提供三星健康数据" width="85%" />
</div>
<h3 align="center">
读取您的三星健康CSV/ZIP导出文件 — 活动、睡眠、心率、压力 — 本地进行。<br>
本地优先的MCP服务器 — <strong>令牌从不离开您的机器</strong>。
</h3>
<p align="center">
<a href="https://www.npmjs.com/package/samsung-health-mcp-unofficial"><img src="https://img.shields.io/npm/v/samsung-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/samsung-health-mcp-unofficial"><img src="https://img.shields.io/npm/dm/samsung-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/samsung-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/samsung-health-mcp/stargazers"><img src="https://img.shields.io/github/stars/davidmosiah/samsung-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/Samsung%20Health-1428A0?style=for-the-badge&labelColor=0F172A&logoColor=white&logo=samsung&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服务器，读取三星健康个人数据CSV/ZIP导出文件，并安全地将其暴露给AI代理。**
> **非官方项目。** 不隶属于、不被三星电子支持或认可。三星健康是三星电子的商标。该软件包读取您从三星健康应用程序生成的导出文件。
> **无三星健康云API。** 三星有针对合作伙伴应用程序的Android SDK路径，但此Node MCP不登录三星、不刮取帐户、不直接读取健康连接。目前它读取本地导出文件；未来Android桥可以与其并存。
由 [David Mosiah](https://github.com/davidmosiah) 构建，作为 [Delx Wellness](https://github.com/davidmosiah/delx-wellness) 的一部分，这是一个用于Claude、Cursor、Hermes、OpenClaw和其他MCP兼容代理的本地优先健康MCP连接器注册表。
## 为什么存在
三星健康可以从Galaxy Watch、Galaxy Ring和手机中收集高信号健康数据：步数、睡眠、运动、心率、血氧饱和度、身体测量等。三星官方健康数据SDK可以从Android应用程序中访问许多这些数据类型，但分发需要三星应用程序流程和合作伙伴流程。对于当前的桌面MCP，可靠的隐私保护路径是本地个人数据下载。
此连接器读取该下载文件，支持CSV文件文件夹、单个CSV文件或包含CSV文件的zip文件，然后通过MCP公开有限的摘要和记录。无需三星凭证，无需OAuth令牌，无需云代理。
## 60秒设置
1. 在Android上，从三星健康导出数据：
```text
三星健康 -> 更多选项 -> 设置 -> 下载个人数据
```
2. 将下载的三星健康文件夹或zip文件传输到此机器。
3. 配置和验证：
```bash
npx -y samsung-health-mcp-unofficial setup --export-path /path/to/SamsungHealth
npx -y samsung-health-mcp-unofficial doctor
```
或者让CLI在`Downloads`、`Desktop`或`Documents`中找到最新的本地三星健康导出文件，将其复制到托管的本地存储中，并保存该路径：
```bash
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客户端配置中：
```json
{
"mcpServers": {
"samsung_health": {
"command": "npx",
"args": ["-y", "samsung-health-mcp-unofficial"]
}
}
}
```
对于Claude Desktop，运行 `setup --client claude --export-path /path/to/SamsungHealth`，连接器将为您写入代码段。
**保持更新 — 监视文件夹（无需Android设备）：**
```bash
npx -y samsung-health-mcp-unofficial setup --watch-path /path/to/health-exports
```
现在，每次您从三星健康应用程序下载个人数据并将新的`SamsungHealth`文件夹（或其`.zip`文件，或任何`*samsung*health*.zip`文件）放入该文件夹中，连接器会自动将最新的导出文件提升为活动导出文件 — 在服务器启动时和运行时 — 并刷新缓存的摘要。您还可以通过`samsung_health_reimport`工具触发重新扫描。 这是跨平台的定期刷新路径；完全实时的三星健康同步仍然需要本地的Android健康连接桥。
## 与您的代理一起试用
```text
使用samsung_health_connection_status检查设置，然后运行samsung_health_daily_summary。
给我今天的5行健康简报。
```
```text
首先调用samsung_health_data_inventory。有哪些三星健康信号和日期范围
可在此导出文件中？
```
```text
调用samsung_health_weekly_summary，响应格式为json。比较过去7天内的
步数、睡眠、锻炼和心率信号。
```
## 数据可用性
解析器故意灵活，因为三星个人数据下载文件可能因应用程序版本、地区和设备而异。它从CSV文件名和标题推断记录类型。
| 数据 | 可用 | 备注 |
|---|:---:|---|
| 步数 | 是 | `samsung_health_steps` |
| 距离 + 有氧能量 | 是 | 当CSV或运动行中存在时 |
| 心率 + 静息心率 | 是 | Galaxy Watch导出时可用 |
| HRV、呼吸率、血氧饱和度 | 是 | 取决于设备和地区 |
| 睡眠 + 睡眠阶段 | 是 | Galaxy Watch睡眠导出时可用 |
| 锻炼 / 运动 | 是 | 时长、距离、卡路里和活动类型 |
| 体重 + 体脂 | 是 | 记录或同步时 |
| 即时健康连接读取 | 否 | 计划中的独立Android桥 |
| 三星账户登录 | 否 | 故意不支持 |
## 工具
首先使用这些：
- `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`
## 隐私和安全
- 三星健康导出文件是敏感的个人健康数据。请保持本地存储。
- 永远不要将三星健康CSV/ZIP导出文件提交到GitHub，在聊天中粘贴原始导出文件，或将它们上传到问题。
- 导出路径是只读的；MCP永远不会修改您的源导出文件。
- `SAMSUNG_HEALTH_PRIVACY_MODE` 默认设置为 `summary`；原始记录转储是可选的。
- 这不是医疗建议。服务器公开您自己导出的数据，用于个人AI工作流，而不是诊断或紧急监护。
## 配置
```bash
SAMSUNG_HEALTH_EXPORT_PATH=/path/to/SamsungHealth # 文件夹、csv或zip
SAMSUNG_HEALTH_PRIVACY_MODE=summary # summary | structured | raw
SAMSUNG_HEALTH_TIMEZONE=America/Fortaleza # 本地日摘要
SAMSUNG_HEALTH_WATCH_PATH=/path/to/health-exports # 可选：自动重新导入最新的导出文件
```
`setup` 将这些设置写入 `~/.samsung-health-mcp/config.json`，权限为 `0600`。
`setup --auto-import` 扫描常见的本地文件夹以查找最新的三星健康导出文件，并将其复制到 `~/.samsung-health-mcp/exports/`，权限为限制性。完全实时的三星健康同步仍然需要单独的Android桥。
### 监视文件夹（定期自动重新导入）
`setup --watch-path <dir>` （或 `SAMSUNG_HEALTH_WATCH_PATH`）使连接器将文件夹视为投递区。在启动时、在运行时（通过文件系统事件）和调用`samsung_health_reimport`工具时，它会将找到的最新三星健康导出文件（`SamsungHealth`导出目录、单个`*.csv`文件或任何`*samsung*health*.zip`文件）提升为活动导出文件，并清除快照和增量缓存，以便下一个摘要反映新数据。`samsung_health_connection_status`报告监视文件夹状态，并在有新导出文件等待时发出警告。完全实时的同步仍然需要本地的Android健康连接桥。
## Hermes / 远程设置
```bash
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`。无需重启网关即可访问正常导出。
## 开发
```bash
git clone https://github.com/davidmosiah/samsung-health-mcp.git
cd samsung-health-mcp
npm install
npm test
```
可选的本地HTTP传输：
```bash
SAMSUNG_HEALTH_MCP_TRANSPORT=http SAMSUNG_HEALTH_MCP_PORT=3000 node dist/index.js
curl http://127.0.0.1:3000/health
```
## 官方参考
- 三星个人数据导出：<https://www.samsung.com/us/support/answer/ANS10001379/>
- 三星健康数据SDK：<https://developer.samsung.com/health/data/overview.html>
- 三星健康数据SDK应用程序流程：<https://developer.samsung.com/health/data/process.html>
- Android健康连接：<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>
---
## 📧 联系和支持
- 📨 **support@delx.ai** — 一般问题、集成帮助、合作伙伴关系
- 🐛 **错误报告 / 功能请求** — [GitHub问题](https://github.com/davidmosiah/samsung-health-mcp/issues)
- 🐦 **更新** — [@delx369](https://x.com/delx369) 在X上
- 🌐 **站点** — [wellness.delx.ai](https://wellness.delx.ai)
