Mi Bridge (Mi Fitness Data Bridge)

Eine lokal orientierte Datenbrücke, die deine eigenen Xiaomi Fitness- & Gesundheitsdaten nach SQLite, JSON, CSV sowie in MCP-kompatible Werkzeuge exportiert.

Die Xiaomi Fitness- & Gesundheits-App zeigt dir gerne deine Schritte, deinen Schlaf und deine Herzfrequenz – aber sie lässt dich diese Daten nie mitnehmen. Diese Brücke bringt deine eigenen Daten in eine eigene SQLite-Datei auf deiner eigenen Festplatte.

Markenrechtlicher Hinweis: Xiaomi, Mijia und Mi Fitness sind Marken der Xiaomi Corporation. Dieses Projekt ist ein inoffizielles Community-Projekt und steht in keiner Verbindung zu Xiaomi und wird von Xiaomi nicht unterstützt.

Experimenteller Hinweis: Der Cloud-Adapter kann jederzeit ausfallen, da Xiaomi seine proprietären Schnittstellen ändern kann. Verwende ihn nur mit Konten und Daten, auf die du zugriffsberechtigt bist.

Verifiziert durch echte Tests

Aufgenommen am 2026-07-20 unter Windows (Python 3.14) basierend auf dem main-Branch-Commit. Alle Daten sind synthetische Daten, keine echten Anmeldeinformationen und kein Netzwerkzugriff. (Anzahl der Tests erneut geprüft am 2026-08-17.)

Testsuite:

$ python -m pytest -q -p no:cacheprovider
........................................................................ [ 96%]
...                                                                      [100%]
75 passed in 10.27s

End-to-End-Synthese-Demo (examples/synthetic_demo.py füllt zuerst den lokalen SQLite-Cache mit synthetischen Datensätzen und führt dann echte JSON/CSV-Exporte durch):

$ python examples/synthetic_demo.py
Seeded synthetic database: C:\Users\<you>\AppData\Local\Temp\mi-fitness-demo-53el7cfh\mi_fitness.db
  daily_activity: 2026-07-15 .. 2026-07-15 (1 day(s))
  sleep: 2026-07-14 .. 2026-07-14 (1 day(s))
  workouts: 2026-07-15 .. 2026-07-15 (1 day(s))
  body_measurements: 2026-07-15 .. 2026-07-15 (1 day(s))

Export completed
  mi_fitness.json
  daily_activity.csv
  sleep.csv
  workouts.csv
  body_measurements.csv
  heart_rate.csv
  spo2.csv
  stress.csv
  abnormal_heart_beat.csv

JSON envelope:
  schema_version: 1.0
  source: mi_fitness_data_bridge
  records.daily_activity: 1 row(s)
  records.sleep: 1 row(s)
  records.workouts: 1 row(s)
  records.body_measurements: 1 row(s)

Sample sleep row (synthetic):
  start_at=2026-07-14T23:20:00 end_at=2026-07-15T07:05:00
  duration_minutes=465 score=86
  stages=[{"stage": "deep", "minutes": 82}, {"stage": "light", "minutes": 271}, {"stage": "rem", "minutes": 88}, {"stage": "awake", "minutes": 24}]

Related MCP server: garmin-givemydata

Zusammengeführtes health-assistant-Projekt

Das health-assistant-Projekt (lokal orientiertes persönliches Health-Dashboard: Strava, Schlaf, Körperzusammensetzung, Ernährungsanalyse) wurde in dieses Repository zusammengeführt, das ursprüngliche Repository wurde archiviert. Die übernommenen Inhalte befinden sich in docs/health-assistant/:

• analytics.py – Referenzimplementierung einer trainingsfreien Erholungszusammenfassung und Empfehlungs-Engine (7-Tage-Trainingsstatistik, akute/chronische Belastungsquote, Bereitschaftsprüfung, tägliche Trainingsempfehlungen).

• coaching_methodology.md – Die erklärbare Methodik dahinter: Radsport-Coaching, Körperzusammensetzung und Sporternährung.

