Versión en inglés: README.en.md

米桥（Mi Fitness Data Bridge）

Puente de datos local primero, que exporta tus propios datos de 小米运动健康 a SQLite, JSON, CSV, Python y herramientas compatibles con MCP.

La aplicación 小米运动健康 se complace en mostrarte tus pasos, sueño y frecuencia cardíaca, pero nunca te deja llevarte esos datos. Este puente coloca tus propios datos en un archivo SQLite en tu propio disco duro.

Aviso de marca: 小米, 米家 y Mi Fitness son marcas comerciales de 小米公司. Este proyecto es un proyecto comunitario no oficial, sin afiliación ni respaldo de 小米公司.

El adaptador de nube experimental puede dejar de funcionar en cualquier momento porque 小米 cambia interfaces privadas. Úsalo solo con cuentas y datos a los que tengas derecho de acceso.

Verificación en la práctica

Grabado el 2026-07-20 en Windows (Python 3.14) basado en el commit de la rama main. Todos los datos son sintéticos, sin credenciales ni acceso a la red. (El número de pruebas se revisó y actualizó el 2026-08-17).

Suite de pruebas:

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

Demostración sintética de extremo a extremo (examples/synthetic_demo.py primero llena la caché SQLite local con registros sintéticos, luego ejecuta el pipeline real de exportación 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

Proyecto health-assistant fusionado

El proyecto health-assistant (panel de salud personal local primero: Strava, sueño, composición corporal, análisis de dieta) se ha fusionado en este repositorio, y su repositorio original se ha archivado. Los activos absorbidos se encuentran en el directorio docs/health-assistant/:

• analytics.py — implementación de referencia del motor de resumen y recomendaciones de entrenamiento/recuperación sin dependencias (estadísticas de entrenamiento de 7 días, ratio de carga aguda/crónica, verificación de preparación, recomendaciones diarias de entrenamiento).

• coaching_methodology.md — la metodología explicable detrás de él: entrenador de ciclismo, composición corporal y nutrición deportiva.

• README.md — instrucciones completas de migración, incluyendo las partes que no se portaron intencionalmente (panel FastAPI, pipeline OAuth/Webhook de Strava, análisis de fotos de comidas) y las razones.

Qué hace este proyecto

• Lee datos de 小米运动健康 a través de un adaptador de nube experimental para la región de China.

• Almacena los registros normalizados en una base de datos SQLite local.

• Exporta JSON o CSV portátiles sin credenciales.

• Expone herramientas de consulta MCP locales para automatización personal.

• Proporciona una implementación de conector reutilizable para proyectos posteriores (por ejemplo, un asesor personal de pérdida de grasa).

Deliberadamente no proporciona consejos médicos, orientación para perder peso, acceso a cuentas alojadas o servicios en la nube multiusuario.

¿Por qué hacer este puente?

Conjuntos de datos admitidos

• Actividad diaria: pasos, distancia, calorías activas y minutos de actividad.

• Registros de sueño y etapas del sueño.

• Registros de ejercicio.

• Mediciones corporales: peso y campos de composición corporal disponibles.

• Muestras de frecuencia cardíaca, incluida la frecuencia cardíaca en reposo cuando esté disponible.

• SpO2, estrés y eventos de latidos anormales (según disponibilidad de cuenta/dispositivo).

La disponibilidad real varía según el dispositivo, la región de la cuenta, el firmware y los servicios upstream de 小米.

Instalación

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

Configuración

Una ruta de configuración interactiva más segura evita escribir el passToken directamente en el historial del shell:

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

Cuando esté disponible, las credenciales se almacenan en el llavero local (keyring). Algunas implementaciones alternativas de keyring pueden almacenar claves de forma no suficientemente segura; infórmate sobre el comportamiento del keyring de tu sistema operativo antes de usarlo.

Cómo obtener user_id y passToken

Este puente utiliza credenciales a nivel de cuenta de 小米 (el mismo estado de inicio de sesión que la aplicación 米家), elige una de las siguientes dos formas:

Método 1: Copia manual desde el navegador

1. Abre account.xiaomi.com en el navegador e inicia sesión con tu cuenta de 小米 (la misma cuenta que la aplicación 小米运动健康).

2. Abre las herramientas de desarrollador (F12) → "Aplicación / Application" → Cookies → https://account.xiaomi.com.

3. Copia los valores de las cookies userId y passToken, y pégalos cuando mi-fitness-bridge setup lo solicite.

Método 2: Herramienta de inicio de sesión con código QR

Usa el mijia-api de código abierto para iniciar sesión con código QR una vez:

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

El estado de inicio de sesión se guarda por defecto en ~/.config/mijia-api/auth.json (en Windows, %USERPROFILE%\.config\mijia-api\auth.json), y el userId y passToken de allí se pueden usar directamente en este puente: las credenciales a nivel de cuenta de 小米 son comunes entre servicios, y el puente las usará para obtener una sesión de 小米运动健康 (sid=miothealth). Ten en cuenta que auth.json guarda las credenciales en texto plano: después de ingresar userId y passToken en este puente (llavero del sistema), se recomienda eliminar ese archivo.

Nota:

• El passToken caduca; cuando doctor informe un fallo de autenticación, vuelve a obtenerlo siguiendo los pasos anteriores.

• Para el método del navegador, inicia sesión en tu red habitual; operaciones frecuentes o desde ubicaciones diferentes pueden activar el control de riesgos de la cuenta de 小米 (verificación por deslizador/SMS). Si encuentras control de riesgos, puedes usar el método de código QR.

• Los nombres de cookies y el flujo de inicio de sesión se basan en pruebas reales de 2026-08, y pueden variar según la región de la cuenta, el dispositivo o las políticas de control de riesgos; 小米 también puede ajustar interfaces privadas en cualquier momento (ver el aviso experimental en la parte superior).

• Estos dos valores equivalen al estado de inicio de sesión de tu cuenta; no los divulgues ni los envíes a Git.

Sincronización

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

O sincroniza solo un conjunto de datos:

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

La base de datos se coloca por defecto en el directorio de datos de usuario de la plataforma (determinado por platformdirs). sync, export, serve y doctor admiten cambiar la ubicación con el parámetro --db o la variable de entorno MI_FITNESS_DB_PATH, con prioridad: línea de comandos > variable de entorno > ubicación predeterminada. Ten en cuenta que platformdirs no responde a la variable de entorno LOCALAPPDATA en Windows; para personalizar la ruta, usa los dos métodos anteriores:

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

Limitación conocida: la sincronización incremental sin parámetros de fecha comienza desde la hora del último registro local; las correcciones o adiciones de historial anterior por parte del upstream no se obtienen automáticamente. Si es necesario, vuelve a ejecutar explícitamente ese rango con un --start-date anterior (sobrescribe de forma idempotente, sin duplicar registros).

Exportación

Genera un archivo JSON portátil:

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

Genera un archivo CSV para cada conjunto de datos:

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

Filtra por conjunto de datos y fecha:

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

Los archivos exportados nunca contienen el passToken de 小米 guardado, pero sí incluyen columnas identificativas como user_id en texto plano: los archivos exportados son datos personales sensibles, guárdalos con cuidado. Los registros de salud exportados están ignorados por Git por defecto.

La descripción del formato de exportación (estructura de sobre JSON, diseño CSV, reglas de filtrado de fechas de intervalo cerrado) se encuentra en Export format.

Servicio MCP

El comando compatible sigue disponible:

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

Las herramientas disponibles incluyen estado de conexión, sincronización, cobertura, resumen diario, mediciones corporales, sueño, ejercicio, frecuencia cardíaca, SpO2 y consultas de estrés, así como la herramienta de series de ejercicio workout_series orientada a agentes: reduce automáticamente la muestra según el límite máximo max_points (promedio por intervalos de tiempo fijos, agregación en SQLite), y marca honestamente en la respuesta downsampled, source_points, returned_points, method, además de proporcionar estadísticas de precisión completa (avg/min/max/percentiles) y tiempo en zonas de frecuencia cardíaca. Las herramientas de listado/resumen como query_workouts, get_daily_summary incluyen data_quality (días cubiertos, métricas faltantes, última hora de sincronización).

Ejemplo de integración de cliente (JSON de configuración para clientes MCP como Claude Code / Codex):

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

Nota: serve es un servicio stdio que se comunica con el cliente a través de la entrada/salida estándar, no es un servicio HTTP. Ejecutarlo directamente en la terminal parecerá "atascado": está esperando mensajes MCP del cliente, lo cual es normal; en el uso diario, deja que el cliente MCP lo inicie según la configuración anterior.

Uso como dependencia de Python

El adaptador normalizado sigue disponible bajo el nombre de módulo compatible:

from mi_fitness_mcp.adapters.mi_fitness_cloud import MiFitnessCloudAdapter

Los proyectos posteriores deben instalar este paquete, en lugar de vender o copiar el código fuente del conector.

Licencia

Historial de licencias: las versiones publicadas antes del 2026-08-03 usan la licencia MIT (la atribución MIT de los upstream kubulashvili/mi-fitness-mcp y binglua/mi-fitness-mcp-cn se conserva en el bloque NOTICE en la parte superior de LICENSE); el código nuevo de la versión actual usa AGPL-3.0-only. Consulta LICENSE y THIRD_PARTY_NOTICES.md para más detalles.

Privacidad y seguridad

• Guarda cuidadosamente el passToken, la base de datos local, los archivos exportados y los registros; no los divulgues.

• Los archivos exportados no contienen el passToken, pero incluyen columnas identificativas como user_id en texto plano, que también son datos personales sensibles.

• No ejecutes este puente como un proxy de credenciales público.

• No envíes datos de salud reales ni capturas de pantalla que contengan métricas personales.

• Usa siempre datos sintéticos en informes de errores y documentación.

• Este software es solo para acceso a datos personales e investigación de ingeniería, no para diagnóstico o tratamiento.

La divulgación responsable se describe en SECURITY.md, y la atribución de fuentes en THIRD_PARTY_NOTICES.md.

Desarrollo

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

Publicación

El historial de versiones se encuentra en CHANGELOG.md, y los elementos de verificación de publicación y posteriores a la publicación en docs/release-checklist.md.

Proyectos relacionados

• garmin-mcp — servicio MCP de datos Garmin local primero. Comparte con este proyecto el contrato de datos agent-safe-series/v1 (semántica de campos de reducción de muestras de series temporales alineada byte a byte), y el mismo agente de IA puede consumir datos de ambos servicios sin problemas.

Apoya este proyecto

Si esta herramienta te ha sido útil, dame una estrella en GitHub.