Health Hub MCP Server

Personal MCP server that ingests Health Connect data from an Android companion app and exposes aggregated health metrics to LLM clients over the Model Context Protocol.

Code

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

The companion app reads raw records from Health Connect and pushes them to this server. The server normalizes, deduplicates, and rolls them up into daily aggregates, then exposes them to LLM clients (Claude, Perplexity, OpenCode) through five MCP tools. Raw events are never handed to the model by default — only rolled-up summaries with explicit caveats so the model cannot silently fabricate missing data.

Requirements

Android 14+ with life-dashboard-companion-app v1.4.0+
Any host with Docker and Docker Compose
Domain with TLS (Caddy handles certificates automatically)

Quick Start

bash

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

Companion Apps

The server accepts health data from two Android apps via separate endpoints. Both write to the same database and use content-hash deduplication — sending the same data from both apps will not double-count.

App	Endpoint	Format	Best for
life-dashboard-companion-app v1.4.0	`POST /ingest/health`	`source: "health_connect"` required	Incremental sync, 200 records per type
HC Webhook	`POST /ingest/hc-webhook`	`source` optional, `rmssd_millis` HRV, extra types	Full sync, all types in one POST

Both endpoints require:

Code

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

The HC Webhook endpoint also accepts 5 additional Health Connect types not present in the companion app: skin_temperature, basal_metabolic_rate, vo2_max, intermenstrual_bleeding, body_water_mass. Unknown type keys are silently tolerated — only types in the server's registry are processed.

Connect Your Phone

See docs/ANDROID.md for step-by-step instructions.

Connect an LLM

Add to Claude Desktop config (claude_desktop_config.json):

config.json

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

For Perplexity, OpenCode, or other MCP clients, use the same URL and token. The Authorization header must include the Bearer prefix — the server rejects requests without it.

MCP Tools

Tool	Description
`daily_summary`	Daily health rollups: steps, distance, calories, sleep, HR, weight
`metric_series`	Time series for any metric with day/week bucketing
`sleep_detail`	Detailed sleep sessions with stages (deep, REM, light, awake)
`get_sync_health`	Per-type sync status: last event, coverage, gaps, errors
`inspect_last_payload`	Raw payload metadata and app diagnostics

Each tool returns an object (never a bare array) with a caveats: string[] field that warns the model about missing days, overlapping records, or aggregation changes. Responses are capped at 400 objects.

Known Limitations

No record IDs from Health Connect — deduplication is content-hash based
Multiple data sources (phone + watch) can cause double-counting for cumulative metrics. The server suppresses overlapping intervals, but this is a heuristic. Check the comparison panel on /debug.
App sync cursor only moves forward — records added to Health Connect retroactively may not arrive
Health Connect does not provide data older than 30 days without re-authorization — the server IS your archive. Back up data/.

License

MIT — see LICENSE.

Companion App

life-dashboard-companion-app v1.4.0