Skip to main content
Glama
deenesjakoruzh
nnishad

health-relay

by nnishad
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

health-relay

在你的 Samsung Watch → Sync2Ra1 手机应用 与 Hermes AI 智能体 之间自托管桥接。手机应用会通过局域网把健康读数推送过来；数据存储在本地（SQLite），并通过 REST 和 MCP 对外暴露，方便你的智能体查询。

Galaxy Watch ─▶ Samsung Health ─▶ Sync2Ra1 (phone) ──push──▶ health-relay ──MCP/REST──▶ Hermes

所有数据都留在你的网络中，不会发送到任何其他地方。

快速开始（Docker 或 Podman)

echo "HR_AUTH_TOKEN=<choose-a-secret>" > .env
docker compose up -d          # or: podman compose up -d
curl http://localhost:8790/healthz     # -> {"ok":true}

数据持久化在 ./data/ledger.db（SQLite，WAL 模式）。

不使用 Docker 运行

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
HR_AUTH_TOKEN=<secret> ./run.sh

Related MCP server: Yummy Health MCP

将手机应用接入

在 Sync2Ra1 → 数据标签页 → 中继（Hermes 桥接） 中：

字段

值

中继 URL

http://<this-machine-ip>:8790

Token

与 HR_AUTH_TOKEN 相同的密钥

点击 保存 → 立即同步。读数会在数秒内到达。

连接方式

phone (Sync2Ra1) ──HTTP :8790──▶ health-relay ◀──MCP stdio / HTTP── Hermes
        same LAN · or Tailscale for anywhere-access

规则

说明

方向

手机 → 中继（仅由手机发起出站连接；没有任何连接会进入手机）

端口

在运行中继的机器上开放 TCP 8790 入站端口——请在宿主机防火墙中放行该端口

协议

明文 HTTP + Authorization: Bearer <token>。建议仅限局域网使用，或前置反向代理（Caddy/nginx）启用 TLS

任意位置访问

在机器和手机上安装 Tailscale，并让应用指向 Tailscale IP（http://100.x.y.z:8790）——加密、可在移动数据下使用、不向互联网暴露端口

同步节奏

每小时自动同步 + 应用启动时同步 + 手动 立即同步

离线

手机会把所有内容存在本地 SQLite 中；重新连网后先推送完整积压数据（从旧到新），再重新同步最近 48 小时，让 Samsung 的修正继续传播

数据去重

不可能重复计数——每条读数都有唯一键，重复推送在服务端会被忽略

Hermes 位置

可以同机部署（MCP 作为本地子进程读取 SQLite 文件），也可远程部署（使用 REST 端点而不使用 MCP）

REST API（Bearer 鉴权）

curl -H "Authorization: Bearer <secret>" \
  "http://localhost:8790/api/v1/health/daily-summary?date=$(date +%F)&tz=Europe/London"

接口

用途

GET /healthz

存活检查（无需鉴权）

POST /api/v1/health/samples

批量写入——幂等，重复提交无效

GET /api/v1/health/samples?type=&from_ms=&to_ms=&limit=&offset=

原始读数

GET /api/v1/health/daily-summary?date=YYYY-MM-DD&tz=Europe/London

每个指标的最小/最大/平均/计数

GET /api/v1/health/trends?type=X&days=N&tz=Europe/London

每日汇总

GET /api/v1/health/status

按类型统计总数

curl -H "Authorization: Bearer <secret>" \
  "http://localhost:8790/api/v1/health/daily-summary?date=$(date +%F)&tz=Europe/London"

接入 Hermes（MCP)

MCP 服务器读取的是同一个 SQLite 文件——直接从本仓库运行即可：

python3 -m venv .venv-mcp
.venv-mcp/bin/pip install fastmcp

在你的 agent 的 MCP 配置中添加：

{
  "mcpServers": {
    "health-relay": {
      "command": "<repo-path>/.venv-mcp/bin/python",
      "args": ["<repo-path>/mcp_server.py"],
      "env": { "HR_DATA_DIR": "<repo-path>/data" }
    }
  }
}

你的 agent 获得的工具

工具

可以回答的问题

list_streams()

“你有哪些健康数据？”

get_samples(type, from_ms, to_ms)

“显示一下我早上的心率”

daily_summary(date, tz)

“我昨天活动量如何？”

sleep_breakdown(nights)

“我这周睡眠情况如何？”

日期边界会按你的时区计算（例如 tz="Europe/London"，夏令时可自动处理）。

记录的数据流

心率 · SpO₂ · 皮肤温度 · 呼吸信息 · 静息心率；VO₂max · 睡眠时长/评分/分期；驾行与楼层数（小时 + 每日） · 运动种类 · 运动热量/时长/距离 · 身体成分（BIA） · 能量积分 · 血压 · 血糖 · 饮水 · 饮食。

配置

环境变量

默认值

HR_AUTH_TOKEN

（留空 = 关闭鉴权）

生产环境请务必设置

HR_PORT

8790

HR_HOST

0.0.0.0

请保持只监听内网

HR_DATA_DIR

~/health-relay-data

SQLite 数据放在这里

测试

.venv/bin/python -m pytest tests/ -q

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Yummy Health MCP

    yummy520730
    F
    license
    Not graded
    quality
    B
    maintenance
    Private, read-only health data bridge that reads from Android Health Connect and exposes heart rate, steps, sleep, and other health metrics to ChatGPT via MCP tools.
    -

  • garmin-owl

    xichen-de
    A
    license
    B
    quality
    A
    maintenance
    Enables local, read-only access to Garmin Connect health and training data through MCP, letting assistants summarize recovery, sleep, activities, and more without uploading your data.
    19
    MIT