google-health-mcp

MCP-Server für die Google Health API mit lokalem SQLite-Cache und Trendanalyse.

Entwickelt für Claude Code und andere MCP-Clients. Ihre Daten werden in eine Datenbank auf Ihrem eigenen Rechner synchronisiert. Dadurch sind Abfragen schnell, funktionieren offline und verbrauchen kein API-Kontingent.

Eigenschaften

• Lokaler SQLite-Cache – einmal synchronisieren, sofort abfragen

• Inkrementelle Synchronisierung – jeder Lauf holt nur neue Daten und setzt dort fort, wo der letzte aufgehört hat

• Offline-Modus – Cache ohne Anmeldedaten und ohne Netzwerk ausliefern

• Trends – wöchentliche, monatliche oder vierteljährliche Aggregate und Zwei-Zeitraum-Vergleiche

• EKG – Messwerte vollständig gespeichert, einschließlich Wellenform, die nur auf Anfrage zurückgegeben werden

• doctor – diagnostiziert eine Installation offline und schreibgeschützt, ohne Kontingent zu verbrauchen

Related MCP server: google-health-mcp-server

Datentypen

Voraussetzungen

• Python 3.13+ (in CI auf 3.13 und 3.14 getestet)

• Ein Google-Konto mit Gesundheitsdaten und ein Google Cloud-Projekt für die Autorisierung. Es wird kein Abrechnungskonto benötigt – die Konsole bietet während der Einrichtung eine kostenlose Testphase an, die Sie vollständig ablehnen können.

Einrichtung

1. Installation

pip install google-health-mcp

Oder führen Sie es ohne Installation aus; dann wird jeder unten genannte google-health-mcp ...-Befehl zu uvx google-health-mcp ...:

uvx google-health-mcp --version

2. Google Cloud-Projekt erstellen

Jeder Benutzer registriert seinen eigenen OAuth-Client. Das sind sieben Konsolenschritte; die Seitennamen entsprechen dem Stand von Google im August 2026.

Googles eigene Einrichtungsseite leitet Sie woanders hin – befolgen Sie stattdessen die folgenden Schritte. Die Schnellstartanleitung erstellt einen Web-Client mit https://www.google.com als Redirect-URI. Das passt eher zum OAuth Playground als zu einem Programm auf Ihrem Rechner; dieser Server lehnt jene Datei ab und teilt das mit. Verwenden Sie diese Seite nur, um zu prüfen, ob eine der unten genannten Seiten umbenannt wurde.

1. Projekt. Erstellen Sie ein Projekt unter console.cloud.google.com/projectcreate und wählen Sie es aus.

2. API. Aktivieren Sie die Google Health API auf der Seite zur API-Aktivierung.

3. Erste Schritte. Öffnen Sie Google Auth Platform und schließen Sie Get started ab – App-Name, Support-E-Mail, Externe Zielgruppe, Kontakt-E-Mail. Ein neues Projekt hat bis dahin keine Seiten für Zielgruppe, Datenzugriff oder Clients.

4. Zielgruppe. Fügen Sie unter Testnutzer Ihr eigenes Google-Konto hinzu. Wenn Sie das überspringen, schlägt die Anmeldung mit 403: access_denied fehl.

5. Datenzugriff. Klicken Sie auf Bereiche hinzufügen oder entfernen, suchen Sie nach „Google Health API" und aktivieren Sie die unten unter OAuth-Bereiche aufgeführten Schreibschutz-Berechtigungen.

6. Clients. Erstellen Sie einen OAuth-Client vom Typ Desktop-App und laden Sie dessen JSON herunter. Ein Desktop-Client erlaubt die Loopback-Umleitung automatisch, sodass nichts zu registrieren ist; ein Web-Client tut das nicht und scheitert stattdessen bei der Zustimmung.

7. Veröffentlichen. Gehen Sie zurück zur Seite „Zielgruppe" und klicken Sie auf App veröffentlichen.

Schritt 7 ist der, der zwickt, und es lohnt sich, zu prüfen statt zu vermuten. Solange der Veröffentlichungsstatus einer App „Testing" ist, gibt Google Refresh-Tokens aus, die sieben Tage nach der Zustimmung ablaufen. Alles funktioniert also, und eine Woche später stoppt die Synchronisierung, ohne dass etwas auf diesen Moment zurückweist. Die Seite „Zielgruppe" kann „In production" anzeigen, während der Token-Server anderer Meinung ist. Zwei Angaben, die das nicht tun: die Zeile zum Verifizierungsstatus auf der Seite Branding und google-health-mcp doctor, das lautstark fehlschlägt, wenn der gespeicherte Token eine kurze Gültigkeitsdauer verzeichnet.

