Content
# Zepp Life (Mi Fit) MCP Server
Un servidor MCP (Model Context Protocol) escrito en Python con FastMCP para leer y consultar los datos de tu cuenta de **Zepp Life** (anteriormente Mi Fit) de Xiaomi / Huami.
## Características
El servidor expone herramientas para consultar los siguientes datos:
* **Dispositivos:** Listado de dispositivos vinculados con su MAC, estado y clave de vinculación Bluetooth (`auth_key`).
* **Peso (Weight):** Historial de peso y composición corporal (IMC, masa grasa, masa muscular, agua, masa ósea, etc.) directo desde la báscula inteligente.
---
## Requisitos Previos
* Python 3.9 o superior
* Una cuenta de Zepp Life / Mi Fit
---
## Configuración y Autenticación
El servidor requiere credenciales para acceder a la API de Zepp. Tienes dos opciones para configurarlo en tu archivo `.env`:
### Opción A: Usar Token de Aplicación y ID de Usuario (Recomendada)
Esta opción es la más estable ya que no sufre de bloqueos por límite de peticiones ni retos de captcha en el login.
Para obtener tu `ZEPP_APP_TOKEN` y `ZEPP_USER_ID`:
1. Instala un proxy de interceptación HTTPS en tu ordenador (por ejemplo, [mitmproxy](https://mitmproxy.org/), [Charles Proxy](https://www.charlesproxy.com/) o [HTTP Toolkit](https://httptoolkit.com/)).
2. Configura tu móvil para que envíe el tráfico a través del proxy.
3. Abre la app Zepp Life en tu móvil y sincroniza tus datos.
4. En los logs del proxy, busca peticiones dirigidas a dominios como `api-mifit.zepp.com` o `api-mifit.huami.com`.
5. Extrae los valores de las cabeceras HTTP:
* `apptoken` (se usará como `ZEPP_APP_TOKEN`)
* `userid` o el parámetro en la URL del ID del usuario (se usará como `ZEPP_USER_ID`)
### Opción B: Inicio de Sesión con Email y Contraseña
Si no deseas interceptar el tráfico, el servidor puede intentar iniciar sesión automáticamente usando tu correo y contraseña:
* `ZEPP_EMAIL`: El email de tu cuenta Zepp Life.
* `ZEPP_PASSWORD`: La contraseña de tu cuenta Zepp Life.
---
## Instalación y Configuración Local
1. Crea un entorno virtual e instala las dependencias:
```bash
python -m venv .venv
.venv/Scripts/activate # En Windows (.venv/bin/activate en macOS/Linux)
pip install -r requirements.txt
```
2. Copia el archivo `.env.example` a `.env` y rellena las variables elegidas:
```bash
copy .env.example .env
```
3. Prueba el servidor en modo desarrollo (con recarga en caliente e inspector web):
```bash
.venv/Scripts/fastmcp dev server.py
```
Esto abrirá una interfaz web del inspector en `http://localhost:5173` donde podrás probar las herramientas directamente.
---
## Herramientas Disponibles (MCP Tools) y Cómo Llamarlas
El servidor expone las siguientes herramientas (tools) para que cualquier cliente compatible con Model Context Protocol (como Claude Desktop) pueda interactuar con ellas:
### 1. `get_devices`
Obtiene la lista cruda de dispositivos vinculados (como smart bands, relojes o básculas inteligentes) asociados con la cuenta.
* **Parámetros:** Ninguno.
* **Ejemplo de llamada:**
```json
{}
```
* **Ejemplo de respuesta (JSON):**
```json
[
{
"macAddress": "AA:BB:CC:DD:EE:FF",
"activeStatus": 1,
"deviceType": 2,
"additionalInfo": "{\"auth_key\":\"0x0123456789abcdef0123456789abcdef\",\"firmware_version\":\"1.0.0.1\"}"
}
]
```
### 2. `get_weight`
Obtiene los registros de peso e impedancia de la báscula de forma estructurada y con marcas de tiempo legibles en UTC, manteniendo además los datos crudos originales.
* **Parámetros:**
* `date` *(string, opcional)*: Fecha de inicio de la búsqueda en formato `YYYY-MM-DD`. Si se omite, por defecto busca desde la fecha actual.
* `end_date` *(string, opcional)*: Fecha de fin de la búsqueda en formato `YYYY-MM-DD`. Si se omite, por defecto busca hasta el final del día de `date`.
* **Ejemplo de llamada (para un rango de días):**
```json
{
"date": "2023-09-01",
"end_date": "2023-09-20"
}
```
* **Ejemplo de respuesta (JSON):**
```json
[
{
"time": "2023-09-20 07:10:16+0000",
"weight": 70.0,
"height": 175.0,
"bmi": 22.86,
"fatRate": 15.0,
"bodyWaterRate": 58.0,
"boneMass": 3.0,
"metabolism": 1600.0,
"muscleRate": 78.0,
"visceralFat": 5.0,
"rawdata": {
"userId": "1234567890",
"memberId": "-1",
"deviceSource": 102,
"appName": "com.xiaomi.hm.health",
"generatedTime": 1695193816,
"weightType": 0,
"deviceId": "1234567890ABCDEF",
"summary": {
"weight": 70.0,
"height": 175.0,
"age": 30,
"bmi": 22.86,
"fatRate": 15.0,
"bodyWaterRate": 58.0,
"boneMass": 3.0,
"metabolism": 1600.0,
"muscleRate": 78.0,
"visceralFat": 5.0
}
}
}
]
```
---
## Integración con Claude Desktop
Para integrar este servidor MCP en tu cliente Claude Desktop, edita tu archivo de configuración `mcp_config.json` (ubicado típicamente en `%APPDATA%\Roaming\Claude\mcp_config.json` en Windows o en `~/Library/Application Support/Claude/mcp_config.json` en macOS) y añade la definición del servidor con rutas relativas a tu sistema.
> [!IMPORTANT]
> Recuerda cambiar las rutas de ejemplo `/ruta/absoluta/a/tu/proyecto` por la ruta real absoluta donde has clonado o creado esta carpeta.
### Configuración con variables de Token (Recomendado)
```json
{
"mcpServers": {
"zepplife-mcp": {
"command": "/ruta/absoluta/a/tu/proyecto/.venv/Scripts/python.exe",
"args": [
"/ruta/absoluta/a/tu/proyecto/server.py"
],
"env": {
"ZEPP_APP_TOKEN": "TU_APP_TOKEN_CAPTURADO",
"ZEPP_USER_ID": "TU_USER_ID_AQUÍ"
}
}
}
}
```
### Configuración con Login Automático
```json
{
"mcpServers": {
"zepplife-mcp": {
"command": "/ruta/absoluta/a/tu/proyecto/.venv/Scripts/python.exe",
"args": [
"/ruta/absoluta/a/tu/proyecto/server.py"
],
"env": {
"ZEPP_EMAIL": "tu_email@example.com",
"ZEPP_PASSWORD": "tu_password_aqui"
}
}
}
}
```
*Nota para macOS/Linux: en lugar de `.venv/Scripts/python.exe` utiliza `.venv/bin/python`.*
Una vez guardado el archivo, reinicia Claude Desktop para activar las herramientas.
