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.
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
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:
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):
{
"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