google-health-mcp
A read-only local MCP server that exposes personal Google Health (Fitbit, Pixel Watch) data, calculated metrics, and summaries to AI agents.
Get daily health facts (
get_daily_health_facts): Retrieve calculated health metrics for a specific date — sleep data, resting heart rate, HRV, activity values — plus 7-day/28-day baseline comparisons.Get daily health pulse (
get_daily_health_pulse): Fetch a deterministic, human-readable English summary of your daily health status for a given date.Get health history (
get_health_history): Query normalized daily metrics (e.g., sleep minutes, steps, resting heart rate, HRV) for an inclusive date range of up to 90 days, with optional field filtering.Get health data status (
get_health_data_status): Check authorization status, last sync time, and local data coverage — without exposing any credentials.Get health data catalog (
get_health_data_catalog): List all supported detailed data types (e.g., sleep stages, intraday heart rate, HRV, activity intervals) along with their local record coverage dates.Get full-fidelity health records (
get_health_records): Retrieve complete, detailed Google Health records (sleep stage segments, timestamped heart rate samples, etc.) for a date range, with data type filtering and pagination (up to 500 records).Get health records by time window (
get_health_window): Query detailed health records overlapping an exact ISO 8601 time window (max 7 days), ideal for correlating health data with calendar events, workouts, or sleep periods, with pagination support.
Delivers daily health pulse messages and allows Discord users to query health data through Hermes integration.
Synchronizes Fitbit health data (steps, sleep, heart rate, etc.) into the local database using the Google Health API.
Integrates with Google Health API v4 to fetch and synchronize health data from sources like Fitbit and Pixel Watch, providing daily metrics and historical records.
Allows the Hermes AI agent to access health facts, baselines, and daily pulse messages via a read-only MCP server for contextual conversations and memory.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@google-health-mcp what's my daily pulse?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 to code it. 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
→ SQLCipher-encrypted database + encrypted sensitive payloads
→ deterministic baselines
→ local read-only MCP server
→ Hermes (optional)
→ DiscordThe 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: personal-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-hermesAlternatively, healthctl setup creates .env interactively without displaying the
client secret. OAuth client credentials are stored in data/credentials.enc, not
.env.
Existing installations should run this once after upgrading:
healthctl migrate-securityThis converts an existing plaintext SQLite database to SQLCipher, moves Google OAuth
client credentials out of .env, protects the master key with Windows DPAPI, and
restricts local file permissions.
For real data:
Run
healthctl serve.In a second terminal, run
healthctl authorize.Run
healthctl sync.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 servestarts the local FastAPI service on127.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-mcpautomatically when it loads the configuredgoogle-healthMCP connection.You do not need to keep
healthctl serverunning 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 syncmanually or schedulehealthctl run-daily.
REST API
The service binds only to 127.0.0.1:8765 by default.
healthctl serveMethod | Path | Purpose |
|
| Configuration and sync status without secrets |
|
| Start Google OAuth |
|
| Receive the OAuth callback |
|
| Revoke Google access |
|
| Synchronize a date range |
|
| Generate facts and a message |
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
The complete SQLite database, including normalized metrics, timestamps, indexes,
OAuth states, and tokens, is encrypted with SQLCipher. Sensitive payloads and OAuth
tokens retain an additional Fernet encryption layer. Google OAuth client credentials
are stored in an encrypted credential file rather than .env.
On Windows, the local master key at data/token.key is wrapped with DPAPI for the
current Windows account. The data directory, database, key, credential store, and
.env use ACLs restricted to that account and SYSTEM. Secrets must be decrypted in
application memory while in use; no application can protect them from malware already
running as the same signed-in user.
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 migrate-security
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 doctorLocal 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-HealthIt 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 -ForceStart 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.
The complete health database is encrypted at rest with SQLCipher.
OAuth client credentials are encrypted outside
.env; tokens are encrypted inside the SQLCipher database with an additional Fernet layer.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
Available Tools
7 toolsget_daily_health_factsA
Return calculated health facts and 7/28-day baselines for one recovery date.
The recovery date contains sleep, resting heart rate, and HRV. Activity values intentionally refer to the previous calendar day. Use YYYY-MM-DD or omit the date for today in the configured timezone.
Inputs: recovery_date. Returns: object
get_daily_health_pulseC
Return the deterministic English daily health summary for one date.
Inputs: recovery_date. Returns: result
get_health_data_catalogA
List every supported detailed data type and its local record coverage.
Inputs: no named parameters. Returns: object
get_health_data_statusA
Return authorization, last-sync, and local data-coverage status without secrets.
Inputs: no named parameters. Returns: object
get_health_historyB
Return normalized daily metrics for an inclusive date range of up to 90 days.
Optionally request only selected fields such as sleep_minutes, steps, resting_heart_rate, or hrv_rmssd_ms. This tool is read-only.
Inputs: start_date (required), end_date (required), fields. Returns: object
get_health_recordsA
Return encrypted-at-rest, full-fidelity Google Health records.
Dates are inclusive YYYY-MM-DD values. Use the catalog first, request only the data types needed, and paginate with limit/offset. Sleep records include complete stage segments; sample data such as heart rate retains its observation timestamp.
Inputs: start_date (required), end_date (required), data_types, limit, +1 more. Returns: object
get_health_windowA
Return detailed records overlapping an exact ISO 8601 time window.
This is intended for correlations with calendar events, workouts, sleep periods, and other timestamped tools. Naive timestamps use the configured local timezone. The maximum window is seven days and results are bounded and pageable.
Inputs: start_time (required), end_time (required), data_types, limit, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Tools have distinct purposes but some overlap exists: get_daily_health_facts and get_daily_health_pulse both return daily summaries (one factual, one narrative), and get_health_history vs get_health_records both provide data at different granularities. Descriptions help differentiate, but minor ambiguity remains.
All tool names follow the verb_noun pattern with snake_case, consistently using 'get_' prefix. The naming is uniform and predictable (e.g., get_daily_health_facts, get_health_data_catalog).
With 7 tools, the set is well-scoped for a health data server. Each tool serves a distinct purpose (daily summary, history, records, catalog, status, time window) without unnecessary bloat or deficiency.
The tool set provides thorough read-only coverage: daily facts, narrative summaries, historical trends, full-fidelity records, time-window queries, and metadata. Missing write operations (create/update/delete) are reasonable if the server is query-only. Minor gaps like direct metric extraction are mitigated by history and records tools.
Maintenance
Related MCP Connectors
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Read-only health context MCP server for Iris users.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server to read daily activity, sleep, heart rate, and body metrics from Google Health API, allowing AI assistants like Claude to access your health data. Optionally syncs health metrics to an Obsidian vault.5MIT
- AlicenseNot gradedqualityDmaintenanceSelf-hosted MCP server that aggregates personal health data from Google Health, Oura, and Withings into a single, provider-attributed interface with configurable source of truth preferences.MIT
- AlicenseAqualityDmaintenanceAn MCP server that locally authenticates with Google Health API v4 and provides read-only access to Fitbit, Pixel Watch, and other health data for AI agents.29129 npm19MIT
- AlicenseNot gradedqualityDmaintenanceRead-only MCP access to Fitbit-synced health data through Google Health API v4. Provides tools for metrics, summaries, trends, and data quality without write or arbitrary HTTP operations.MIT