• README.md – Vollständige Migrationsbeschreibung, einschließlich der bewusst nicht übernommenen Teile (FastAPI-Dashboard, Strava-OAuth/Webhook-Pipeline, Essensfoto-Analyse) und der Gründe dafür.

Was dieses Projekt tut

• Über einen experimentellen Cloud-Adapter für die chinesische Region Xiaomi Fitness- & Gesundheitsdaten abrufen.

• Normalisierte Datensätze in einer lokalen SQLite-Datenbank speichern.

• Tragbare JSON- oder CSV-Dateien ohne Anmeldeinformationen exportieren.

• Lokale MCP-Abfragewerkzeuge für persönliche Automatisierung bereitstellen.

• Eine wiederverwendbare Konnektorimplementierung für nachgelagerte Projekte (z. B. persönliche Fettreduktionsberater) bereitstellen.

Es bietet bewusst keine medizinische Beratung, keine Abnehmhilfe, keinen kontenbasierten Mehrbenutzerzugriff und keinen Cloud-Dienst.

Warum diese Brücke?

Unterstützte Datensätze

• Tägliche Aktivitäten: Schritte, Distanz, Aktivitätskalorien und aktive Minuten.

• Schlafaufzeichnungen und Schlafphasen.

• Trainingsaufzeichnungen.

• Körpermessungen: Gewicht und verfügbare Körperzusammensetzungsfelder.

• Herzfrequenzproben, einschließlich Ruheherzfrequenz, sofern verfügbar.

• Blutsauerstoff (SpO2), Stress und abnormale Herzschlagereignisse (sofern vom Konto/der Region/dem Gerät unterstützt).

Die tatsächliche Verfügbarkeit hängt von Gerät, Kontoregion, Firmware und den vorgelagerten Xiaomi-Diensten ab.

Installation

git clone https://github.com/shkyyy18/mi-bridge.git mi_fitness_data_bridge
cd mi_fitness_data_bridge
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Windows Git Bash:

source .venv/Scripts/activate
pip install -e ".[dev]"

macOS/Linux:

source .venv/bin/activate
pip install -e '.[dev]'

Konfiguration

Der sicherere interaktive Konfigurationspfad vermeidet, dass passToken in der Shell-Historie landet:

mi-fitness-bridge setup
mi-fitness-bridge doctor

Wenn verfügbar, werden Anmeldeinformationen im Schlüsselbund des Betriebssystems (keyring) gespeichert. Einige keyring-Backends speichern Schlüssel jedoch möglicherweise nicht sicher – informiere dich vor der Verwendung über das keyring-Verhalten deines Betriebssystems.

So erhältst du user_id und passToken

Diese Brücke verwendet Anmeldeinformationen auf Xiaomi-Kontoebene (dieselbe Anmeldesitzung wie die Mijia-App). Wähle eine der beiden folgenden Methoden:

Methode 1: Manuelles Kopieren aus dem Browser

1. Öffne account.xiaomi.com im Browser und melde dich mit deinem Xiaomi-Konto an (dasselbe Konto wie in der Xiaomi Fitness- & Gesundheits-App).

2. Öffne die Entwicklertools (F12) → "Anwendung / Application" → Cookies → https://account.xiaomi.com.

3. Kopiere die Werte von userId und passToken und füge sie ein, wenn mi-fitness-bridge setup danach fragt.

Methode 2: QR-Code-Login-Tool

Verwende das Open-Source-Tool mijia-api für einen einmaligen QR-Code-Login:

pip install mijiaAPI
python -c "from mijiaAPI import mijiaAPI; mijiaAPI().login()"   # 终端出二维码，用米家 App 扫码

Der Login-Status wird standardmäßig in ~/.config/mijia-api/auth.json gespeichert (unter Windows: %USERPROFILE%\.config\mijia-api\auth.json). Die darin enthaltenen userId- und passToken-Werte können direkt mit dieser Brücke verwendet werden – Xiaomi-Kontoanmeldeinformationen sind dienstübergreifend gültig, und die Brücke verwendet sie, um eine Sitzung für Xiaomi Fitness & Health (sid=miothealth) zu erhalten. Hinweis: auth.json speichert Anmeldeinformationen im Klartext: Nachdem du userId und passToken in diese Brücke (Schlüsselbund des Betriebssystems) eingegeben hast, wird empfohlen, diese Datei zu löschen.

