Mi Fitness MCP CN
Syncs personal Mi Fitness/Xiaomi health data from the Xiaomi cloud into a local SQLite database, enabling querying and analysis of daily activity, heart rate, sleep stages, workouts, body measurements, SpO₂, stress, and abnormal heartbeats through MCP tools, REST API, and a web dashboard.
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 CN Sync my Mi Fitness data for last week and summarize my sleep stages."
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 CN
小米运动健康(Mi Fitness)数据的本地一站式解决方案:MCP Server + REST API + 可视化 Web 仪表盘。把你自己账号里的健康数据同步到本地 SQLite,供 AI 客户端、其他程序或浏览器直接查询分析。
Local-first Mi Fitness (Xiaomi health) data hub: sync your own health data to a local SQLite database, exposed via MCP, REST API, and a web dashboard.
关于本仓库
本仓库基于中文增强分支 HUAYUE1024/mi-fitness-mcp-cn(其源自 kubulashvili/mi-fitness-mcp)的 v0.2.2 继续开发,当前版本 v0.3.0。维护与发版(Issue / PR / tag / GitHub Release)都在本仓库进行,保留 MIT 许可与全部原作者署名。
Related MCP server: Mi Fitness Data Bridge
相比上游多了什么
上游最新是 v0.2.2,本仓库到 v0.3.0 多了下面这些,每条都有对应提交和测试:
睡眠数据修好了:旧版睡眠分段状态码映射反了,深睡基本取不到。本版按实测重映射(4=REM、5=清醒、6=未分期按浅睡计),历史数据重新同步一次深睡就回来了;主睡眠评分也能从日汇总补齐(0–100)。
小时窗口增量同步:
sync_data、POST /api/sync、CLI 新增hours_back/start_time/end_time,只拉最近 N 小时。2 小时心率一次约 60–120 条,不再全天约 1440 条,单趟请求量约降到 1/12。时间参数更宽容:同步口直接吃 ISO 8601(如
2026-11-06T09:00:00),窗口起止一端日期一端时间也能跑;查询端点统一按日期处理,修掉 ISO 串比较会漏掉开始日的问题。API 返回包版本号,外部程序能直接确认后端版本。
仪表盘显示修准:总览与查询页按 API 实际字段渲染,活动消耗、距离、静息心率、睡眠、血氧、压力与睡眠分段不再错位或空白。
CI 更严:新增
twine check、实装 wheel 冒烟和 CLI 冒烟,发版包坏没坏在 CI 就拦下。
日聚合数据(步数、睡眠、体重)在窗口模式下仍按整天抓取,汇总完整;无破坏性 API 变更,旧版本可继续读同一个 SQLite 库。
界面预览


