mi-health-mcp

Описание проекта

mi-health-mcp предоставляет данные о сне, пульсе и шагах текущего вошедшего в аккаунт Xiaomi пользователя, а также авторизованных родственников, MCP-клиентам, таким как Hermes, по протоколу MCP. Сервис работает на Cloudflare Workers. Проект происходит из wusaki0723/mi-health-mcp, сохраняет лицензию GPL-3.0 и опирается на реализации интерфейсов из Misty02600/mi-fitness-python и shkyyy18/mi_fitness_data_bridge.

Related MCP server: boyuan-health-bridge

Развёртывание

Требуются Node.js 20 или новее и учётная запись Cloudflare.

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

Запишите namespace ID из вывода команды в kv_namespaces[0].id в wrangler.toml. KV namespace ID — это идентификатор ресурса Cloudflare, а не учётные данные; в публичном репозитории необходимо коммитить wrangler.toml, чтобы Workers Builds могли определить точку входа Worker и binding. После форка перед развёртыванием обязательно замените его на namespace ID из вашего аккаунта.

Затем задайте токен доступа и разверните:

npx wrangler secret put AUTH_TOKEN
npx wrangler deploy

Для AUTH_TOKEN используйте собственную длинную случайную строку; не записывайте её в исходный код, wrangler.toml или Git.

Вход с passToken

Рекомендуется задать userId, passToken и deviceId из браузерных Cookie Xiaomi Account как Cloudflare Secret. deviceId обычно начинается с wb_. Worker использует их для получения краткосрочной сессии health API с sid=miothealth; исходный passToken не записывается в KV, логи или ответы MCP.

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

Также можно добавить Secret с тем же именем в Cloudflare Dashboard в разделе Worker «Settings > Variables and Secrets». XIAOMI_USER_ID и XIAOMI_PASS_TOKEN должны быть заданы одновременно; XIAOMI_DEVICE_ID необязателен, при его задании используйте deviceId из той же браузерной сессии, в которой был получен этот passToken.

Имя привязки KV должно оставаться MI_HEALTH_KV. AUTH_TOKEN, XIAOMI_USER_ID и XIAOMI_PASS_TOKEN должны задаваться через Cloudflare Secret; не записывайте их в исходный код, файлы конфигурации или Git.

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

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

Замените URL на адрес вашего собственного развёрнутого Worker. Значение MI_HEALTH_AUTH_TOKEN должно совпадать с Secret AUTH_TOKEN этого Worker. Пример не содержит реальных учётных данных.

Навык Hermes

Файл skills/mi-health/SKILL.md в репозитории отвечает за направление запросов «я/сам пользователь» и «родственники» к правильным инструментам и объясняет значения полей компактных результатов. После публикации репозитория его можно установить по URL исходного файла:

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

Навык не создаёт автоматически запланированные задачи. Чтобы подключить его к существующей задаче, сначала проверьте задачу и недавние записи выполнения, затем добавьте по ID задачи:

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

Запланированные задачи выполняются в отдельной сессии; в prompt необходимо явно указать цель запроса, количество дней, часовой пояс, место отправки и способ обработки сбоев. Не помещайте в prompt никакие учётные данные; для периодических задач следует фиксировать provider и model, чтобы поведение не менялось при изменении глобальных значений по умолчанию.

Порядок использования

1. После настройки XIAOMI_USER_ID и XIAOMI_PASS_TOKEN вызовите health_login_refresh; XIAOMI_DEVICE_ID — необязательный Secret, позволяющий при необходимости указать браузерную сессию, в которой был получен этот passToken. Worker получает и кэширует сессию miothealth; при сбое текущая кэшированная сессия не удаляется.

2. Используйте health_me, чтобы подтвердить текущий аккаунт; для запроса отдельных исходных сводок вызывайте health_latest, health_sleep, health_heart или health_steps; если нужен анализ тенденций, в первую очередь вызывайте health_analyze и передавайте текущий IANA-часовой пояс пользователя.

3. При запросе родственников сначала вызовите health_relatives, затем передайте target: "relative" и полученный relative_uid.

health_login_start и health_login_poll сохранены только для совместимости. Этот процесс с QR-кодом на некоторых аккаунтах отклоняется Xiaomi с кодом 70036, а приложение 小米运动健康 может также сообщать, что QR-код не поддерживается; этот проект не описывает его как проверенный способ входа.

