Google Health Daily Pulse

A self-hosted health service for Google Health API v4. It synchronizes Fitbit, Pixel Watch, and compatible health data, preserves timestamped records locally, calculates reproducible 7-day and 28-day comparisons, and exposes both summaries and full-fidelity data to Hermes Agent through a read-only MCP server.

You can do anything you want with this repo. Codex was used. Use at your own risk. For Mac users, there should not be much of a difference. I will test it on a Mac later and update the repository if there are any issues.

Architecture

Google Health API
  → OAuth 2.0 + encrypted tokens
  → FastAPI / healthctl
  → encrypted detailed records + normalized daily SQLite metrics
  → deterministic baselines
  → local read-only MCP server
  → Hermes (optional)
  → Discord

The health core works without Hermes. If Hermes, the subscription, or a rate limit is unavailable, the service can produce a deterministic English template message.

Related MCP server: Google Health MCP

Quick start

Requirement: Python 3.11 or newer.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env
healthctl seed-demo
healthctl daily-pulse --no-hermes

Alternatively, healthctl setup creates .env interactively without displaying the client secret.

For real data:

1. Configure Google Cloud.

2. Run healthctl serve.

3. In a second terminal, run healthctl authorize.

4. Run healthctl sync.

5. Run healthctl daily-pulse --no-hermes.

See docs/windows-setup.md for the complete Windows, Hermes, Codex, Discord, MCP, and scheduler setup.

What needs to stay running?

healthctl serve and the MCP server are separate:

• healthctl serve starts the local FastAPI service on 127.0.0.1:8765. It is needed for the Google OAuth callback and only if you want to use the REST endpoints.

• The local MCP server uses stdio. Hermes starts google-health-mcp automatically when it loads the configured google-health MCP connection.

• You do not need to keep healthctl serve running for MCP access, synchronization through the CLI, or daily-pulse generation.

• To use health tools from Discord continuously, the Hermes gateway must be running.

• To refresh the local database, run healthctl sync manually or schedule healthctl run-daily.

REST API

The service binds only to 127.0.0.1:8765 by default.

healthctl serve

Examples:

Invoke-RestMethod -Method Post `
  -Uri http://localhost:8765/v1/sync `
  -ContentType application/json `
  -Body '{"start_date":"2026-05-15","end_date":"2026-06-20"}'

Invoke-RestMethod -Method Post `
  -Uri http://localhost:8765/v1/daily-pulse `
  -ContentType application/json `
  -Body '{"use_hermes":true,"send":false}'

Uvicorn access logs are disabled by the CLI server so OAuth codes do not appear in query-string logs.

Data model

The database stores two complementary layers.

Normalized daily values:

• Sleep duration, sleep period, awake time, awakenings, and efficiency

• Light, deep, and REM sleep when available

• Steps

• Light, moderate, and vigorous activity minutes

• Exercise count, duration, and types

• Daily resting heart rate

• Daily HRV/RMSSD

Full-fidelity records preserve the complete structured Google payload and timestamps for every supported stream under the configured activity, health-metrics, and sleep scopes. This includes:

• Complete sleep sessions, stage segments, and out-of-bed segments

• Intraday heart rate, HRV, oxygen saturation, and respiratory measurements

• Heart-rate zones, activity intervals, sedentary periods, and exercise details

• Energy, distance, floors, VO2 max, body measurements, and temperature records

• Daily rollups for total calories and calories in heart-rate zones

Detailed payloads and OAuth tokens are Fernet-encrypted in SQLite. They are never written to logs. The local encryption key is generated on first use at data/token.key.

The default daily sync uses 35 days for compact baseline metrics and two recent days for full-resolution records. This avoids re-downloading hundreds of thousands of one-second heart-rate samples every morning. Detailed records accumulate locally as the scheduled sync advances. Configure HEALTH_DETAILED_SYNC_LOOKBACK_DAYS from 1 to 90 for a larger initial backfill.

CLI

healthctl setup
healthctl serve
healthctl authorize
healthctl sync
healthctl facts [--date YYYY-MM-DD]
healthctl daily-pulse [--send] [--no-hermes]
healthctl run-daily [--send]
healthctl seed-demo
healthctl doctor

Local MCP server

The project includes a read-only stdio MCP server for Hermes and other local MCP clients:

google-health-mcp --project-dir C:\path\to\Google-Health

It exposes:

• Calculated daily facts and 7-day/28-day baselines

• The deterministic English daily pulse

• Selected normalized history for up to 90 days

• A catalog of all detailed data types and their local coverage

• Full-fidelity records for a date range with bounded pagination

• Exact timestamp-window queries for calendar and workout correlation

• Authorization, sync, and local data-coverage status

It does not expose OAuth tokens, Google credentials, synchronization, revocation, or database-write operations. Detailed health payloads are intentionally available to the local agent, but each call is date bounded, limited to at most 500 records, and pageable.

Hermes normally starts this executable automatically. You should not run it manually unless you are testing an MCP client.

Hermes skill

The repository includes skills/google-health/SKILL.md. It teaches Hermes how to choose the correct health tool, correlate exact windows with calendar events, handle timezones and personal baselines, and use memory without copying raw health data into it.

Install it into the active Hermes profile:

$SkillsRoot = if (Test-Path "$env:LOCALAPPDATA\hermes\skills") {
  "$env:LOCALAPPDATA\hermes\skills"
} else {
  "$HOME\.hermes\skills"
}
$Target = Join-Path $SkillsRoot "personal\google-health"
New-Item -ItemType Directory -Force $Target | Out-Null
Copy-Item .\skills\google-health\SKILL.md $Target\SKILL.md -Force

Start a new Hermes session after installing or changing the skill.

Security and product boundaries

• Never put secrets in issues, chat messages, or Git.

• Only read-only Google Health scopes are requested.

• Detailed health records remain local and encrypted at rest.

• Hermes Discord access is restricted through DISCORD_ALLOWED_USERS.

• The FastAPI service binds to localhost by default and provides no public multi-user authentication.

• Health guidance describes trends; it does not provide diagnoses or treatment.

• A centrally hosted service requires a different security architecture, privacy review, Google OAuth verification, and recurring restricted-scope security review.

Tests

pytest
ruff check .

Official references

• Google Health API Setup

• Google Health API Scopes

• Google Health API App Verification

• Google Health API REST v4

• OpenAI Codex Authentication

• Hermes MCP

• Hermes Discord Setup