Health Hub MCP

Health Hub MCP Server

个人 MCP 服务，可从 Android 配套应用导入 Health Connect 数据，并通过 Model Context Protocol 向大模型客户端提供汇总后的健康指标。

Android 14+ ──POST /ingest/health──────▶ ┌──────────────────┐
  (companion app)                         │                  │
Android 14+ ──POST /ingest/hc-webhook──▶ │   Health Hub     │──MCP──▶ LLM
  (HC Webhook client)                     │   SQLite         │
                   browser ──GET /debug──▶ └──────────────────┘

配套应用会从 Health Connect 读取原始记录，并将其推送到此服务。服务会对记录进行标准化、去重，并汇总为每日数据，然后通过五个 MCP 工具将数据提供给大模型客户端（Claude、Perplexity、OpenCode）。默认情况下，原始事件不会交给模型——只提供汇总数据，并明确列出 caveats，防止模型悄然编造缺失数据。

要求

• Android 14+，以及 life-dashboard-companion-app v1.4.0+
• 安装了 Docker 和 Docker Compose 的任意主机
• 配备 TLS 的域名（Caddy 会自动处理证书）

快速开始

cp .env.example .env
# Edit .env: set DEVICE_TOKEN and MCP_TOKEN (run: openssl rand -hex 32)
docker compose up -d --build
curl -s http://localhost:8000/health

配套应用

服务通过不同的端点接收来自两款 Android 应用的健康数据。两者都会写入同一个数据库，并使用内容哈希去重——即使两款应用发送相同数据，也不会重复计数。

应用	端点	格式	适用场景
life-dashboard-companion-app v1.4.0	POST /ingest/health	必须提供 source: "health_connect"	增量同步，每种类型最多 200 条记录
HC Webhook	POST /ingest/hc-webhook	source 可选，HRV 使用 rmssd_millis，支持额外类型	全量同步，单次 POST 包含所有类型

两个端点都需要：

Authorization: Bearer <DEVICE_TOKEN>
Content-Type: application/json; charset=utf-8

HC Webhook 端点还接受配套应用不支持的另外 5 种 Health Connect 类型：skin_temperature、basal_metabolic_rate、vo2_max、intermenstrual_bleeding、body_water_mass。未知的类型键会被静默接受——服务只会处理其注册表中的类型。

连接手机

请参阅 docs/ANDROID.md 获取分步说明。

连接大模型

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）：

{
  "mcpServers": {
    "health-hub": {
      "url": "https://your-domain.example.com/mcp",
      "headers": {"Authorization": "Bearer <YOUR_MCP_TOKEN>"}
    }
  }
}

对于 Perplexity、OpenCode 或其他 MCP 客户端，请使用相同的 URL 和令牌。Authorization 标头必须包含 Bearer 前缀——否则服务会拒绝请求。

MCP 工具

工具	描述
daily_summary	每日健康汇总：步数、距离、卡路里、睡眠、心率、体重
metric_series	任意指标的时间序列，支持按天/周分组
sleep_detail	包含睡眠阶段（深睡、REM、浅睡、清醒）的详细睡眠时段
get_sync_health	按类型查看同步状态：最后事件、覆盖范围、缺口、错误
inspect_last_payload	原始负载元数据和应用诊断信息

每个工具都会返回一个 object（绝不会返回单独的数组），并包含 caveats: string[] 字段，用于提醒模型注意缺失日期、重叠记录或汇总方式变更。响应最多包含 400 个对象。

已知限制

• Health Connect 不提供记录 ID——去重基于内容哈希
• 多个数据源（手机 + 手表）可能导致累计指标重复计数。服务会抑制时间重叠的区间，但这只是启发式处理。请查看 /debug 上的对比面板。
• 应用同步游标只会向前移动——事后添加到 Health Connect 的记录可能无法同步过来
• 未经重新授权，Health Connect 不会提供超过 30 天的数据——服务就是你的档案库。请备份 data/。

许可证

MIT——详见 LICENSE。

配套应用

life-dashboard-companion-app v1.4.0