English version: README.en.md

Mi Bridge (Mi Fitness Data Bridge)

Локально-ориентированный мост данных, который экспортирует ваши собственные данные из приложения Xiaomi Mi Fitness в SQLite, JSON, CSV, Python и инструменты, совместимые с MCP.

Приложение Xiaomi Mi Fitness с радостью покажет вам ваши шаги, сон и пульс — но никогда не позволит забрать эти данные с собой. Этот мост помещает ваши собственные данные в файл SQLite на вашем собственном диске.

Товарный знак: Xiaomi, Mi Home, Mi Fitness являются товарными знаками Xiaomi Corporation. Этот проект является неофициальным сообществом и не имеет никакого отношения к Xiaomi Corporation и не одобрен ею.

Экспериментальный облачный адаптер может перестать работать в любой момент из-за изменений Xiaomi в частных интерфейсах. Используйте только с учётными записями и данными, к которым у вас есть право доступа.

Проверено на практике

Записано 2026-07-20 на Windows (Python 3.14) на основе коммита ветки main. Все данные синтетические, без каких-либо учётных данных или сетевого доступа. (Количество тестов повторно проверено и обновлено 2026-08-17.)

Тестовый набор:

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

Сквозная синтетическая демонстрация (examples/synthetic_demo.py сначала заполняет локальный кэш SQLite синтетическими записями, а затем запускает реальный конвейер экспорта JSON/CSV):

$ 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

Проект health-assistant объединён

Проект health-assistant (локально-ориентированная персональная панель здоровья: Strava, сон, состав тела, анализ питания) объединён в этот репозиторий, его исходный репозиторий архивирован. Перенесённые ресурсы находятся в каталоге docs/health-assistant/:

• analytics.py — эталонная реализация движка рекомендаций по тренировкам/восстановлению без зависимостей (7-дневная статистика тренировок, соотношение острой/хронической нагрузки, проверка готовности, ежедневные рекомендации по тренировкам).

• coaching_methodology.md — объяснимая методология велосипедного коучинга, состава тела и спортивного питания, лежащая в его основе.

• README.md — полные инструкции по миграции, включая намеренно не перенесённые части (панель FastAPI, конвейер Strava OAuth/Webhook, анализ фотографий приёмов пищи) и причины.

Что делает этот проект

• Читает данные Xiaomi Mi Fitness через экспериментальный облачный адаптер для китайского региона.

• Сохраняет нормализованные записи в локальную базу данных SQLite.

• Экспортирует переносимые JSON или CSV без учётных данных.

• Предоставляет локальные инструменты запросов MCP для личной автоматизации.

• Предоставляет переиспользуемую реализацию коннектора для нижестоящих проектов (например, персонального консультанта по снижению веса).

Он намеренно не предоставляет медицинские консультации, рекомендации по снижению веса, управляемый доступ к учётным записям или многопользовательские облачные сервисы.

Зачем нужен этот мост?

Поддерживаемые наборы данных

• Ежедневная активность: шаги, дистанция, активные калории и минуты активности.

• Записи сна и фазы сна.

• Записи тренировок.

• Измерения тела: вес и доступные поля состава тела.

• Сэмплы пульса, включая пульс в покое, когда доступен.

• SpO2, стресс и события аномального сердцебиения (зависит от наличия в учётной записи/устройстве).

Фактическая доступность зависит от устройства, региона учётной записи, прошивки и вышестоящих сервисов Xiaomi.

Установка

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]'

Конфигурация

Более безопасный интерактивный путь настройки позволяет избежать записи passToken в историю shell:

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

Когда доступно, учётные данные хранятся в локальной связке ключей (keyring). Некоторые запасные реализации keyring могут хранить ключи недостаточно безопасно; перед использованием ознакомьтесь с поведением keyring вашей операционной системы.

Как получить user_id и passToken

Этот мост использует учётные данные уровня учётной записи Xiaomi (та же сессия входа, что и в приложении Mi Home), выберите один из двух способов:

Способ 1: Ручное копирование в браузере

1. Откройте account.xiaomi.com в браузере и войдите в свою учётную запись Xiaomi (та же учётная запись, что и в приложении Xiaomi Mi Fitness).

2. Откройте инструменты разработчика (F12) → «Приложение / Application» → Cookies → https://account.xiaomi.com.

3. Скопируйте значения cookie userId и passToken и вставьте их при запросе mi-fitness-bridge setup.

Способ 2: Инструмент входа по QR-коду

Войдите один раз по QR-коду с помощью open-source mijia-api:

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

Состояние входа по умолчанию сохраняется в ~/.config/mijia-api/auth.json (на Windows — %USERPROFILE%\.config\mijia-api\auth.json); значения userId и passToken из него можно напрямую использовать в этом мосте — учётные данные уровня учётной записи Xiaomi универсальны для сервисов, и мост использует их для получения сессии Xiaomi Mi Fitness (sid=miothealth). Обратите внимание, что auth.json хранит учётные данные в открытом виде: после ввода userId и passToken в этот мост (системная связка ключей) рекомендуется удалить этот файл.

Примечания:

• passToken истекает; при сообщении doctor об ошибке аутентификации просто получите его заново по шагам выше.

