内容
# Zepp Life（小米运动）MCP 服务器
一个使用 FastMCP 写的 Python MCP（Model Context Protocol）服务器，用于读取和查询你的 **Zepp Life**（原小米运动）账户数据。
## 功能特点
服务器提供了查询以下数据的工具：
* **设备：** 已绑定设备的列表，包含 MAC 地址、状态和蓝牙绑定密钥（`auth_key`）。
* **体重：** 直接从智能体重秤获取体重和身体成分（BMI、脂肪量、肌肉量、水分、骨骼量等）的历史记录。
---
## 前置要求
* Python 3.9 或更高版本
* 一个 Zepp Life / 小米运动账户
---
## 配置和认证
服务器需要凭证才能访问 Zepp 的 API。你有两种配置选项，可以在 `.env` 文件中选择：
### 选项 A：使用应用令牌和用户 ID（推荐）
此选项最稳定，因为它不会因请求限制或登录验证码而被阻止。
要获取你的 `ZEPP_APP_TOKEN` 和 `ZEPP_USER_ID`：
1. 在计算机上安装 HTTPS 拦截代理（例如 [mitmproxy](https://mitmproxy.org/)、[Charles Proxy](https://www.charlesproxy.com/) 或 [HTTP Toolkit](https://httptoolkit.com/)）。
2. 配置手机将流量发送到代理。
3. 在手机上打开 Zepp Life 应用并同步数据。
4. 在代理日志中查找发送到 `api-mifit.zepp.com` 或 `api-mifit.huami.com` 等域名的请求。
5. 从 HTTP 头部提取值：
* `apptoken`（用作 `ZEPP_APP_TOKEN`）
* `userid` 或用户 ID URL 参数（用作 `ZEPP_USER_ID`）
### 选项 B：使用电子邮件和密码登录
如果您不想拦截流量，服务器可以尝试使用您的电子邮件和密码自动登录：
* `ZEPP_EMAIL`：您的 Zepp Life 账户电子邮件。
* `ZEPP_PASSWORD`：您的 Zepp Life 账户密码。
---
## 本地安装和配置
1. 创建虚拟环境并安装依赖项：
```bash
python -m venv .venv
.venv/Scripts/activate # 在 Windows 上（.venv/bin/activate 在 macOS/Linux 上）
pip install -r requirements.txt
```
2. 将 `.env.example` 文件复制到 `.env` 并填写所选变量：
```bash
copy .env.example .env
```
3. 在开发模式下测试服务器（热重载和 Web 检验）：
```bash
.venv/Scripts/fastmcp dev server.py
```
这将在 `http://localhost:5173` 打开 Web 检验界面，您可以直接在那里测试工具。
---
## 可用工具（MCP 工具）及调用方式
服务器公开了以下工具，允许任何兼容 Model Context Protocol（例如 Claude Desktop）的客户端与它们交互：
### 1. `get_devices`
获取与账户关联的已绑定设备（例如智能手环、智能手表或智能体重秤）的原始列表。
* **参数：** 无。
* **调用示例：**
```json
{}
```
* **响应示例（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`
获取体重秤的体重和阻抗记录，以 UTC 时间戳格式化，并保留原始数据。
* **参数：**
* `date` *(字符串，可选)*：搜索开始日期，格式为 `YYYY-MM-DD`。如果省略，则默认从当前日期开始搜索。
* `end_date` *(字符串，可选)*：搜索结束日期，格式为 `YYYY-MM-DD`。如果省略，则默认搜索到 `date` 当天的结束。
* **调用示例（针对某一天范围）：**
```json
{
"date": "2023-09-01",
"end_date": "2023-09-20"
}
```
* **响应示例（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
}
}
}
]
```
---
## 与 Claude Desktop 集成
要将此 MCP 服务器集成到您的 Claude Desktop 客户端中，请编辑您的配置文件 `mcp_config.json`（通常位于 Windows 上的 `%APPDATA%\Roaming\Claude\mcp_config.json` 或 macOS 上的 `~/Library/Application Support/Claude/mcp_config.json`），并添加服务器定义以及系统相关路径。
> [!IMPORTANT]
> 请记得将示例路径 `/ruta/absoluta/a/tu/proyecto` 替换为克隆或创建此文件夹的实际绝对路径。
### 使用令牌变量配置（推荐）
```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": "您的应用令牌",
"ZEPP_USER_ID": "您的用户 ID"
}
}
}
}
```
### 自动登录配置
```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": "your_email@example.com",
"ZEPP_PASSWORD": "your_password"
}
}
}
}
```
*macOS/Linux 注意：请使用 `.venv/bin/python` 代替 `.venv/Scripts/python.exe`。*
保存文件后，重启 Claude Desktop 以激活工具。
