Mi Fitness MCP CN
Syncs and queries personal Mi Fitness (Xiaomi health) data from Xiaomi cloud, including daily activity, heart rate, sleep stages, workouts, body measurements, SpO₂, stress, and abnormal heart beat.
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 recent Mi Fitness data and show my sleep stages from last night."
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.
基于 kubulashvili/mi-fitness-mcp 修改并深度重构。
功能特性
🇨🇳 中国区云端适配(
--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),不上传任何第三方服务
⚠️ 非小米官方项目。全部云端接口为逆向所得,仅用于读取和分析你自己的健康数据,请遵守小米用户协议。接口可能因小米改版而失效。
Related MCP server: mifit
架构
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₂ 采样 |
|
|
压力 | 压力分数 + 等级 |
|
|
异常心跳 | 事件起止与时长 |
|
|
快速开始
安装
git clone https://github.com/HUAYUE1024/mi-fitness-mcp-cn.git
cd mi-fitness-mcp-cn
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(可能明文存储凭据)。
获取凭据(二选一)
方式 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 天)接入 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
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"}'常见问题
数据链路是「手环 → 手机 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 # 完整测试套件(22 个)
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——健康数据是敏感信息扫码登录端点允许扫码者将其账号登录到你的服务器,务必保持管理鉴权开启
免责声明
本项目与小米公司无关。接口为社区逆向成果,不保证持续可用。请仅用于读取和分析您自己的个人健康数据。
License
MIT · 源自上游项目 kubulashvili/mi-fitness-mcp
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 have distinct, clearly-scoped purposes (connection, sync, profile, and per-metric queries). The generic query_metric_series overlaps somewhat with the specific query_heart_rate/query_spo2/query_stress tools, which could cause some misselection, but descriptions largely clarify the boundaries.
The set follows a consistent verb_noun pattern (get_*, query_*, get_*_status) with clear prefixes for read vs. query operations. The lone sync_data breaks the get_/query_ prefix convention slightly, but overall it is predictable and readable.
14 tools is well within a reasonable range for a fitness-data server and each tool earns its place, covering distinct lifecycle steps (connection, sync, profile, metrics, coverage).
The surface covers connection, sync lifecycle, profile, a broad set of metrics, and data coverage, giving good read coverage. Minor gaps exist (e.g. no metric-discovery/list tool beyond the generic series query, no config/auth management), but core workflows are workable.
Maintenance
Related MCP Connectors
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Connect your wearables, rings and training apps, then ask your AI about your own health data.
Connect your health, fitness, nutrition, sleep, and wearable data to your AI assistant.
Your Google Health data (Fitbit, Pixel Watch): sleep, HRV, readiness and biological age.
Related MCP Servers
- 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 PyPI8MIT
- AlicenseCqualityBmaintenanceEnables syncing Xiaomi Mi Fitness cloud health data into a local SQLite cache and querying it through MCP tools for daily activity, heart rate, sleep, workouts, body measurements, blood oxygen, stress, and abnormal heartbeat records.14MIT
- AlicenseNot gradedqualityCmaintenanceExposes a locally synced SQLite database of Garmin China (connect.garmin.cn) activities and daily health metrics as nine tools covering activity lists, per-activity splits, rest-HR/HRV/sleep/Body Battery data, weekly training-load summaries, multi-day sleep reports, morning briefings, and read-only SQL. Queries auto-trigger incremental sync when local data is stale, so users can ask training and recovery questions in plain language.MIT