截图使用合成演示数据,不含任何真实账号或健康记录。
功能特性
🇨🇳 中国区云端适配(
--region cn),同时支持 ru/de/sg/us 等国际区!📦 三种接入方式:MCP Server(AI 客户端)、REST API(任意程序)、Web 仪表盘(浏览器)
💤 全量健康指标:每日活动、逐分钟心率、睡眠分期(深睡/浅睡/REM/小睡)、运动记录、身体成分、血氧(SpO₂)、压力、异常心跳
🔄 增量同步引擎:7 天分块拉取 + 断点续传游标 + UPSERT 幂等入库,重复同步不产生脏数据
🔑 API Key 体系:用小米凭据换取
mif_sk_*Key(类大模型平台风格),支持多账号隔离、用量统计、按前缀吊销📱 扫码登录:逆向小米官方扫码流程,手机 App 扫码即可授权,告别浏览器 F12 抓 Cookie
🖥️ 现代化 Web 仪表盘(Flask):数据图表走势、实时响应检视、cURL 一键生成、深浅主题
🔒 本地优先:数据、凭据、配置全部留在本机(SQLite + 系统 keyring),不上传任何第三方服务
⚠️ 非小米官方项目。全部云端接口为逆向所得,仅用于读取和分析你自己的健康数据,请遵守小米用户协议。接口可能因小米改版而失效。
架构
flowchart LR
A[小米手环/手表] -->|蓝牙| B[小米运动健康 App]
B -->|同步| C[小米健康云]
C -->|RC4 加密 + 签名<br/>逆向协议| D[SyncService<br/>分块/增量]
D --> E[(本地 SQLite)]
E --> F[MCP Server<br/>stdio · 14 个工具]
E --> G[REST API<br/>FastAPI · X-API-Key]
E --> H[Web 仪表盘<br/>Flask · 浏览器]
G <--> H支持的数据
类型 | 内容 | CLI | API 端点 |
每日活动 | 步数、距离、活动卡路里 |
|
|
心率 | 逐分钟采样 + 静息心率 |
|
|
睡眠 | 时长、入睡/清醒、分段(深睡/浅睡/REM) |
|
|
运动 | 类型、时长、距离、卡路里、心率、配速 |
|
|
身体成分 | 体重、BMI、体脂、肌肉量等(需体脂秤) |
|
|
血氧 | SpO₂ 采样 |
|
|
压力 | 压力分数 + 等级 |
|
|
异常心跳 | 事件起止与时长 |
|
|
睡眠分段状态码
6(未分期 / 手机单段跟踪)按浅睡计入。
快速开始
安装
本项目未发布到 PyPI,从 GitHub 安装。稳定版本用 tag,开发版用 main:
# 稳定版(推荐):安装到当前 Python 环境
pip install "mi-fitness-mcp[all] @ git+https://github.com/ai-dachui/mi-fitness-mcp-enhance@v0.3.0"
# 开发版:克隆源码后可编辑安装
git clone https://github.com/ai-dachui/mi-fitness-mcp-enhance.git
cd mi-fitness-mcp-enhance
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e '.[all,dev]' # 含 FastAPI 与 Flask Web UI;仅核心功能: pip install -e .要求 Python ≥ 3.11。Linux 无系统 keyring 时可 pip install keyrings.alt(可能明文存储凭据)。
升级与回滚
版本升级与回滚都通过 tag 安装,不改本地数据库结构:
# 升级到 0.3.0
pip install --force-reinstall "mi-fitness-mcp[all] @ git+https://github.com/ai-dachui/mi-fitness-mcp-enhance@v0.3.0"
# 回滚到 0.2.2
pip install --force-reinstall "mi-fitness-mcp[all] @ git+https://github.com/ai-dachui/mi-fitness-mcp-enhance@v0.2.2"升级到 0.3.0 后建议先对最近 7 天做一次睡眠同步:睡眠分段状态码已按实测重映射,历史 REM/清醒时长会随同步更新。
获取凭据(二选一)
方式 A:Web 仪表盘扫码登录(推荐,无需浏览器 F12)
mi-fitness-mcp api # 终端 1:后端 API 服务 (127.0.0.1:8321)
mi-fitness-mcp web # 终端 2:Web 仪表盘 (127.0.0.1:8322)浏览器打开 http://127.0.0.1:8322/ → 点击「扫码登录」→ 用小米账号 / 米家 App 扫码确认 → 自动换取并注入 API Key。
方式 B:手动配置凭据
浏览器登录 account.xiaomi.com,从 Cookie 获取 userId 与 passToken:
mi-fitness-mcp setup --mode mi_fitness_cloud --user-id "<userId>" --pass-token "<passToken>" --region cn
mi-fitness-mcp doctor # 验证连通性同步与使用
mi-fitness-mcp sync --start-date 2026-01-01 --end-date 2026-06-30 # 全量同步
mi-fitness-mcp sync --type sleep --start-date 2026-06-01 --end-date 2026-06-30 # 按类型
mi-fitness-mcp sync # 无日期:从上次断点续传(首次为最近 30 天)
# 小时窗口增量(时序类:心率、压力、血氧、异常心跳、运动)
mi-fitness-mcp sync --type heart_rate --hours-back 2
mi-fitness-mcp sync --type heart_rate --start-time 1743467400 --end-time 1743474600
--hours-back/--start-time/--end-time只对时序类生效;步数、睡眠、体重等日聚合数据仍按天抓取,避免汇总值被窗口截断。
接入 MCP 客户端(Claude Desktop 等):
{
"mcpServers": {
"mi-fitness": { "command": "mi-fitness-mcp", "args": ["serve"] }
}
}MCP 工具(14 个):get_connection_status · sync_data · get_sync_status · get_profile · get_daily_summary · query_metric_series · query_heart_rate · query_body_measurements · query_sleep · query_workouts · query_spo2 · query_stress · query_abnormal_heart_beat · get_data_coverage
sync_data 与 CLI/REST 使用同一组窗口参数:hours_back(最近 N 小时)、start_time / end_time(epoch 秒),仅对心率、压力、血氧、异常心跳、运动生效。例如在 MCP 客户端里调用:
{"data_types": ["heart_rate"], "hours_back": 2}REST API 与鉴权
mi-fitness-mcp api [--host 127.0.0.1] [--port 8321]交互式 Swagger 文档:
http://127.0.0.1:8321/docs鉴权层级:
层级 | 说明 |
默认凭据 | 不带 Key = 使用本机 |
静态 Key | 设置 |
发放 Key |
|
管理鉴权 | Key 发放/吊销与扫码登录端点须带 |
# 发放 Key(真实登录验证凭据)
curl -X POST http://127.0.0.1:8321/api/auth/keys -H "Content-Type: application/json" \
-d '{"user_id":"...","pass_token":"...","region":"cn","label":"my-app"}'
# 带 Key 查询
curl "http://127.0.0.1:8321/api/summary?start_date=2026-08-01&end_date=2026-08-31" \
-H "X-API-Key: mif_sk_..."
# 触发同步(前台等待)/ 后台执行
curl -X POST http://127.0.0.1:8321/api/sync -H "Content-Type: application/json" \
-d '{"start_date":"2026-08-30","end_date":"2026-08-31"}'
# 小时窗口同步(时序类)
curl -X POST http://127.0.0.1:8321/api/sync -H "Content-Type: application/json" \
-d '{"data_types":["heart_rate"],"hours_back":2}'常见问题
数据链路是「手环 → 手机 App → 小米云 → 本项目」。步数通常实时性最好;心率/血氧/压力的连续监测需在小米运动健康 App 中开启(如「全天心率监测」「全天压力监测」),且手环需保持佩戴。云端没有的数据本项目无法凭空生成。
passToken 是长期凭据,但退出登录、修改密码或在小米账号安全中心踢出设备都会使其失效。重新到 account.xiaomi.com 获取新的 userId/passToken 运行 setup,或直接用扫码登录重新授权。
MCP SDK 2.x 移除了该 API。本项目已固定 mcp>=1.0.0,<2,若你从旧版本升级,重新 pip install -e . 让依赖约束生效即可。
首次全量同步按 7 天分块串行拉取,8 个月数据约数分钟(心率逐分钟采样占大头);之后增量同步只拉最近数据,数秒完成。所有写入为 UPSERT 幂等,重复同步安全。
项目结构
src/mi_fitness_mcp/
├── main.py # CLI 统一入口: serve / setup / doctor / sync / api / web
├── server.py # MCP Server(14 个工具 + 异步同步引擎)
├── api.py # REST API 服务(FastAPI: 数据端点 + Key 体系 + 扫码登录)
├── web.py # 可视化仪表盘反向代理服务(Flask)
├── web_assets/ # 前端界面(HTML / CSS / JS)
├── adapters/ # 小米云协议:登录、RC4 加解密、签名、分页、解析
├── services/ # 同步引擎(分块/增量)与查询聚合
├── storage/ # SQLite 数据库引擎(8 张数据表 + sync_state)
├── models/ # Pydantic 数据模型
├── config.py # 系统配置管理(platformdirs + JSON)
└── auth/ # keyring 安全凭据存储
testpage/ # 可选:独立运行的 Web 测试控制台(免安装,直接 python app.py)
docs/ # 技术文档(见下方)
tests/ # 单元测试与端到端测试套件数据库与配置位于系统用户目录(~/.local/share/mi-fitness-mcp/,Windows 为 %LOCALAPPDATA%\mi-fitness-mcp\),凭据存于系统 keyring,均不在仓库内。
文档
隐私与数据安全审计 —— 数据流向、全部对外请求清单、威胁模型与自验方法
本地开发
pip install -e '.[all,dev]'
ruff check src tests # 代码规范检查(CI 同款)
pytest -v # 完整测试套件
python -m build # 构建发行包安全与隐私
数据只进不出:本项目从小米云拉取你自己的数据到本地 SQLite,除小米官方服务器外不与任何第三方通信;无遥测/统计/崩溃上报;所有查询端点断网可用。完整审计见 docs/PRIVACY.md。
passToken等同小米账号登录态,切勿提交或泄露;若泄露,请在小米账号安全中心退出设备并重新登录凭据与 API Key 密钥存于系统 keyring(Windows DPAPI / macOS Keychain / Linux Secret Service),不落明文
不要提交本地配置、数据库、keyring 文件(
.gitignore已默认排除)服务默认仅绑定
127.0.0.1,并已启用 CORS 本机限制与 Host 白名单(防恶意网页跨站读取 / DNS 重绑定)。向局域网/公网开放前,务必设置MI_FITNESS_API_KEY与MI_FITNESS_ADMIN_KEY——健康数据是敏感信息扫码登录端点允许扫码者将其账号登录到你的服务器,务必保持管理鉴权开启
免责声明
本项目与小米公司无关。接口为社区逆向成果,不保证持续可用。请仅用于读取和分析您自己的个人健康数据。
来源与署名
本项目的代码、文档与功能是三层持续积累的结果,署名按真实提交历史保留:
原始项目:kubulashvili/mi-fitness-mcp(Aleksej Kubulashvili,MIT)——最初的独立 Mi Fitness MCP 实现,本项目的起点。
中文增强分支:HUAYUE1024/mi-fitness-mcp-cn(贡献者 binglua、HUAYUE1024)——中文本地化、睡眠与运动同步、血氧/压力/异常心跳;v0.2.0 的 REST API、API Key、扫码登录与 Web 仪表盘,v0.2.1/v0.2.2 的隐私加固与数据导出。
本自维护分支:ai-dachui/mi-fitness-mcp-enhance——直接延续第 2 层的提交历史,负责 v0.3.0 的睡眠分段修复、小时窗口同步、时间参数兼容、仪表盘字段修复、CI 产物校验与发版工程(详见上文相比上游多了什么)。
历史提交保留原作者信息,未做改写。特别感谢 binglua 与 HUAYUE1024 在 v0.2.x 与 0.3.0 中的主要工作。
License
MIT · 原始版权归 Aleksej Kubulashvili(kubulashvili/mi-fitness-mcp);后续增强见 HUAYUE1024/mi-fitness-mcp-cn
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, end_time, background, data_types, +4 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 map to distinct resource+action pairs (sync_data, get_profile, query_sleep). However, the generic query_metric_series overlaps conceptually with the specific query_heart_rate/spo2/stress/body tools, and get_daily_summary sits close to query_metric_series, creating mild boundary ambiguity.
Consistent verb_noun pattern throughout, with a thoughtful split between get_ (status/profile/summary) and query_ (time-series samples), plus sync_/get_sync_status for sync operations. No mixing of style conventions.
14 tools is well within the ideal 3-15 range and each covers a distinct facet of fitness data (heart rate, sleep, workouts, spo2, stress, body, coverage). No filler tools.
Covers connection, sync, profile, daily summary, and the full metric surface, which is comprehensive for a read-only fitness domain. Minor gaps: no way to enumerate available metrics/devices or export raw data, but core lifecycle is well covered.
Maintenance
Related MCP Connectors
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Your Google Health data (Fitbit, Pixel Watch): sleep, HRV, readiness and biological age.
Connect your wearables, rings and training apps, then ask your AI about your own health data.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceSelf-hosted MCP server that syncs Xiaomi fitness data to SQLite and provides authenticated tools to query health metrics (steps, sleep, HR, etc.) for AI assistants like Grok.GPL 3.0
- 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
- AlicenseNot gradedqualityBmaintenanceLets AI assistants read your own Mi Fitness (Xiaomi cloud) health data — steps, heart rate, sleep, SpO2, stress, weight and workouts — through local MCP tools with QR-code login. Runs locally over stdio, returns results as JSON, and withholds GPS tracks unless explicitly allowed.586 PyPI5MIT
- AlicenseCqualityBmaintenanceEnables AI clients to query and analyze your own Xiaomi/Mi Fitness health data — daily activity, minute-level heart rate, sleep stages, workouts, body composition, SpO₂, stress, and abnormal heart beat events — after syncing it from the Xiaomi cloud into a local SQLite database. Exposes 14 tools covering connection status, incremental sync control, and metric/date-range queries, with everything stored and served locally.14MIT