# 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 泄露，建议退出小米账号并重新登录刷新。

## 免责声明

本项目与小米公司无关。请仅用于读取和分析你自己的健康数据。



### 新增健康指标

本分支额外逆向并验证了以下小米运动健康云端 key，并已接入 CLI 同步、本地 SQLite 缓存和 MCP 查询工具：

- `resting_heart_rate`：静息心率，合并到 `query_heart_rate(sample_type="resting")`。
- `spo2`：血氧饱和度，CLI 类型 `spo2`，MCP 工具 `query_spo2`。
- `stress`：压力值，CLI 类型 `stress`，MCP 工具 `query_stress`。
- `abnormal_heart_beat`：异常心跳事件，CLI 类型 `abnormal_heart_beat`，MCP 工具 `query_abnormal_heart_beat`。

示例：

```bash
mi-fitness-mcp sync --type spo2 --start-date 2026-06-01 --end-date 2026-06-22
mi-fitness-mcp sync --type stress --start-date 2026-06-01 --end-date 2026-06-22
mi-fitness-mcp sync --type abnormal_heart_beat --start-date 2026-06-01 --end-date 2026-06-22
```

## License

MIT