mirror of
https://github.com/This-weiyuqing/mi-fitness-health.git
synced 2026-10-18 11:13:48 +08:00
199 lines
3.6 KiB
Markdown
199 lines
3.6 KiB
Markdown
# Mi Fitness MCP CN
|
||
|
||
小米运动健康 / Mi Fitness 数据本地 MCP Server。
|
||
|
||
本项目基于 `kubulashvili/mi-fitness-mcp` 修改，增加中国区小米健康云适配，并补充睡眠与运动记录同步能力。
|
||
|
||
> 非小米官方项目，仅用于读取和分析你自己的健康数据。数据默认同步到本地 SQLite。
|
||
|
||
## 功能
|
||
|
||
- 读取小米运动健康云端数据
|
||
- 本地 SQLite 缓存
|
||
- MCP Server 支持
|
||
- 支持中国区：`--region cn`
|
||
- 支持数据类型：
|
||
- `daily_activity`：步数、距离、活动卡路里
|
||
- `heart_rate`：心率采样
|
||
- `sleep`：睡眠记录
|
||
- `workouts`：运动记录
|
||
- `body_measurements`：体重 / 身体成分，视账号数据而定
|
||
|
||
## 已逆向验证的接口
|
||
|
||
### 健康数据接口
|
||
|
||
```text
|
||
POST https://hlth.io.mi.com/app/v1/data/get_fitness_data_by_time
|
||
```
|
||
|
||
常用 key：
|
||
|
||
```text
|
||
steps
|
||
calories
|
||
heart_rate
|
||
weight
|
||
sleep
|
||
```
|
||
|
||
睡眠请求示例：
|
||
|
||
```json
|
||
{
|
||
"start_time": 1767225600,
|
||
"end_time": 1782086399,
|
||
"key": "sleep"
|
||
}
|
||
```
|
||
|
||
### 运动记录接口
|
||
|
||
```text
|
||
POST https://hlth.io.mi.com/app/v1/data/get_sport_records_by_time
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"start_time": 1767225600,
|
||
"end_time": 1782086399,
|
||
"limit": 50
|
||
}
|
||
```
|
||
|
||
返回字段通常包含：
|
||
|
||
```text
|
||
sport_records
|
||
has_more
|
||
next_key
|
||
```
|
||
|
||
每条运动记录的 `value` 是 JSON 字符串，包含 `start_time`、`end_time`、`duration`、`distance`、`calories`、`avg_hrm`、`max_hrm` 等字段。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
git clone git@github.com:binglua/mi-fitness-mcp-cn.git
|
||
cd mi-fitness-mcp-cn
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -e '.[dev]'
|
||
```
|
||
|
||
如果当前环境没有系统 keyring，可安装：
|
||
|
||
```bash
|
||
pip install keyrings.alt
|
||
```
|
||
|
||
注意：`keyrings.alt` 可能以明文文件方式保存凭据。
|
||
|
||
## 配置
|
||
|
||
需要从 `https://account.xiaomi.com` 登录后的 Cookie 中获取：
|
||
|
||
- `userId`
|
||
- `passToken`
|
||
|
||
中国区账号建议：
|
||
|
||
```bash
|
||
mi-fitness-mcp setup \
|
||
--mode mi_fitness_cloud \
|
||
--user-id "<userId>" \
|
||
--pass-token "<passToken>" \
|
||
--region cn
|
||
```
|
||
|
||
检查连接：
|
||
|
||
```bash
|
||
mi-fitness-mcp doctor
|
||
```
|
||
|
||
## 同步数据
|
||
|
||
同步全部可探测数据：
|
||
|
||
```bash
|
||
mi-fitness-mcp sync --start-date 2026-01-01 --end-date 2026-06-21
|
||
```
|
||
|
||
按类型同步：
|
||
|
||
```bash
|
||
mi-fitness-mcp sync --type daily_activity --start-date 2026-01-01 --end-date 2026-06-21
|
||
mi-fitness-mcp sync --type heart_rate --start-date 2026-01-01 --end-date 2026-06-21
|
||
mi-fitness-mcp sync --type sleep --start-date 2026-01-01 --end-date 2026-06-21
|
||
mi-fitness-mcp sync --type workouts --start-date 2026-01-01 --end-date 2026-06-21
|
||
mi-fitness-mcp sync --type body_measurements --start-date 2026-01-01 --end-date 2026-06-21
|
||
```
|
||
|
||
## 启动 MCP Server
|
||
|
||
```bash
|
||
mi-fitness-mcp serve
|
||
```
|
||
|
||
Claude Desktop 配置示例：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"mi-fitness": {
|
||
"command": "mi-fitness-mcp",
|
||
"args": ["serve"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## MCP 工具
|
||
|
||
- `get_connection_status`
|
||
- `sync_data`
|
||
- `get_profile`
|
||
- `get_daily_summary`
|
||
- `query_metric_series`
|
||
- `query_heart_rate`
|
||
- `query_body_measurements`
|
||
- `query_sleep`
|
||
- `query_workouts`
|
||
- `get_data_coverage`
|
||
|
||
## 本地数据库
|
||
|
||
默认位置：
|
||
|
||
```text
|
||
~/.local/share/mi-fitness-mcp/mi_fitness.db
|
||
```
|
||
|
||
主要表：
|
||
|
||
```text
|
||
daily_activity
|
||
heart_rate_samples
|
||
sleep_sessions
|
||
workouts
|
||
body_measurements
|
||
sync_state
|
||
```
|
||
|
||
## 安全说明
|
||
|
||
- `passToken` 是敏感凭据，不要泄露。
|
||
- 不要提交本地配置、数据库、keyring 文件。
|
||
- 如果 token 泄露，建议退出小米账号并重新登录刷新。
|
||
|
||
## 免责声明
|
||
|
||
本项目与小米公司无关。请仅用于读取和分析你自己的健康数据。
|
||
|
||
## License
|
||
|
||
MIT
|