По умолчанию в запросах здоровья используется target: "self" — интерфейс данных самого пользователя, relative_uid не отправляется; для запроса родственников необходимо указать действительный relative_uid, автоматический выбор первого элемента из списка родственников не выполняется.

Инструменты MCP

• health_me: возвращает текущий статус входа и user_id, не возвращает учётные данные.

• health_login_status: возвращает, доступна ли текущая сессия health API, и способ входа; учётные данные не возвращаются.

• health_login_refresh: принудительно обновляет сессию, используя Secret аккаунта Xiaomi; при сбое сохраняет существующую кэшированную сессию.

• health_relatives: выводит список relative_uid и заметок для родственников, которых можно запрашивать.

• health_latest: запрашивает последние сводки по сну, пульсу и шагам.

• health_analyze: по умолчанию запрашивает 30 дней, строит личный базовый уровень на основе последних 7 полных дней и более ранних записей; отделяет незавершённую активность текущего дня, сообщает о пропущенных датах, задержке синхронизации, полноте стадий сна и качестве выборки пульса, выводит недиагностическую robust statistics.

• health_sleep: запрашивает ежедневные сводки по сну за последние 1–30 дней, не более одной записи в день.

• health_heart: запрашивает ежедневную статистику пульса за последние 1–30 дней, не возвращает все точки выборки.

• health_steps: запрашивает ежедневные сводки по шагам за последние 1–30 дней, не более одной записи в день.

При запросе собственных данных опустите target или явно передайте {"target":"self"}. При запросе родственников необходимо передать:

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

Пример анализа тенденций:

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

health_analyze не пересчитывает даты, уже возвращённые health API; timezone используется только для определения текущего календарного дня: шаги текущего дня и ежедневный пульс помечаются как partial и исключаются из базового уровня полных дней. Сон считается завершённой записью по дате пробуждения. Если на одну дату есть несколько сводок, анализатор детерминированно выбирает одну, сначала по валидности измерений, полноте выборки или стадий сна, затем по времени записи и стабильному ключу. recent_days задаёт окно последних календарных дней; пропущенные даты или даты, исключённые из-за недостаточного качества, не заменяются более ранними записями. Результат сначала возвращает data_quality: missing_dates означает, что запись за день отсутствует, missing_measurements — запись есть, но целевое значение пустое, нечисловое или отрицательное; оба случая обрабатываются как неизвестные, а не как 0. Результат также сообщает задержку синхронизации последних данных, полноту стадий сна и качество выборки пульса. Даты, где количество выборок ниже 50% медианы количества выборок полных дней, попадают в low_sample_dates; даты без валидного количества выборок — в unknown_sample_dates; обе категории не входят в тренд пульса. Для сравнения трендов используются неокруглённые median, MAD, IQR и robust z-score; округление выполняется только при выводе. При недостаточности выборки возвращается insufficient_data, а не навязывается вывод о тренде. Все сравнения являются сводками личной истории и не могут использоваться для диагностики заболеваний или рекомендаций по лекарствам.

Границы использования

Только для входа в ваш собственный аккаунт Xiaomi и запроса данных родственников, на которые вы получили разрешение. Не используйте проект в целях, нарушающих чью-либо приватность или условия пользовательского соглашения Xiaomi.

Для собственных данных используется POST /app/v1/data/get_fitness_data_by_time. Для китайского региона окно запроса расширяется на 18 часов в обе стороны, затем записи относятся к датам по их zone_offset; при отсутствии zone_offset используется UTC+8. Собственные записи steps сводятся по дням согласно инкрементальной семантике интерфейса; точки выборки heart преобразуются в ежедневную статистику; для sleep в один и тот же день приоритет отдаётся записи, которая не является коротким сном, имеет большую длительность и более позднее время обновления. Для данных родственников используется daily_report из /app/v1/relatives/*; записи одного дня не суммируются повторно.

Ответы MCP используют белый список полей и не возвращают AUTH_TOKEN, passToken, cUserId, serviceToken, ssecurity или Cookie. Не коммитьте .dev.vars, .env, wrangler.toml или .wrangler/.

Лицензия

Проект распространяется под GNU General Public License v3.0 (GPL-3.0), что соответствует лицензии вышестоящего проекта Misty02600/mi-fitness-python.