3. Autorisieren

Legen Sie die heruntergeladene Client-JSON-Datei unverändert an der Stelle ab, an der der Server danach sucht:

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

Ihr Browser wird warnen, dass Google diese App nicht verifiziert hat. Das ist zu erwarten, und die App ist Ihre eigene: Diese Gesundheits-Berechtigungen gelten als eingeschränkt, und die Verifizierung ist erst ab mehr als 100 Nutzern von Bedeutung. Klicken Sie auf Erweitert und dann auf Weiter zu google-health-mcp (unsicher), und erteilen Sie die Berechtigungen.

Der Ablauf lauscht für den Rückruf auf localhost:8081; dieser Port muss also frei sein. Die Tokens werden mit 0600-Berechtigungen in ~/.config/google-health-mcp/google_tokens.json gespeichert. Zugriffstokens halten eine Stunde und werden automatisch erneuert. Refresh-Tokens rotieren nicht, sodass ein auf einem Rechner mit Browser erzeugter Token auf einen Rechner ohne Browser kopiert werden kann.

Wenn Sie die App vor der Veröffentlichung autorisiert haben, führen Sie anschließend google-health-mcp auth erneut aus: Eine Veröffentlichung verlängert einen bereits erteilten Token nicht, und dieser läuft weiterhin nach sieben Tagen ab.

4. Bei Ihrem MCP-Client registrieren

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

Stattdessen mit uvx ausführen: claude mcp add -s user google-health -- uvx google-health-mcp.

5. Prüfen

google-health-mcp doctor

Es lohnt sich, dies sowohl vor Schritt 3 (Autorisieren) als auch danach auszuführen: Es meldet, ob Port 8081 frei ist und ob dieser Host einen Browser öffnen kann – das sind die beiden Wege, auf denen auth scheitert, bevor es überhaupt beginnt.

Offline und schreibgeschützt: Es meldet, welche Pfade sich wo aufgelöst haben, ob die Anmeldedatensätze die richtige Form haben, ob der Token nur kurzlebig ist und ob der Cache aktuell gehalten wird.

6. Erste Synchronisierung (optional)

Abfrage-Tools synchronisieren bei der ersten Nutzung jedes Tages; Sie können diesen Schritt also überspringen. Um den Cache vorab zu füllen oder ältere Verläufe nachzuziehen:

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

CLI-Nutzung

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

Abfrage-Tools synchronisieren bei der ersten Abfrage jedes Tages je Datentyp und lesen dann aus dem Cache.

Alle Abfrage-Tools außer health_get_devices und health_get_lifetime_stats, die keine Argumente entgegennehmen, akzeptieren:

• start_date – YYYY-MM-DD, YYYY-MM oder 30d (relativ). Standard: die letzten 30 Tage.

• end_date – YYYY-MM-DD. Standard: heute.

• live – wenn true, wird dieses Zeitfenster vor dem Lesen des Caches erneut von der API geholt. Ein fehlgeschlagenes Aktualisieren wird gemeldet, statt stillschweigend aus dem Cache zu antworten.

health_get_exercises akzeptiert außerdem exercise_type, einen case-insensitiven Teilstring-Abgleich auf den Namen der Trainingseinheit. health_get_ecg akzeptiert außerdem include_waveform: Eine Aufzeichnung besteht aus Tausenden von Spannungswerten, daher enthält die Standardantwort stattdessen Klassifikation, durchschnittliche Herzfrequenz, Dauer und eine Stichprobenanzahl.

health_sync

• data_types – all oder eine durch Kommas getrennte Teilmenge der oben unter CLI-Nutzung aufgeführten Namen (irn sind die Benachrichtigungen zu unregelmäßigem Rhythmus). Standard: all.

• days – Tage Verlauf für eine erste Synchronisierung (Standard: 30). Spätere Synchronisierungen sind inkrementell.

• since / until – ein exaktes Zeitfenster holen, unabhängig davon, was im Cache liegt.

health_trends

• data_type – ein beliebiger gecachter Typ mit einer Tagesreihe; EKG-Messwerte und Rhythmusmeldungen sind Ereignisse und haben keinen Trend. Standard: activity.

• period – weekly, monthly, quarterly. Standard: monthly.

• start_date / end_date – Standard: die letzten 12 Monate.

