Content
# Mi Fitness MCP Server
Mi Fitness / Mi Fitness data local MCP Server.
This project is based on `kubulashvili/mi-fitness-mcp` and modified to add support for Chinese Mi Health cloud and supplement sleep and exercise record synchronization capabilities.
> Non-official Xiaomi project, only used to read and analyze your own health data. Data is synced to local SQLite by default.
## Features
- Read Mi Fitness cloud data
- Local SQLite cache
- MCP Server support
- Support for China region: `--region cn`
- Support data types:
- `daily_activity`: steps, distance, active calories
- `heart_rate`: heart rate samples
- `sleep`: sleep records
- `workouts`: exercise records
- `body_measurements`: weight / body composition, depending on account data
## Verified APIs
### Health Data API
```text
POST https://hlth.io.mi.com/app/v1/data/get_fitness_data_by_time
```
Common keys:
```text
steps
calories
heart_rate
weight
sleep
```
Sleep request example:
```json
{
"start_time": 1767225600,
"end_time": 1782086399,
"key": "sleep"
}
```
### Exercise Records API
```text
POST https://hlth.io.mi.com/app/v1/data/get_sport_records_by_time
```
Request example:
```json
{
"start_time": 1767225600,
"end_time": 1782086399,
"limit": 50
}
```
Response fields usually contain:
```text
sport_records
has_more
next_key
```
Each exercise record's `value` is a JSON string containing `start_time`, `end_time`, `duration`, `distance`, `calories`, `avg_hrm`, `max_hrm`, etc.
## Installation
```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]'
```
If the current environment does not have a system keyring, install:
```bash
pip install keyrings.alt
```
Note: `keyrings.alt` may save credentials in plaintext.
## Configuration
Needs to be obtained from `https://account.xiaomi.com` logged-in Cookie:
- `userId`
- `passToken`
Recommended for Chinese accounts:
```bash
mi-fitness-mcp setup \
--mode mi_fitness_cloud \
--user-id "<userId>" \
--pass-token "<passToken>" \
--region cn
```
Check connection:
```bash
mi-fitness-mcp doctor
```
## Sync Data
Sync all detectable data:
```bash
mi-fitness-mcp sync --start-date 2026-01-01 --end-date 2026-06-21
```
Sync by type:
```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
```
## Start MCP Server
```bash
mi-fitness-mcp serve
```
Claude Desktop configuration example:
```json
{
"mcpServers": {
"mi-fitness": {
"command": "mi-fitness-mcp",
"args": ["serve"]
}
}
}
```
## MCP Tools
- `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`
## Local Database
Default location:
```text
~/.local/share/mi-fitness-mcp/mi_fitness.db
```
Main tables:
```text
daily_activity
heart_rate_samples
sleep_sessions
workouts
body_measurements
sync_state
```
## Security Notes
- `passToken` is a sensitive credential, do not leak.
- Do not submit local configuration, database, and keyring files.
- If the token is leaked, it is recommended to log out of the Xiaomi account and re-login to refresh.
## Disclaimer
This project is not affiliated with Xiaomi. Please only use it to read and analyze your own health data.
### New Health Metrics
This branch additionally reverse-engineered and verified the following Mi Fitness cloud keys and has integrated them into CLI sync, local SQLite cache, and MCP query tools:
- `resting_heart_rate`: resting heart rate, merged into `query_heart_rate(sample_type="resting")`.
- `spo2`: blood oxygen saturation, CLI type `spo2`, MCP tool `query_spo2`.
- `stress`: stress value, CLI type `stress`, MCP tool `query_stress`.
- `abnormal_heart_beat`: abnormal heart beat events, CLI type `abnormal_heart_beat`, MCP tool `query_abnormal_heart_beat`.
Example:
```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
