mi-health-mcp

Projektübersicht

mi-health-mcp stellt die Schlaf-, Herzfrequenz- und Schrittdaten des aktuell angemeldeten 小米-Kontos sowie der autorisierten Verwandten über das MCP-Protokoll für MCP-Clients wie Hermes bereit. Der Dienst läuft auf Cloudflare Workers. Dieses Projekt stammt von wusaki0723/mi-health-mcp, behält die GPL-3.0-Lizenz bei und orientiert sich bei der Schnittstellenimplementierung an Misty02600/mi-fitness-python und shkyyy18/mi_fitness_data_bridge.

Related MCP server: boyuan-health-bridge

Bereitstellung

Erforderlich sind Node.js 20 oder höher sowie ein Cloudflare-Konto.

git clone https://github.com/<your-github-account>/mi-health-mcp.git
cd mi-health-mcp
npm install
npx wrangler login
npx wrangler kv namespace create MI_HEALTH_KV

Schreibe die vom Befehl ausgegebene Namespace-ID in kv_namespaces[0].id in der wrangler.toml. Die KV-Namespace-ID ist eine Cloudflare-Ressourcenkennung und keine Zugangsberechtigung; öffentliche Repositorys müssen wrangler.toml committen, damit Workers Builds den Worker-Einstiegspunkt und das Binding erkennen. Nach einem Fork muss die Namespace-ID vor der Bereitstellung durch die des eigenen Kontos ersetzt werden.

Dann Zugriffstoken festlegen und bereitstellen:

npx wrangler secret put AUTH_TOKEN
npx wrangler deploy

Verwende für AUTH_TOKEN einen selbst erzeugten langen Zufallsstring und schreibe ihn nicht in den Quellcode, in wrangler.toml oder in Git.

passToken-Anmeldung

Es wird empfohlen, userId, passToken und deviceId aus dem Browser-Cookie des Xiaomi-Kontos als Cloudflare Secret zu setzen. deviceId beginnt normalerweise mit wb_. Der Worker tauscht sie gegen eine kurzlebige Health-API-Session mit sid=miothealth ein; das ursprüngliche passToken wird nicht in KV, Logs oder MCP-Antworten geschrieben.

npx wrangler secret put XIAOMI_USER_ID
npx wrangler secret put XIAOMI_PASS_TOKEN
npx wrangler secret put XIAOMI_DEVICE_ID

Alternativ kann im Cloudflare Dashboard unter Worker „Settings > Variables and Secrets“ ein gleichnamiges Secret hinzugefügt werden. XIAOMI_USER_ID und XIAOMI_PASS_TOKEN müssen zusammen gesetzt werden; XIAOMI_DEVICE_ID ist optional und sollte die deviceId aus derselben Browser-Sitzung verwenden, in der das passToken erlangt wurde.

Der Name des KV-Bindings muss MI_HEALTH_KV bleiben. AUTH_TOKEN, XIAOMI_USER_ID und XIAOMI_PASS_TOKEN müssen als Cloudflare Secret gesetzt werden und dürfen nicht in Quellcode, Konfigurationsdateien oder Git geschrieben werden.

Hermes-Konfiguration

mcp_servers:
  mi_health:
    url: "https://<worker-name>.<account-subdomain>.workers.dev/mcp"
    headers:
      Authorization: "Bearer ${MI_HEALTH_AUTH_TOKEN}"

Ersetze die URL durch die Adresse deines eigenen bereitgestellten Workers. Der Wert von MI_HEALTH_AUTH_TOKEN muss mit dem AUTH_TOKEN-Secret dieses Workers übereinstimmen. Das Beispiel enthält keine echten Zugangsdaten.

Hermes-Skill

Die Datei skills/mi-health/SKILL.md im Repository leitet Anfragen für „ich/selbst“ und „Verwandte“ an das richtige Tool weiter und erläutert die Bedeutung der Felder der kompakten Ergebnisse. Sobald das Repository öffentlich ist, kann es über die URL der Originaldatei installiert werden:

hermes skills install https://raw.githubusercontent.com/<your-github-account>/mi-health-mcp/main/skills/mi-health/SKILL.md
hermes skills list

