mi-health-mcp

Introducción del proyecto

mi-health-mcp proporciona los datos de sueño, frecuencia cardíaca y pasos de la cuenta de Xiaomi actualmente iniciada y de los familiares autorizados a clientes MCP como Hermes mediante el protocolo MCP. El servicio se ejecuta en Cloudflare Workers. Este proyecto deriva de wusaki0723/mi-health-mcp, conserva la licencia GPL-3.0 y hace referencia a las implementaciones de interfaz de Misty02600/mi-fitness-python y shkyyy18/mi_fitness_data_bridge.

Related MCP server: boyuan-health-bridge

Despliegue

Se requiere Node.js 20 o superior y una cuenta de 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

Escribe el namespace ID que genera el comando en kv_namespaces[0].id de wrangler.toml. El namespace ID de KV es un identificador de recurso de Cloudflare, no una credencial de acceso; los repositorios públicos deben hacer commit de wrangler.toml para que Workers Builds reconozca la entrada y el binding del Worker. Después de hacer fork, antes de desplegar, debes reemplazarlo por el namespace ID de tu propia cuenta.

Luego configura el token de acceso y despliega:

npx wrangler secret put AUTH_TOKEN
npx wrangler deploy

El valor de AUTH_TOKEN debe ser una cadena aleatoria larga generada por ti; no lo escribas en el código fuente, en wrangler.toml ni en Git.

Inicio de sesión con passToken

Se recomienda configurar como Cloudflare Secret los valores userId, passToken y deviceId de las cookies del navegador de Xiaomi Account. deviceId normalmente comienza con wb_. El Worker los usará para obtener una sesión de la API de salud de corta duración con sid=miothealth; el passToken original no se escribe en KV, en los registros ni en las respuestas MCP.

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

También puedes añadir Secrets con el mismo nombre en el Worker desde Cloudflare Dashboard en «Settings > Variables and Secrets». XIAOMI_USER_ID y XIAOMI_PASS_TOKEN deben configurarse juntos; XIAOMI_DEVICE_ID es opcional y, si se configura, debe usarse el deviceId de la misma sesión del navegador con la que se obtuvo ese passToken.

El nombre del binding de KV debe seguir siendo MI_HEALTH_KV. AUTH_TOKEN, XIAOMI_USER_ID y XIAOMI_PASS_TOKEN deben usarse como Cloudflare Secret; no los escribas en el código fuente, en archivos de configuración ni en Git.

Configuración de Hermes

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

Reemplaza la URL por la dirección del Worker que hayas desplegado. El valor de MI_HEALTH_AUTH_TOKEN debe coincidir con el Secret AUTH_TOKEN de ese Worker. El ejemplo no contiene credenciales reales.

Skill de Hermes

El archivo skills/mi-health/SKILL.md del repositorio se encarga de dirigir las solicitudes de «yo/mi cuenta» y «familiares» a la herramienta correcta, y explica el significado de los campos de los resultados compactos. Una vez que el repositorio sea público, se puede instalar desde la URL del archivo original:

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

El skill no crea tareas programadas automáticamente. Si necesitas conectarlo a una tarea existente, primero revisa la tarea y sus ejecuciones recientes, y luego añádelo por el ID de la tarea:

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

Las tareas programadas se ejecutan en una sesión independiente; el prompt debe especificar claramente el objetivo de la consulta, los días, la zona horaria, el lugar de envío y cómo manejar los fallos. No pongas ninguna credencial en el prompt; las tareas periódicas deben fijar el provider y el model para evitar que el comportamiento cambie si los valores predeterminados globales varían.

Flujo de uso

1. Tras configurar XIAOMI_USER_ID y XIAOMI_PASS_TOKEN, llama a health_login_refresh; XIAOMI_DEVICE_ID es un Secret opcional que se usa para especificar, cuando sea necesario, la sesión del navegador con la que se obtuvo ese passToken. El Worker obtiene y almacena en caché la sesión de miothealth; si falla, no elimina la sesión en caché actual.

2. Usa health_me para confirmar la cuenta actual; para consultar resúmenes originales individuales, llama a health_latest, health_sleep, health_heart o health_steps; si necesitas análisis de tendencias, prioriza health_analyze e indica la zona horaria IANA actual del usuario.

3. Para consultar a familiares, primero llama a health_relatives y luego pasa target: "relative" junto con el relative_uid devuelto.

health_login_start y health_login_poll se conservan solo por compatibilidad. Este flujo de código QR es rechazado por Xiaomi en algunas cuentas y devuelve 70036; la aplicación 小米运动健康 App también puede indicar que el código QR no es compatible. Este proyecto no lo describe como un método de inicio de sesión verificado y funcional.

