Metadata-Version: 2.4
Name: google-health-mcp
Version: 1.7.0
Summary: MCP server for the Google Health API, with a local cache and trend analysis.
Author-email: jjdelrio <641373+partymola@users.noreply.github.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/partymola/google-health-mcp
Project-URL: Repository, https://github.com/partymola/google-health-mcp
Project-URL: Bug Tracker, https://github.com/partymola/google-health-mcp/issues
Keywords: google-health,mcp,model-context-protocol,health,fitness,sleep
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==2.2.0
Requires-Dist: anyio==4.15.1
Provides-Extra: dev
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
Requires-Dist: ruff==0.16.9; extra == "dev"
Dynamic: license-file

# google-health-mcp

<!-- mcp-name: io.github.partymola/google-health-mcp -->

[![CI](https://github.com/partymola/google-health-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/partymola/google-health-mcp/actions/workflows/ci.yml)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/google-health-mcp)](https://pypi.org/project/google-health-mcp/)
[![Glama MCP Server](https://glama.ai/mcp/servers/partymola/google-health-mcp/badges/score.svg)](https://glama.ai/mcp/servers/partymola/google-health-mcp)

MCP server for the [Google Health API](https://developers.google.com/health), with a local SQLite cache and trend analysis.

Designed for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and other [MCP](https://modelcontextprotocol.io/) 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

| Tool | Data |
|------|------|
| `health_get_heart_rate` | Resting heart rate |
| `health_get_activity` | Steps, calories, distance, floors |
| `health_get_exercises` | Workouts: name, duration, heart rate, calories, Google's metrics summary, and splits on request |
| `health_get_exercise_route` | One workout's GPS route, as the TCX file Google exports |
| `health_get_sleep` | Duration, stages, sleep period |
| `health_get_sleep_sessions` | Each session as Google recorded it: metadata, summary, and every stage segment on request |
| `health_get_weight` | Weight, body fat %, one row a day |
| `health_get_weight_readings` | Every weigh-in and body-fat reading, as Google recorded each one |
| `health_get_height` | Height readings |
| `health_get_spo2` | Nightly blood oxygen saturation |
| `health_get_hrv` | Heart rate variability (RMSSD) |
| `health_get_azm` | Active zone minutes, with the per-zone breakdown |
| `health_get_breathing_rate` | Nightly breaths per minute |
| `health_get_skin_temperature` | Nightly variation from your baseline, and the absolutes behind it |
| `health_get_core_temperature` | Body temperature readings you logged by hand |
| `health_get_cardio_fitness` | VO2 max, where the device reports it |
| `health_get_food_log` | Food calories and water, where logged |
| `health_get_ecg` | Electrocardiograms: classification, average rate, duration, waveform on request |
| `health_get_irregular_rhythm` | Irregular-rhythm notifications and the windows that triggered them |
| `health_get_devices` | Paired devices, battery level, last sync |
| `health_get_profile` | Your profile, settings and irregular-rhythm enrolment, as Google returns them |
| `health_get_lifetime_stats` | Totals and best days over the cached history, with its coverage |
| `health_trends` | Aggregated averages and period comparisons |

## 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

```bash
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 ...`:

```bash
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](https://developers.google.com/health/setup) 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](https://console.cloud.google.com/projectcreate) and select it.
2. **API.** Enable **Google Health API** on the [API Enablement page](https://console.cloud.google.com/apis/library/health.googleapis.com).
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](#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:

```bash
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.

If you have more than one Google account, pick the one your health data is in. `auth` checks the account once the tokens are saved, and if Google reports it is not linked to Google Health, it says so and exits 1; run it again and choose the other account.

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

```bash
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

```bash
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, whether the grant holds every permission this version reads, and whether the cache is being kept up to date.

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

```json
{
  "version": "1.7.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:

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

## CLI usage

```
google-health-mcp                Start the MCP server (stdio transport)
google-health-mcp -V, --version  Print the installed package version
google-health-mcp auth           Interactive OAuth setup
google-health-mcp doctor         Check the setup and report what needs fixing
  --json                Emit the findings as JSON, for a monitor rather than
                        a person. Each finding carries a stable `check` name
                        to match on; the exit code is the same either way.
google-health-mcp sync           Sync data to the local cache
  --days N              Days of history for a first sync (default: 30)
  --types TYPE,...      Data types to sync (default: all). One or more of:
                        heart_rate, activity, exercises, sleep, weight, spo2,
                        hrv, azm, breathing_rate, skin_temperature,
                        core_temperature, cardio_fitness, food_log, ecg, irn,
                        account, height, exercise_routes, sleep_sessions,
                        weight_readings, body_fat_readings
  --since YYYY-MM-DD    Fetch from this date, ignoring the incremental cursor
  --until YYYY-MM-DD    Inclusive end date for a --since window; together they
                        re-fetch exactly that window, to repair a gap in the
                        middle of the cache
google-health-mcp import         Import exported JSON data files
  --data-dir PATH       Directory containing the JSON files
```

## MCP tool reference

Query tools sync on the first query of each day per data type, then read the cache.

All query tools except `health_get_devices`, `health_get_lifetime_stats`, `health_get_profile` and `health_get_exercise_route` accept:

- `start_date` - `YYYY-MM-DD`, `YYYY-MM`, or `30d` (relative). Default: last 30 days, except `health_get_height`, whose default is the last ten years.
- `end_date` - `YYYY-MM-DD`. Default: today.
- `live` - if true, re-fetch this window from the API before reading the cache. A failed refresh is reported rather than silently answered from the cache.

`health_get_profile` takes only `live`.

`health_get_exercises` also takes `exercise_type`, a case-insensitive substring match on the workout name. Google names the workouts, so a value matching no workout name in your cache is refused with the cached names listed and the `live=True` hint, rather than answered as a period you did not train in. It also takes `include_detail`: without it each workout carries how many exercise events, splits and split summaries it has, rather than every one. `health_get_ecg` also takes `include_waveform`: a trace is thousands of voltages, so the default response carries the classification, average rate, duration and a sample count instead. `health_get_sleep_sessions` also takes `include_stages`, for the same reason: without it each session carries how many stage segments, short awakenings and out-of-bed segments it has, rather than every one.

`health_get_exercise_route` takes a workout's `log_id`. The route text comes back only with `include_tcx`, since it can run to hundreds of kilobytes. Only workouts recorded with GPS have a route, and a sync fetches routes for the workouts in its own window, so an older one needs `health_sync` with `data_types="exercise_routes"` and `since`. A route holds every position you recorded, start and end included: it is cached on disk like the rest, and reaches the model only when `include_tcx` is set.

**If your authorisation lacks a permission this version reads**, every successful tool response carries an `authorisation` note naming it, `doctor` reports it under the check `missing-scopes`, and `sync` prints it. The data types read under it are skipped rather than failed, so `sync` still exits 0. A grant does not gain permissions on refresh, so this is what an upgrade that adds one looks like until you run `google-health-mcp auth` again. `doctor` on the syncing host sees the new grant straight away; the tool note, and `doctor` on a cache-only host, catch up once the next sync has run. Run `google-health-mcp sync` after authorising to fetch the newly granted data at once; a query tool otherwise waits for the next day, since a skipped type counts as synced for that day.

### health_sync

- `data_types` - `all`, or a comma-separated subset of the names listed under [CLI usage](#cli-usage) above (`irn` is the irregular-rhythm notifications, and `account` is the profile, settings and irregular-rhythm enrolment). Default: `all`.
- `days` - days of history for a first sync (default: 30). Later syncs are incremental.
- `since` / `until` - fetch an exact window regardless of what is cached.

**A sync adds and corrects, and never removes.** An entry deleted in the app it was logged in simply stops appearing in the API, with nothing to say it was deleted, so a re-sync of that window leaves the cached row as it was. The API offers no tombstone, no change feed and no modified-since filter, so there is nothing to detect it by. In practice this reaches only the types you fill in by hand, since a device series is not deleted after the fact. Re-creating the cache is the way to clear one.

### health_trends

- `data_type` - any cached type with a daily series; ECG readings and rhythm alerts are episodes, and sleep sessions and individual readings are records, so they have no trend. Default: `activity`.
- `period` - `weekly`, `monthly`, `quarterly`. Default: `monthly`.
- `start_date` / `end_date` - default: the last 12 months.
- `compare` - two periods, e.g. `last_30d vs previous_30d`, `2026-03 vs 2026-02`, `2026-Q1 vs 2025-Q4`. When set, `period`, `start_date` and `end_date` are ignored.

## OAuth scopes

Tick these read-only scopes on the Data Access page. All are under `https://www.googleapis.com/auth/googlehealth.`:

| Scope | Data accessed |
|-------|--------------|
| `activity_and_fitness.readonly` | Steps, distance, floors, calories, workouts, active zone minutes |
| `health_metrics_and_measurements.readonly` | Heart rate, HRV, SpO2, breathing rate, weight, body fat, height, temperature, VO2 max |
| `sleep.readonly` | Sleep sessions and stages |
| `nutrition.readonly` | Food and water logs |
| `ecg.readonly` | Electrocardiograms |
| `irn.readonly` | Irregular-rhythm notifications and enrolment |
| `settings.readonly` | Paired devices, units and time zone |
| `profile.readonly` | Age, membership start, stride lengths |
| `location.readonly` | GPS routes of workouts |

The console also offers `reproductive_health.readonly`, `logged_symptoms.readonly` and `mindfulness.readonly`, which this package does not request. As of September 2026 the cycle, ovulation-test, symptom and mood data types can be written but not read, and the API has no mindfulness data type, so there is nothing to read under them.

**Read the list off the console, not off the published scope page** - read-only scopes exist that appear in neither Google's documentation nor the API's own discovery document, and the discovery document omits `nutrition.readonly` outright. To request fewer, tick fewer on the Data Access page and remove them from `GOOGLE_SCOPE_READERS` in `config.py` before authorising, which needs a source checkout rather than a `pip` or `uvx` install; the data types under a scope you leave out are skipped by every sync. A grant does not gain scopes on refresh, so widening the list later means running `auth` again.

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `GOOGLE_HEALTH_MCP_CONFIG_DIR` | `~/.config/google-health-mcp/` | Directory holding the OAuth client and tokens |
| `GOOGLE_HEALTH_MCP_DB_PATH` | `~/.local/share/google-health-mcp/google_health.db` | SQLite cache |
| `GOOGLE_HEALTH_MCP_OFFLINE` | unset | If truthy (`1`, `true`, `yes`, `on`), run as a cache-only reader |

### Offline / cache-only mode

By default the server syncs on demand, so no cron job is needed. Set `GOOGLE_HEALTH_MCP_OFFLINE=1` to run as a pure reader instead:

- No credentials are required - the server never opens the token file.
- No network call is made. Auto-sync is off, and `live=True`, `health_get_devices` and `health_sync` return a clear "offline mode" message rather than reaching the API.
- Query tools serve the cache, tagged `"offline_mode": true`.

Typical uses:

- **Several machines, one cache** - one host runs `google-health-mcp sync` from cron or systemd against a shared database; the others set `GOOGLE_HEALTH_MCP_OFFLINE=1`, point `GOOGLE_HEALTH_MCP_DB_PATH` at the same file, and only read.
- **CI and privacy** - run queries with no network access and no credentials.

## Rate limits

Google applies a per-user request quota, documented at [developers.google.com/health/rate-limits](https://developers.google.com/health/rate-limits). Ordinary syncing is nowhere near it: a day's update is a handful of requests, and a measured three-year backfill of every data type was around 250. If a sync is cut short, that data type is recorded as a partial sync and the next run resumes from its cursor rather than starting over.

Querying from the cache - the default - costs no quota at all.

## Data safety

Your health data stays on your machine: this server has no backend, sends nothing anywhere, and talks only to Google's API with your own credentials.

The repository ships a pre-commit hook that refuses to commit database files, anything under `config/`, and large files; [CONTRIBUTING.md](https://github.com/partymola/google-health-mcp/blob/main/CONTRIBUTING.md) says how to install it.

## Importing existing data

If you already have health data as JSON files, from an export or a script of your own:

```bash
google-health-mcp import --data-dir /path/to/json/files/
```

Expected file names: `heart_rate.json`, `activity.json`, `exercises.json`, `sleep.json`, `weight.json`, `spo2.json`, `hrv.json`. See `src/google_health_mcp/importer.py` for the shape each one expects. Import covers those seven types; everything else arrives by `sync`.

## Contributing

See [CONTRIBUTING.md](https://github.com/partymola/google-health-mcp/blob/main/CONTRIBUTING.md) for development setup, the test workflow, and the pre-commit hook. Changes are tracked in [CHANGELOG.md](https://github.com/partymola/google-health-mcp/blob/main/CHANGELOG.md).

## License

[GPL-3.0-or-later](https://github.com/partymola/google-health-mcp/blob/main/LICENSE)