Das Skill erstellt keine geplanten Aufgaben automatisch. Wenn es mit einer vorhandenen Aufgabe verbunden werden soll, prüfe zuerst die Aufgabe und die letzten Ausführungsprotokolle und füge es dann anhand der Aufgaben-ID hinzu:

hermes cron status
hermes cron list
hermes cron runs <job-id>
hermes cron edit <job-id> --add-skill mi-health

Geplante Aufgaben werden in einer unabhängigen Sitzung ausgeführt. Der Prompt muss das Abfrageziel, die Anzahl der Tage, die Zeitzone, den Sendestandort und das Vorgehen bei Fehlern klar angeben. Gib keine Zugangsdaten in den Prompt; für regelmäßige Aufgaben sollten provider und model festgelegt werden, damit sich das Verhalten nicht ändert, wenn sich globale Standardwerte ändern.

Verwendung

1. Nach dem Konfigurieren von XIAOMI_USER_ID und XIAOMI_PASS_TOKEN health_login_refresh aufrufen; XIAOMI_DEVICE_ID ist ein optionales Secret, um bei Bedarf die Browser-Sitzung anzugeben, in der das passToken erlangt wurde. Der Worker tauscht die miothealth-Session ein und speichert sie im Cache; bei einem Fehler wird die aktuell gecachte Session nicht gelöscht.

2. Mit health_me das aktuelle Konto bestätigen; für einzelne Rohzusammenfassungen health_latest, health_sleep, health_heart oder health_steps aufrufen; für Trendanalysen bevorzugt health_analyze aufrufen und die aktuelle IANA-Zeitzone des Benutzers übergeben.

3. Für Abfragen zu Verwandten zuerst health_relatives aufrufen und dann target: "relative" sowie die zurückgegebene relative_uid übergeben.

health_login_start und health_login_poll sind nur aus Kompatibilitätsgründen beibehalten. Der QR-Code-Ablauf wird bei manchen Konten von Xiaomi abgelehnt und gibt 70036 zurück; auch die 小米运动健康 App kann melden, dass der QR-Code nicht unterstützt wird. Dieses Projekt beschreibt ihn nicht als verifiziert nutzbare Anmeldemethode.

Gesundheitsabfragen verwenden standardmäßig target: "self" und die Datenschnittstelle der eigenen Person; relative_uid wird nicht gesendet. Für Abfragen zu Verwandten muss eine gültige relative_uid angegeben werden; das erste Element der Verwandtenliste wird nicht automatisch ausgewählt.

MCP-Tools

• health_me: Gibt den aktuellen Anmeldestatus und user_id zurück, keine Zugangsdaten.

• health_login_status: Gibt zurück, ob die aktuelle Health-API-Session verfügbar ist, sowie die Anmeldemethode; keine Zugangsdaten.

• health_login_refresh: Erzwingt die Aktualisierung der Session mit dem 小米-Konto-Secret; bei einem Fehler bleibt die vorhandene Cache-Session erhalten.

• health_relatives: Listet die relative_uid und Notizen der abfragbaren Verwandten auf.

• health_latest: Fragt die neuesten Zusammenfassungen von Schlaf, Herzfrequenz und Schritten ab.

• health_analyze: Fragt standardmäßig 30 Tage ab und erstellt eine persönliche Baseline aus den letzten 7 vollständigen Tagen und früheren Aufzeichnungen; trennt die noch nicht abgeschlossene Aktivität des aktuellen Tages ab, meldet fehlende Daten, Synchronisationsverzögerung, Vollständigkeit der Schlafphasen und Qualität der Herzfrequenzmessungen und liefert nicht-diagnostische robuste Statistiken.

• health_sleep: Fragt die täglichen Schlafzusammenfassungen der letzten 1 bis 30 Tage ab, höchstens ein Eintrag pro Tag.

• health_heart: Fragt die täglichen Herzfrequenzstatistiken der letzten 1 bis 30 Tage ab, ohne alle Messpunkte zurückzugeben.

• health_steps: Fragt die täglichen Schrittzusammenfassungen der letzten 1 bis 30 Tage ab, höchstens ein Eintrag pro Tag.

Für Abfragen der eigenen Person kann target weggelassen oder explizit {"target":"self"} übergeben werden. Für Abfragen zu Verwandten muss Folgendes übergeben werden:

{
  "target": "relative",
  "relative_uid": "...",
  "days": 7
}

Beispiel für eine Trendanalyse:

{
  "target": "self",
  "days": 30,
  "recent_days": 7,
  "timezone": "Europe/Berlin"
}

health_analyze berechnet die von der Health-API bereits zurückgegebenen Daten nicht neu; timezone dient nur dazu, den aktuellen Kalendertag zu erkennen, die Schritte des aktuellen Tages und die tägliche Herzfrequenz als partial zu markieren und von der Baseline der vollständigen Tage auszuschließen. Schlaf wird anhand des Aufwachdatums als abgeschlossene Aufzeichnung betrachtet. Wenn für dasselbe Datum mehrere Zusammenfassungen vorliegen, wählt der Analysator deterministisch eine anhand von gültigen Messwerten, Vollständigkeit der Messungen oder Schlafphasen, Aufzeichnungszeit und stabilem Schlüssel aus. recent_days bezeichnet das Fenster der letzten Kalendertage; fehlende oder wegen unzureichender Qualität ausgeschlossene Daten werden nicht durch frühere Aufzeichnungen ersetzt. Die Ergebnisse geben zuerst data_quality zurück: missing_dates bedeutet, dass die Aufzeichnung für den Tag fehlt; missing_measurements bedeutet, dass die Aufzeichnung vorhanden ist, der Zielwert jedoch leer, nicht numerisch oder negativ ist; beide werden als unbekannt behandelt und nicht als 0. Die Ergebnisse melden außerdem die Synchronisationsverzögerung der neuesten Daten, die Vollständigkeitsrate der Schlafphasen und die Qualität der Herzfrequenzmessungen. Daten, deren Stichprobenanzahl unter 50 % des Medians der Stichprobenanzahl vollständiger Tage liegt, werden in low_sample_dates aufgeführt; Daten ohne gültige Stichprobenanzahl in unknown_sample_dates; beide fließen nicht in den Herzfrequenztrend ein. Für Trendvergleiche werden ungerundete Median, MAD, IQR und robuste Z-Scores verwendet; gerundet wird erst bei der Ausgabe. Bei unzureichenden Stichproben wird insufficient_data zurückgegeben, ohne eine erzwungene Trendaussage zu treffen. Alle Vergleiche sind persönliche historische Zusammenfassungen und nicht für die Diagnose von Krankheiten oder Medikationsempfehlungen geeignet.

Nutzungsgrenzen

Nur für die Anmeldung mit deinem eigenen 小米-Konto und die Abfrage von Daten deiner autorisierten Verwandten. Nicht für Zwecke verwenden, die die Privatsphäre anderer verletzen oder gegen die 小米-Nutzungsbedingungen verstoßen.

Für eigene Daten wird POST /app/v1/data/get_fitness_data_by_time verwendet. Für die China-Region wird das Abfragefenster um jeweils 18 Stunden vor und nach dem Zeitraum erweitert und die Daten werden anhand des zone_offset der Aufzeichnung dem Datum zugeordnet; fehlt zone_offset, wird auf UTC+8 zurückgegriffen. Eigene Schrittdatensätze werden gemäß der inkrementellen Semantik der Schnittstelle pro Tag summiert; eigene Herzfrequenz-Messpunkte werden in tägliche Statistiken umgewandelt; bei Schlafdaten desselben Tages werden bevorzugt Aufzeichnungen beibehalten, die kein Nickerchen sind, eine längere Dauer und einen neueren Aktualisierungszeitpunkt haben. Für Verwandtendaten wird daily_report unter /app/v1/relatives/* verwendet; Datensätze desselben Tages werden nicht doppelt summiert.

MCP-Antworten verwenden eine Feld-Whitelist und geben AUTH_TOKEN, passToken, cUserId, serviceToken, ssecurity oder Cookies nicht zurück. Bitte committe keine .dev.vars, .env, wrangler.toml oder .wrangler/.

Lizenz

Dieses Projekt steht unter der GNU General Public License v3.0 (GPL-3.0) und bleibt damit mit der Lizenz des Upstream-Projekts Misty02600/mi-fitness-python konsistent.