• При использовании браузерного способа входите в систему в вашей обычной сетевой среде; частая или необычная активность может вызвать защиту учётной записи Xiaomi (слайдер/ SMS-верификация); при срабатывании защиты можно использовать способ с QR-кодом.

• Имена cookie и процесс входа основаны на проверке от 2026-08 и могут отличаться в зависимости от региона учётной записи, устройства или политики защиты; Xiaomi также может в любой момент изменить частные интерфейсы (см. экспериментальное заявление вверху).

• Эти два значения эквивалентны состоянию входа в вашу учётную запись; не разглашайте их и не коммитьте в Git.

Синхронизация

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

Или синхронизируйте только один набор данных:

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

База данных по умолчанию находится в каталоге данных пользователя платформы (определяется platformdirs). sync, export, serve, doctor поддерживают смену расположения через параметр --db или переменную окружения MI_FITNESS_DB_PATH, приоритет: командная строка > переменная окружения > расположение по умолчанию. Обратите внимание, что platformdirs на Windows не реагирует на переменную окружения LOCALAPPDATA; для настройки пути используйте два указанных выше способа:

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

Известные ограничения: инкрементальная синхронизация без параметра даты начинается со времени последней локальной записи; исправления или дополнения более ранней истории на вышестоящем сервере не подтягиваются автоматически; при необходимости явно перезапустите этот диапазон с более ранним --start-date (будет идемпотентно перезаписано, без дублирующих записей).

Экспорт

Создание переносимого JSON-файла:

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

Отдельный CSV-файл для каждого набора данных:

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

Фильтрация по набору данных и дате:

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

Экспортируемые файлы никогда не содержат сохранённый passToken Xiaomi, но содержат идентифицирующие столбцы, такие как user_id, в открытом виде — экспортируемые файлы являются чувствительными персональными данными, храните их надлежащим образом. Экспортированные записи о здоровье по умолчанию игнорируются Git.

Описание формата экспорта (структура JSON-конверта, структура CSV, правила фильтрации дат с закрытыми интервалами) см. в Export format.

MCP-сервис

Совместимая команда по-прежнему доступна:

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

Доступные инструменты включают запросы статуса подключения, синхронизации, покрытия, ежедневных сводок, измерений тела, сна, тренировок, пульса, SpO2 и стресса, а также ориентированный на агентов инструмент временных рядов тренировок workout_series — автоматическое понижение частоты дискретизации с жёстким верхним пределом max_points (усреднение по фиксированным временным интервалам, агрегация внутри SQLite), с честным указанием downsampled, source_points, returned_points, method в ответе, а также полной статистикой полной точности (avg/min/max/квантили) и временем в пульсовых зонах. Инструменты списков/сводок, такие как query_workouts, get_daily_summary, сопровождаются data_quality (количество покрытых дней, отсутствующие метрики, время последней синхронизации).

Пример подключения клиента (конфигурационный JSON для MCP-клиентов, таких как Claude Code / Codex):

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

Примечание: serve — это stdio-сервис, общающийся с клиентом через стандартный ввод-вывод, а не HTTP-сервис. Запуск его напрямую в терминале может выглядеть как «зависание» — это ожидание MCP-сообщений от клиента, что нормально; в повседневной работе запускайте его через MCP-клиент согласно конфигурации выше.

Использование в качестве Python-зависимости

Нормализованный адаптер по-прежнему доступен под совместимым именем модуля:

from mi_fitness_mcp.adapters.mi_fitness_cloud import MiFitnessCloudAdapter

Нижестоящие проекты должны устанавливать этот пакет, а не вендорить или копировать исходный код коннектора.

Лицензия

История лицензии: версии, выпущенные до 2026-08-03, лицензированы под MIT (атрибуция MIT вышестоящих kubulashvili/mi-fitness-mcp и binglua/mi-fitness-mcp-cn сохранена в блоке NOTICE вверху LICENSE); новый код текущей версии лицензирован под AGPL-3.0-only. Подробности см. в LICENSE и THIRD_PARTY_NOTICES.md.

Конфиденциальность и безопасность

• Надлежащим образом храните passToken, локальную базу данных, экспортируемые файлы и журналы, не разглашайте их.

• Экспортируемые файлы не содержат passToken, но содержат идентифицирующие столбцы, такие как user_id, в открытом виде — это также чувствительные персональные данные.

• Не запускайте этот мост как публичный прокси учётных данных.

• Не коммитьте реальные данные о здоровье или скриншоты с личными показателями.

• В отчётах об ошибках и документации всегда используйте синтетические данные.

• Это программное обеспечение предназначено только для доступа к личным данным и инженерных исследований, не для диагностики или лечения.

Ответственное раскрытие уязвимостей — см. SECURITY.md, происхождение — см. THIRD_PARTY_NOTICES.md.

Разработка

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

Релизы

История версий — в CHANGELOG.md, чек-лист релиза и пост-релизных проверок — в docs/release-checklist.md.

Связанные проекты

• garmin-mcp — локально-ориентированный MCP-сервис для данных Garmin. Разделяет с этим проектом контракт данных agent-safe-series/v1 (семантика полей понижения частоты дискретизации временных рядов побайтово совпадает), один и тот же AI-агент может без проблем потреблять данные обоих сервисов.

Поддержка проекта

Если этот инструмент вам помог, поставьте звезду на GitHub.