Hinweise:

• passToken läuft ab; wenn doctor einen Authentifizierungsfehler meldet, wiederhole einfach die obigen Schritte, um neue Werte zu erhalten.

• Verwende für die Browsermethode am besten deine übliche Netzwerkumgebung; häufige oder ortsfremde Anmeldeversuche können die Xiaomi-Konto-Sicherheitsprüfung auslösen (Slider-/SMS-Verifizierung). Falls die Sicherheitsprüfung ausgelöst wird, verwende stattdessen die QR-Code-Methode.

• Cookie-Name und Anmeldeablauf basieren auf Tests vom 2026-08 und können je nach Kontoregion, Gerät oder Sicherheitsrichtlinien abweichen; Xiaomi kann seine proprietären Schnittstellen auch jederzeit anpassen (siehe experimentellen Hinweis oben).

• Diese beiden Werte entsprechen deinem angemeldeten Konto – gib sie nicht weiter und committe sie nicht in Git.

Synchronisierung

mi-fitness-bridge sync --start-date 2026-07-01 --end-date 2026-07-15

Oder synchronisiere nur einen einzelnen Datensatz:

mi-fitness-bridge sync --type sleep --start-date 2026-07-01 --end-date 2026-07-15
mi-fitness-bridge sync --type body_measurements --start-date 2026-07-01 --end-date 2026-07-15

Die Datenbank liegt standardmäßig im benutzerspezifischen Datenverzeichnis der Plattform (durch platformdirs bestimmt). sync, export, serve und doctor unterstützen alle die Angabe eines anderen Speicherorts über den --db-Parameter oder die Umgebungsvariable MI_FITNESS_DB_PATH. Priorität: Befehlszeilenparameter > Umgebungsvariable > Standardverzeichnis. Hinweis: platformdirs berücksichtigt auf Windows die Umgebungsvariable LOCALAPPDATA nicht; für einen benutzerdefinierten Pfad verwende eine der beiden oben genannten Methoden.

mi-fitness-bridge sync --db ./data/mi_fitness.db --start-date 2026-07-01 --end-date 2026-07-15
export MI_FITNESS_DB_PATH=./data/mi_fitness.db

Bekannte Einschränkung: Die inkrementelle Synchronisierung ohne Datumsangabe beginnt beim Zeitstempel des letzten lokalen Datensatzes; Korrekturen oder Nachträge für frühere Zeiträume auf der Serverseite werden nicht automatisch abgerufen. Verwende bei Bedarf ein früheres --start-date, um den Zeitraum explizit erneut zu synchronisieren (die Synchronisierung ist idempotent und überschreibt ohne Duplikate).

Export

Erzeugt eine tragbare JSON-Datei:

mi-fitness-bridge export --format json --output exports/mi_fitness.json

Erzeugt eine CSV-Datei pro Datensatztyp:

mi-fitness-bridge export --format csv --output exports/csv

Nach Datensatztyp und Datumsbereich filtern:

mi-fitness-bridge export --format json --type sleep \
  --start-date 2026-07-01 --end-date 2026-07-15 \
  --output exports/sleep.json

Exportdateien enthalten niemals das gespeicherte Xiaomi-passToken, enthalten jedoch Klartext-Identifikationsspalten wie user_id – Exportdateien sind sensible personenbezogene Daten und entsprechend sorgfältig aufzubewahren. Exportierte Gesundheitsdatensätze sind standardmäßig in Git ignoriert.

Details zum Exportformat (JSON-Envelope-Struktur, CSV-Layout, Regeln für die Filterung inklusiver Datumsbereiche) findest du unter Exportformat.

MCP-Dienst

Der kompatible Befehl ist weiterhin verfügbar:

mi-fitness-bridge serve
# legacy alias
mi-fitness-mcp serve

