google-health-mcp

MCP server for the Google Health API, with a local SQLite cache and trend analysis.

Designed for Claude Code and other MCP clients. Your data syncs to a database on your own machine, so queries are fast, work offline, and cost no API quota.

Features

• Local SQLite cache - sync once, query instantly
• Incremental sync - each run fetches only what is new, resuming from where the last one stopped
• Offline mode - serve the cache with no credentials and no network at all
• Trends - weekly, monthly or quarterly aggregates, and two-period comparisons
• ECG - readings stored whole, waveform included, returned only when asked for
• doctor - diagnoses a setup offline and read-only, without spending quota

Data types

Requirements

• Python 3.13+ (tested on 3.13 and 3.14, on Linux, macOS and Windows, in CI)
• A Google account with health data, and a Google Cloud project to authorise against. No billing account is needed - the console offers a free trial throughout setup and you can decline all of it.

Setup

1. Install

pip install google-health-mcp

Or run it without installing, in which case every google-health-mcp ... command you run below becomes uvx google-health-mcp ...:

uvx google-health-mcp --version

2. Create the Google Cloud project

Every user registers their own OAuth client. This is seven console steps, and the page names are Google's as of August 2026.

Google's own setup page will send you somewhere else - follow the steps below instead. Its quick-start builds a Web client with https://www.google.com as the redirect URI, which suits the OAuth Playground rather than a program running on your machine; this server refuses that file and says so. Use that page only to check whether one of the pages below has been renamed.

1. Project. Create a project at console.cloud.google.com/projectcreate and select it.
2. API. Enable Google Health API on the API Enablement page.
3. Get started. Open Google Auth Platform and complete Get started - app name, support email, External audience, contact email. A new project has no Audience, Data Access or Clients page until this is done.
4. Audience. Under Test users, add your own Google account. Skipping this fails sign-in with 403: access_denied.
5. Data Access. Click Add or remove scopes, search for "Google Health API", and tick the read-only scopes listed under OAuth scopes below.
6. Clients. Create an OAuth client of type Desktop app and download its JSON. A Desktop client permits the loopback redirect automatically, so there is nothing to register; a Web client does not, and fails at consent instead.
7. Publish. Back on the Audience page, click Publish app.

Step 7 is the one that bites, and it is worth checking rather than assuming. While an app's publishing status is Testing, Google issues refresh tokens that expire seven days after consent - so everything works, and then syncing stops a week later with nothing pointing back to this moment. The Audience page can read "In production" while the token server disagrees. Two readings that do not: the verification-status line on the Branding page, and google-health-mcp doctor, which fails loudly when the stored token records a short expiry.

3. Authorise

Put the downloaded client JSON where the server looks for it, unedited:

mkdir -p ~/.config/google-health-mcp
cp ~/Downloads/client_secret_*.json ~/.config/google-health-mcp/google_client.json
google-health-mcp auth

Your browser will warn that Google hasn't verified this app. That is expected, and the app is your own: these health scopes are classified restricted, and verification only matters above 100 users. Click Advanced, then Go to google-health-mcp (unsafe), and grant the scopes.

The flow listens on localhost:8081 for the callback, so that port must be free. It saves tokens to ~/.config/google-health-mcp/google_tokens.json, created 0600 on POSIX. Windows keeps only the owner-write bit, as its read-only attribute, and governs access by ACLs - so there the file is not restricted to your account, and what it grants is whatever its directory's ACLs pass down. Access tokens last an hour and refresh automatically. Refresh tokens do not rotate, so a token minted on a machine with a browser can be copied to a headless one.

If you authorised before publishing the app, re-run google-health-mcp auth afterwards: publishing does not extend a token already granted, and that one still expires after seven days.

4. Register with your MCP client

claude mcp add -s user google-health -- google-health-mcp

Running it with uvx instead: claude mcp add -s user google-health -- uvx google-health-mcp.

5. Check it

google-health-mcp doctor

Worth running before step 3 (Authorise) as well as after: it reports whether port 8081 can be bound and whether this host can open a browser, which are the two ways auth fails before it starts.

Offline and read-only: it reports which paths resolved where, whether the credential files are the right shape, whether the token is short-lived, and whether the cache is being kept up to date.

doctor --json reports the same findings for a monitor to act on:

{
  "version": "1.5.0",
  "findings": [
    {
      "check": "stopped-series",
      "name": "hrv series",
      "severity": "warn",
      "detail": "No hrv since 2026-03-30, after rows on 28 of the 30 days before that.",
      "fix": "Re-sync that type alone (...)"
    }
  ],
  "counts": {"ok": 7, "warn": 1, "fail": 0}
}

The payload goes to stdout; logging goes to stderr, so a subprocess consumer should read the two separately.

Match on check, never on name or detail: the first is a stable identifier, the other two are prose and carry the data type. check is null for findings nothing consumes programmatically yet.

The exit code is 1 only when something is graded fail, in both formats - a warning never changes it, which is the reason this flag exists: a stopped data series is a warning, so the exit code alone cannot tell you about the one failure most worth watching for.

Check version before trusting an absent check. A release older than this one omits the field entirely and an older one still rejects --json and exits 2, so "no stopped-series finding" and "this build cannot report one" look identical without it. version is itself null when the package is run from a source tree with no installed distribution metadata - the payload is still emitted, since a diagnostic that dies on a half-configured install is worthless exactly when it is needed.

The payload names the resolved config, database and credential paths, the same way the text report does. That is deliberate - it is what makes a wrong-path setup diagnosable - but a consumer that forwards the payload off the machine is disclosing them. No credential values appear in either format.

6. First sync (optional)

Query tools sync on first use each day, so you can skip this. To pre-populate the cache, or to pull history older than it:

google-health-mcp sync --days 30
google-health-mcp sync --since 2023-10-01     # backfill

CLI usage