Las consultas de salud usan por defecto target: "self", que utiliza la interfaz de datos propios y no envía relative_uid; las consultas de familiares deben proporcionar un relative_uid válido y no seleccionan automáticamente el primer elemento de la lista de familiares.

Herramientas MCP

• health_me: devuelve el estado de inicio de sesión actual y el user_id; no devuelve credenciales.

• health_login_status: devuelve si la sesión actual de la API de salud está disponible y el método de inicio de sesión; no devuelve credenciales.

• health_login_refresh: fuerza la renovación de la sesión usando los Secrets de la cuenta Xiaomi; si falla, conserva la sesión en caché existente.

• health_relatives: lista los relative_uid y las notas de los familiares que se pueden consultar.

• health_latest: consulta el resumen más reciente de sueño, frecuencia cardíaca y pasos.

• health_analyze: consulta 30 días por defecto y establece una línea base personal con los últimos 7 días completos y los registros anteriores; separa la actividad del día actual aún no finalizada, informa fechas faltantes, retraso de sincronización, integridad de las fases de sueño y calidad del muestreo de frecuencia cardíaca, y produce estadísticas robustas no diagnósticas.

• health_sleep: consulta el resumen diario de sueño de los últimos 1 a 30 días, como máximo una entrada por día.

• health_heart: consulta las estadísticas diarias de frecuencia cardíaca de los últimos 1 a 30 días; no devuelve todos los puntos de muestreo.

• health_steps: consulta el resumen diario de pasos de los últimos 1 a 30 días, como máximo una entrada por día.

Para consultar tus propios datos, omite target o pasa explícitamente {"target":"self"}. Para consultar a un familiar, debes pasar:

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

Ejemplo de análisis de tendencias:

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

health_analyze no recalcula las fechas ya devueltas por la API de salud; timezone solo se usa para identificar el día natural actual, marcando los pasos del día actual y la frecuencia cardíaca diaria como partial y excluyéndolos de la línea base de días completos. El sueño se considera un registro completado según la fecha de levantamiento. Cuando hay resúmenes duplicados para la misma fecha, el analizador selecciona uno de forma determinista priorizando la validez de las mediciones, la integridad del muestreo o de las fases de sueño, la hora del registro y la clave estable. recent_days representa la ventana de días naturales más recientes; las fechas faltantes o excluidas por calidad insuficiente no se rellenan con registros más antiguos. Los resultados devuelven primero data_quality: missing_dates indica que falta el registro de ese día, y missing_measurements indica que el registro existe pero el valor objetivo está vacío, no es numérico o es negativo; ambos se tratan como desconocidos, no como 0. Los resultados también informan el retraso de sincronización de los datos más recientes, la tasa de integridad de las fases de sueño y la calidad del muestreo de frecuencia cardíaca. Las fechas por debajo del 50 % de la mediana de muestras de los días completos se incluyen en low_sample_dates, y las fechas sin un número válido de muestras se incluyen en unknown_sample_dates; ninguna de ellas entra en la tendencia de frecuencia cardíaca. La comparación de tendencias usa la mediana, MAD, IQR y robust z-score sin redondear, y solo redondea al mostrar los resultados; si las muestras son insuficientes, devuelve insufficient_data sin forzar una conclusión de tendencia. Todas las comparaciones son resúmenes del historial personal y no pueden usarse para diagnosticar enfermedades ni recomendar medicamentos.

Límites de uso

Solo para iniciar sesión con tu propia cuenta de Xiaomi y consultar los datos de familiares que hayas autorizado. No lo uses para fines que vulneren la privacidad de otras personas o infrinjan el acuerdo de usuario de Xiaomi.

Los datos propios usan POST /app/v1/data/get_fitness_data_by_time. En la región de China, la ventana de consulta se amplía 18 horas antes y después, y luego los registros se asignan a la fecha según su zone_offset; si falta zone_offset, se recurre a UTC+8. Los registros de pasos propios se agregan por día según la semántica incremental de la interfaz; los puntos de muestreo de frecuencia cardíaca propios se convierten en estadísticas diarias; para el sueño, el mismo día se conserva preferentemente el registro que no sea siesta, tenga mayor duración y una hora de actualización más reciente. Los datos de familiares usan daily_report de /app/v1/relatives/*; los registros del mismo día no se suman repetidamente.

Las respuestas MCP usan una lista blanca de campos y no devuelven AUTH_TOKEN, passToken, cUserId, serviceToken, ssecurity ni cookies. No hagas commit de .dev.vars, .env, wrangler.toml ni .wrangler/.

Licencia

Este proyecto utiliza la GNU General Public License v3.0 (GPL-3.0), en línea con la licencia del proyecto upstream Misty02600/mi-fitness-python.