Mi Fitness MCP
Mi Fitness MCP syncs Xiaomi/Mi Fitness cloud health data into a local SQLite cache and exposes it through MCP tools for querying.
Check connection status and background sync progress
Trigger full or type-specific synchronization, optionally in the background
Retrieve user profile and daily activity summaries
Query metric time series for steps, distance, active calories, and weight
Query heart rate samples, including resting, active, passive, and workout samples
Query body measurements, sleep sessions with naps, workouts, SpO2, stress, and abnormal heartbeat events
Inspect data coverage by data type
Run as a stdio MCP server for clients such as Claude Desktop
Provides tools for reading and syncing Xiaomi Mi Fitness cloud health data, including daily activity, heart rate, sleep, workouts, body measurements, SpO2, stress, and abnormal heart beat events, into a local SQLite cache for querying.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mi Fitness MCP sync my steps and sleep for the past week and show daily activity"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mi Fitness MCP
小米运动健康 / Mi Fitness 数据本地 MCP Server。把云端数据同步到本地 SQLite,供 MCP 客户端或任何能读 SQLite 的工具查询。
功能
读取小米运动健康云端数据,同步到本地 SQLite 缓存
提供 MCP Server(stdio),供 Claude Desktop 等 MCP 客户端调用
支持中国区(
--region cn),其它区域可选ru/de/i2/sg/us支持的数据类型:
类型 | 内容 |
| 步数、距离、活动卡路里 |
| 心率采样(主动 / 被动)与静息心率 |
| 睡眠记录(分期、午睡、同晚去重) |
| 运动记录 |
| 体重 / 身体成分,视账号设备而定 |
| 血氧饱和度 |
| 压力值 |
| 异常心跳事件 |
Related MCP server: Mi Fitness MCP
数据处理
步数与卡路里
云端对同一天会返回多路上报记录(手机 + 手表各报一份),同一分钟常见 2~3 条且数值不同。同步时按时间戳合并、取最大值,再按天累加,而不是把所有记录直接相加。
剩余约 2% 的差异无法消除:小米 App 的活动段合并算法不等于「每分钟取最大值」。数字只能作量级参考,精确值仍以 App 为准。
睡眠
分期映射:
state2 → deep、3 → light、4 → rem、5 → awake、6 → unclassified(设备未做分期分析),未知值一律归入 unclassified。同晚去重:入睡时间相差 ≤60 分钟的记录视为同一晚(健康平台与设备直传各记一份),只保留信息量最高的一条 —— 含 REM 的优先,其次是有真实分期的,最后是只有总时长的;同档比较时长。
午睡识别:时长 <60 分钟且醒来时间落在本地 11:00–16:59 的记录标记为
is_nap。归档口径:按入睡日期归档。23:40 入睡、次日 07:44 醒的记录归到入睡那天,查「昨天睡得怎样」时需留意。
缺时间戳的记录
time 缺失或非法的记录不参与时间戳合并,各自原样保留,不会被合并成一条。
安装
git clone ssh://git@192.168.31.114:3022/uint/mi-fitness-mcp.git
cd mi-fitness-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'如果当前环境没有系统 keyring:
pip install -e '.[headless]' # keyrings.alt,明文文件后端注意:keyrings.alt 可能以明文文件方式保存凭据。
headless 服务器上推荐用 mi.py(会自动切到本仓库的 .venv):
install -m 600 /dev/null ~/.config/secrets/xiaomi.env
# 写入两行:XIAOMI_USER_ID=... / XIAOMI_PASS_TOKEN=...
./mi.py doctor
./mi.py sync --start-date 2026-10-01 --end-date 2026-10-19配置
需要从 https://account.xiaomi.com 登录后的 Cookie 中获取 userId 和 passToken。
中国区账号:
mi-fitness-mcp setup \
--mode mi_fitness_cloud \
--user-id "<userId>" \
--pass-token "<passToken>" \
--region cn凭据也可以通过环境变量提供,适合容器 / cron / 无 keyring 的环境:
export MI_FITNESS_USER_ID="<userId>"
export MI_FITNESS_PASS_TOKEN="<passToken>"keyring 优先:setup 写入的值不会被环境变量覆盖。变量说明见 .env.example。
检查连接:
mi-fitness-mcp doctor同步数据
# 全部支持的类型
mi-fitness-mcp sync --start-date 2026-01-01 --end-date 2026-06-21
# 按类型
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
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启动 MCP Server
mi-fitness-mcp serveClaude Desktop 配置示例:
{
"mcpServers": {
"mi-fitness": {
"command": "mi-fitness-mcp",
"args": ["serve"]
}
}
}MCP 工具
工具 | 用途 |
| 检查连接状态 |
| 触发同步(支持后台执行) |
| 查后台同步进度 |
| 用户资料 |
| 某天的活动汇总 |
| 任意指标时间序列 |
| 心率采样(含静息心率) |
| 体重与体成分 |
| 睡眠记录 |
| 运动记录 |
| 血氧 |
| 压力 |
| 异常心跳事件 |
| 各类型数据覆盖范围 |
本地数据库
默认位置:
~/.local/share/mi-fitness-mcp/mi_fitness.db主要表:
daily_activity
heart_rate_samples
sleep_sessions
workouts
body_measurements
spo2_samples
stress_samples
abnormal_heart_beat_events
sync_state已知限制
这些是当前实现的实际短板,不是待办清单 —— 记录在此,避免使用者踩到后误以为数据本身有问题。
数据可得性
项 | 现状 | 原因 |
体重 / 体成分 | 0 条 | 账号没有小米体脂秤,云端无数据。表结构和 MCP 工具都在,接上秤即可用 |
压力(stress) | 0 条 | 手环不上报该指标 |
睡眠得分 | 全为空 | 云端 |
GPS 轨迹 | 无 | 只取了距离和步数,运动记录不含轨迹点 |
数据口径
步数存在约 2% 的系统性偏差:小米 App 的活动段合并算法不等于「每分钟取最大值」,数字只能作量级参考,精确值以 App 为准(见上文「数据处理」)。
运维
无异常数据检测:同步只负责搬运,不做合理性校验(比如某天步数突然翻十倍不会告警)。
CI 只在本仓库推送到 GitHub 时触发:本地可用
pytest/ruff手动跑。
云端接口
健康数据接口
POST https://hlth.io.mi.com/app/v1/data/get_fitness_data_by_time常用 key:
steps
calories
heart_rate
weight
sleep睡眠请求示例:
{
"start_time": 1767225600,
"end_time": 1782086399,
"key": "sleep"
}运动记录接口
POST https://hlth.io.mi.com/app/v1/data/get_sport_records_by_time请求示例:
{
"start_time": 1767225600,
"end_time": 1782086399,
"limit": 50
}返回字段通常包含 sport_records、has_more、next_key。
每条运动记录的 value 是 JSON 字符串,包含 start_time、end_time、duration、distance、calories、avg_hrm、max_hrm 等字段。
安全说明
passToken是敏感凭据,不要泄露。不要提交本地配置、数据库、keyring 文件。
如果 token 泄露,建议退出小米账号并重新登录刷新。
与小米公司的关系
本项目与小米公司无关,非官方项目,仅用于读取和分析你自己的健康数据。
参考与致谢
代码起源于以下两个项目,感谢它们的作者与维护者:
项目 | 提供的基础 |
整体架构、MCP server、SQLite 存储层、认证流程(MIT) | |
小米健康云接口逆向、 |
MIT 许可证与原始版权声明保留在 LICENSE。
License
MIT。完整许可证与版权声明见 LICENSE。
Available Tools
14 toolsget_connection_statusC
Check connection status
Inputs: no named parameters.
get_daily_summaryC
Get daily activity summary
Inputs: date, end_date, start_date.
get_data_coverageD
Get data coverage
Inputs: data_types.
get_profileB
Get user profile information
Inputs: no named parameters.
get_sync_statusC
Get background synchronization status
Inputs: sync_id (required).
query_abnormal_heart_beatC
Query abnormal heart beat events
Inputs: end_date (required), start_date (required), limit.
query_body_measurementsD
Query body measurements
Inputs: end_date (required), start_date (required), metrics, latest_only.
query_heart_rateC
Query heart rate samples
Inputs: end_date (required), start_date (required), limit, sample_type.
query_metric_seriesD
Query metric series
Inputs: metric (required), end_date (required), start_date (required), aggregation, +1 more.
query_sleepC
Query sleep sessions
Inputs: end_date (required), start_date (required), include_naps.
query_spo2C
Query blood oxygen saturation samples
Inputs: end_date (required), start_date (required), limit.
query_stressC
Query stress samples
Inputs: end_date (required), start_date (required), level, limit.
query_workoutsD
Query workouts
Inputs: end_date (required), start_date (required), min_duration, activity_types, +1 more.
sync_dataC
Synchronize Mi Fitness data
Inputs: end_date, background, data_types, start_date, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target clearly distinct resources or actions. The generic query_metric_series could overlap with specific metric tools like query_heart_rate or query_spo2, and sync_data/get_sync_status/get_connection_status have related sync semantics, but they remain distinguishable.
All names use snake_case and follow a predictable verb_noun or get_noun pattern. The mix of get_*, query_*, and sync_* is semantically coherent and consistent across the set.
14 tools is well-scoped for a fitness data integration. Each major metric has a dedicated query tool without excessive or redundant tooling.
The surface covers connection, sync, profile, daily summaries, data coverage, and major health metrics including heart rate, sleep, workouts, SpO2, stress, and body measurements. Minor gaps may exist for device details or granular activity segments, but core coverage is strong.
Maintenance
Related MCP Connectors
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Hosted Apple Health MCP: workouts, sleep and HRV in ChatGPT, Claude, Gemini, Grok. Free, no export.
Apple Health training load, recovery, HRV and workout detail for Claude, ChatGPT and any MCP client.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server that provides local caching, sync, and tools for Zepp Life health data including steps, sleep, heart rate, workouts, and body measurements, supporting both file exports and cloud session access.1016MIT
- AlicenseCqualityCmaintenanceMCP server for Mi Fitness cloud data. Provides a local SQLite-backed server to sync and query daily activity, heart rate, and body measurements.128MIT
- AlicenseCqualityDmaintenanceEnables reading and syncing Xiaomi Mi Fitness health data (steps, heart rate, sleep, workouts) from the Chinese cloud region to a local SQLite database via MCP tools.1021MIT
- AlicenseAqualityAmaintenanceProvides local MCP tools to query your own Xiaomi Mi Fitness health data (sleep, workouts, heart rate, etc.) stored in a local SQLite database, enabling AI assistants to access personal health records without exposing credentials.1773AGPL 3.0