• compare – zwei Zeiträume, z. B. last_30d vs previous_30d, 2026-03 vs 2026-02, 2026-Q1 vs 2025-Q4. Wenn gesetzt, werden period, start_date und end_date ignoriert.

OAuth-Bereiche

Aktivieren Sie auf der Seite „Datenzugriff" diese Schreibschutz-Berechtigungen. Alle liegen unter https://www.googleapis.com/auth/googlehealth.:

location.readonly und profile.readonly sind zwei von der Konsole angebotene Berechtigungen, die dieses Paket bewusst nicht anfordert, weil hier nichts von ihnen liest – die erste ist die bei einer Trainingseinheit aufgezeichnete GPS-Spur.

Lesen Sie die Liste aus der Konsole ab, nicht von der veröffentlichten Berechtigungsseite – es gibt Schreibschutz-Berechtigungen, die weder in Googles Dokumentation noch im Discovery-Dokument der API selbst erscheinen, und das Discovery-Dokument lässt nutrition.readonly gänzlich aus. Um weniger anzufordern, aktivieren Sie auf der Seite „Datenzugriff" weniger und bearbeiten Sie GOOGLE_SCOPES in config.py vor der Autorisierung; dafür ist ein Quellcode-Checkout erforderlich statt einer Installation per pip oder uvx. Eine erteilte Genehmigung erhält bei der Erneuerung keine zusätzlichen Berechtigungen; die Liste später zu erweitern, bedeutet also, auth erneut auszuführen.

Konfiguration

Offline-/Cache-only-Modus

Standardmäßig synchronisiert der Server bei Bedarf, daher ist kein Cron-Job erforderlich. Setzen Sie GOOGLE_HEALTH_MCP_OFFLINE=1, um stattdessen als reiner Leser zu laufen:

• Es sind keine Anmeldedaten erforderlich – der Server öffnet die Token-Datei nie.

• Es wird kein Netzwerkaufruf durchgeführt. Auto-Sync ist deaktiviert, und live=True, health_get_devices und health_sync geben eine klare Meldung "Offline-Modus" zurück, anstatt die API zu erreichen.

• Abfragetools bedienen den Cache, gekennzeichnet mit "offline_mode": true.

Typische Anwendungsfälle:

• Mehrere Maschinen, ein Cache – Ein Host führt google-health-mcp sync per cron oder systemd gegen eine gemeinsame Datenbank aus; die anderen setzen GOOGLE_HEALTH_MCP_OFFLINE=1, richten GOOGLE_HEALTH_MCP_DB_PATH auf dieselbe Datei und lesen nur.

• CI und Datenschutz – Abfragen ohne Netzwerkzugriff und ohne Anmeldedaten ausführen.

Ratenlimits

Google wendet ein Pro-Benutzer-Anfragekontingent an, dokumentiert unter developers.google.com/health/rate-limits. Normales Synchronisieren liegt weit davon entfernt: Ein Tagesupdate besteht aus einer Handvoll Anfragen, und ein gemessener Drei-Jahres-Backfill aller Datentypen lag bei etwa 250. Wenn eine Synchronisierung abgebrochen wird, wird dieser Datentyp als partielle Synchronisierung erfasst und der nächste Lauf setzt an seinem Cursor fort, anstatt von vorn zu beginnen.

Abfragen aus dem Cache – die Standardeinstellung – kosten überhaupt kein Kontingent.

Datensicherheit

Ihre Gesundheitsdaten bleiben auf Ihrem Rechner: Dieser Server hat kein Backend, sendet nichts irgendwohin und kommuniziert nur mit der Google-API über Ihre eigenen Anmeldedaten.

Das Repository wird mit einem Pre-Commit-Hook ausgeliefert, der sich weigert, Datenbankdateien, alles unter config/ und große Dateien zu committen; CONTRIBUTING.md erklärt, wie man ihn installiert.

Importieren vorhandener Daten

Wenn Sie bereits Gesundheitsdaten als JSON-Dateien haben, etwa aus einem Export oder einem eigenen Skript:

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

Erwartete Dateinamen: heart_rate.json, activity.json, exercises.json, sleep.json, weight.json, spo2.json, hrv.json. Siehe src/google_health_mcp/importer.py für die erwartete Struktur jeder Datei. Der Import deckt diese sieben Typen ab; alles andere kommt per sync.

Mitwirken

Siehe CONTRIBUTING.md für die Entwicklungseinrichtung, den Test-Workflow und den Pre-Commit-Hook. Änderungen werden in CHANGELOG.md festgehalten.

Lizenz

GPL-3.0-or-later