Verfügbare Werkzeuge umfassen Verbindungsstatus, Synchronisierung, Abdeckung, Tageszusammenfassung, Körpermessungen, Schlaf, Training, Herzfrequenz, Blutsauerstoff (SpO2) und Stressabfragen sowie das für Agenten entwickelte Werkzeug workout_series für Trainingszeitreihen – es führt automatisch ein Downsampling gemäß dem harten Limit max_points durch (feste Zeit-Bucket-Mittelwerte, Aggregation in SQLite) und kennzeichnet in der Antwort ehrlich downsampled, source_points, returned_points und method, zusammen mit Statistiken in voller Präzision (avg/min/max/Perzentile) und Zeitanteilen in Herzfrequenzzonen. Listen-/Zusammenfassungswerkzeuge wie query_workouts und get_daily_summary enthalten zusätzlich data_quality (abgedeckte Tage, fehlende Metriken, letzter Synchronisierungszeitpunkt).

Beispiel für die Client-Integration (Konfigurations-JSON für MCP-Clients wie Claude Code / Codex):

{
  "mcpServers": {
    "mi-bridge": {
      "command": "mi-fitness-bridge",
      "args": ["serve"]
    }
  }
}

Hinweis: serve ist ein stdio-Dienst, der über Standardeingabe/-ausgabe mit dem Client kommuniziert, kein HTTP-Dienst. Wenn du ihn direkt im Terminal ausführst, scheint er "hängen zu bleiben" – das liegt daran, dass er auf MCP-Nachrichten des Clients wartet und ist normales Verhalten; im Alltag startest du ihn über den MCP-Client mit der obigen Konfiguration.

Als Python-Abhängigkeit verwenden

Der normalisierte Adapter ist weiterhin unter dem kompatiblen Modulnamen verfügbar:

from mi_fitness_mcp.adapters.mi_fitness_cloud import MiFitnessCloudAdapter

Nachgelagerte Projekte sollten dieses Paket installieren, anstatt den Konnektor-Quellcode zu vendoren oder zu kopieren.

Lizenz

Lizenzhistorie: Versionen, die vor dem 2026-08-03 veröffentlicht wurden, stehen unter der MIT-Lizenz (die MIT-Anerkennungen der vorgelagerten Projekte kubulashvili/mi-fitness-mcp und binglua/mi-fitness-mcp-cn sind im NOTICE-Block oben in LICENSE erhalten); der neu hinzugefügte Code der aktuellen Version steht unter AGPL-3.0-only. Siehe LICENSE und THIRD_PARTY_NOTICES.md.

Datenschutz & Sicherheit

• Bewahre passToken, die lokale Datenbank, Exportdateien und Protokolle sorgfältig auf und gib sie nicht weiter.

• Exportdateien enthalten kein passToken, enthalten jedoch Klartext-Identifikationsspalten wie user_id – auch sie sind sensible personenbezogene Daten.

• Betreibe diese Brücke nicht als öffentlichen Anmeldeinformations-Proxy.

• Committe keine echten Gesundheitsdaten oder Screenshots mit persönlichen Metriken.

• Verwende in Fehlerberichten und Dokumentation ausschließlich synthetische Daten.

• Diese Software dient ausschließlich dem persönlichen Datenzugriff und der technischen Forschung, nicht der Diagnose oder Behandlung.

Verantwortungsvolle Offenlegung: siehe SECURITY.md; Herkunftsnachweise: siehe THIRD_PARTY_NOTICES.md.

Entwicklung

pip install -e '.[dev]'
python -m pytest -q -p no:cacheprovider
python -m ruff check src tests

Veröffentlichung

Versionshistorie siehe CHANGELOG.md; Veröffentlichungs- und Nachveröffentlichungs-Checkliste siehe docs/release-checklist.md.

Verwandte Projekte

• garmin-mcp – Lokal orientierter MCP-Dienst für Garmin-Daten. Teilt mit diesem Projekt den Datenvertrag agent-safe-series/v1 (die Semantik der Downsampling-Felder für Zeitreihen ist bytegenau identisch), sodass derselbe KI-Agent nahtlos Daten beider Dienste konsumieren kann.

Unterstütze dieses Projekt

Wenn dir dieses Werkzeug geholfen hat, gib mir auf GitHub einen Stern.