miband-health-mcp
Allows reading health records from Xiaomi Mi Band devices, providing recent status, daily reports, historical details, and data synchronization.
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., "@miband-health-mcp sync my band and give me today's health summary"
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.
MiBand MCP
让电脑上的 agent 读取小米手环的健康记录。当前支持小米手环 10,提供最近状态、日报、历史明细与数据同步;每项结果区分观测时间、拉取时间和缺失数据。
当前为首个公开测试版本(alpha)。主要验通路线是国内版安卓手机、Gadgetbridge、USB 和 Linux 电脑;其他平台及无线方式以各文档的验证范围为准。
使用效果如下:
让 agent 帮你配置
把本仓库交给能够操作电脑的 agent,并请它读取 配置 skill。它会检查设备、解释需要的选择,完成电脑配置,并逐步引导手机操作。也可以选择让 agent 帮忙操作手机;配对确认仍由你在手机和手环上完成。
可以直接把下面这段话交给 agent:
请按 https://github.com/kirisawa-subaru/miband-mcp 的配置 skill 帮我安装手环 MCP。先检查我的电脑和手机是否适用,默认用 USB 连接。电脑上的安装和配置由你完成,需要我在手机或手环上操作时,一步步告诉我。最后通过 MCP 实际同步并查询数据。
当前无需 root 的路线需要:
安卓手机和小米手环 10;苹果手机不适用。
Linux 或 macOS 电脑;Windows 尚未适配。
支持数据传输的 USB 线,可先找手机包装盒里的原装线。
接受改用 Gadgetbridge 管理手环。官方 App 的旧历史不会随配对密钥自动迁移过去。
先用 USB 完成连接。电脑开着、手机接上线时按需同步,无需先安装 Tailscale。无线及跨网络连接仍需单独配置和验收。
Related MCP server: miband-mcp
实现与开发
同一个 miband-health-mcp 入口按配置选择后端,数据分别缓存:
后端 | 数据通道 | 接口 |
Gadgetbridge | 已授权 ADB、App 导出、电脑 SQLite 缓存 | 最近状态、日报、明细、同步 |
小米运动健康(实验) | 已有 root/SSH 环境、官方 App 数据库与内部接口 | 查询、后台同步及设备控制已在指定版本实机验收;佩戴、睡眠和活动状态仍返回 unknown,App 升级后需重新验收 |
使用 uv sync --locked 安装依赖;需要小米健康进程内控制时加 --extra xiaomi。单元测试运行 .venv/bin/python -m unittest discover -s tests。原 mibandctl CLI 保留,新的 MCP 入口是 miband-health-mcp。
密钥、健康数据库、手机日志和用户配置仅保存在用户本机私有目录。尚未覆盖没有预先调试授权的首次安装测试;安装 agent 按实际机型引导连接,遇到版本差异可提交问题反馈。
许可证与来源
本项目采用 AGPL-3.0-or-later。Gadgetbridge 提供了设备支持、数据格式与协议研究基础,参考来源和第三方组件说明见 NOTICE。
Available Tools
11 toolsdelete_band_scheduleADestructive
Delete only the identified band alarm/reminder and verify its absence by read-back.
Obtain item_id from get_band_schedule. Other entries remain unchanged. Unknown write outcomes are reported explicitly; a transport acknowledgment alone is not success. timeout_seconds: 5..90.
Inputs: kind (required), item_id (required), timezone, timeout_seconds. Returns: object
get_band_scheduleA
Read actual band alarms/reminders, their IDs, repeat rules and device capacity.
Reconnect is automatic and bounded. Alarm time is the band's local wall clock; reminder timestamps are converted from UTC for display in the selected IANA timezone. timeout_seconds: 5..90. No data is invented if a device response is unavailable. Read again to reconcile an earlier write whose outcome was unknown. timezone defaults to the server setting.
Inputs: kind, timezone, timeout_seconds. Returns: object
get_band_statusA
Band connection, battery, charging and heart-rate/SpO2/stress monitoring settings.
Monitoring configuration is read-only. Remote reads reconnect automatically within the timeout; cached never contacts the phone. Unknown fields remain null. max_age_seconds: 1..86400; timeout_seconds: 10..90. No app UI interaction.
Inputs: freshness, max_age_seconds, timeout_seconds. Returns: object
get_current_stateA
Recent recorded heart rate, steps and historical sleep/workouts; Gadgetbridge adds battery.
cached returns immediately. prefer_fresh attempts an ordinary backend pull if HR is old; require_fresh returns freshness_unmet if the requested age cannot be met. No app UI interaction. A successful recent pull is reused for 60 seconds even when source data remains stale. wait_seconds: 1..30; max_age_seconds: 1..86400.
Inputs: freshness, wait_seconds, max_age_seconds. Returns: object
get_daily_reportARead-only
Cached natural-day summary (YYYY-MM-DD), with sleep assigned to the waking day.
Includes sample coverage and optional preceding-day comparisons (missing days excluded). For a morning digest, query yesterday's activity and today's waking sleep separately. Call sync_health first if needed. timezone is an IANA name, default Asia/Shanghai.
Inputs: date (required), timezone, compare_days. Returns: object
get_health_statusA
Recent HR, steps, sleep/workout history, wearing, sleep and activity state.
Each device-state observation has its own age/source. Current sleep_state is the band's classification, distinct from latest_sleep (a historical sleep session). cached uses local data only; remote reads reconnect automatically. This does not start a new measurement or change monitoring settings. max_age_seconds: 1..86400; device-state age is capped at 120s. timeout_seconds: 10..90.
Inputs: freshness, max_age_seconds, timeout_seconds. Returns: object
measure_heart_rateA
Request one live heart-rate reading from the connected, worn Mi Band, then stop.
Uses the app's authenticated Bluetooth connection, not the historical database. Reports received_at (host receipt time), start/stop acknowledgments and cleanup errors. No reading may be available if the band is not worn or disconnected. Timeout: 30..90s. Current-state queries prefer a newer successful live reading; daily aggregates remain based on recorded history. Always attempts to stop; check stop_confirmed rather than assuming success. Requires Xiaomi Health to be running with its band connection available.
Inputs: timeout_seconds. Returns: object
query_healthARead-only
Bounded cached detail: metric buckets, sleep sessions, or workouts.
Supply both start (inclusive) and end (exclusive) as offset-aware ISO timestamps, or neither for the last 24 hours (timeseries) / 30 days (sessions). limit 1..500; use returned pagination for more. Session IDs from summaries select a session. Missing buckets remain missing. Common metrics: heart_rate.bpm (default), steps, calories, distance. Additional metrics depend on the configured backend; see health://device-profile. aggregation_minutes: 1..1440. No arbitrary SQL.
Inputs: kind (required), end, limit, start, +5 more. Returns: object
set_band_alarmADestructive
Create or update one band alarm, preserving other alarms and verifying by read-back.
time is HH:MM in the band's local wall clock. weekdays uses ISO Monday=1..Sunday=7; [] means once, all seven means daily. Omit alarm_id to create; provide a listed ID to update that existing alarm. Supply the complete desired time/weekdays/enabled values. timezone labels the wall clock; it does not change the band's timezone. A lost write response is reconciled by reading back, never by blindly repeating the write. timeout_seconds: 5..90.
Inputs: time (required), weekdays (required), enabled, alarm_id, +2 more. Returns: object
set_band_reminderADestructive
Create or update one wrist reminder, then verify its actual stored fields.
at is an ISO timestamp with UTC offset; wire dates/times are UTC. title is the text shown on the band. Omit reminder_id to create, or use a listed ID to update. Supply all desired fields; unrelated entries are preserved. Recurrence follows the band's UTC schedule, so it does not automatically track local daylight-saving changes. On an unknown result inspect get_band_schedule before attempting another create. timeout_seconds: 5..90.
Inputs: at (required), title (required), repeat, timezone, +2 more. Returns: object
sync_healthA
Update the selected local cache and report actual record-time advancement.
Gadgetbridge exports and pulls its database over ADB; refresh_app=true first requests recorded-data synchronization from the band and waits for completion. Xiaomi Health reads through SSH; refresh_app=true invokes its internal background synchronization. No screen interaction or new physiological measurement is requested. Configure the transport once; cached queries still work when the phone is unavailable. Concurrent syncs share a single writer; timeout_seconds: 1..180.
Inputs: refresh_app, timeout_seconds. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools target distinct resources, but get_health_status and get_current_state both return recent HR, steps, and sleep/workout information, creating real ambiguity. get_band_status also overlaps with get_current_state on battery data. Detailed descriptions help, but an agent could still misselect among the health/state read tools.
Tool names follow a consistent verb_noun snake_case pattern: get_*, set_*, delete_*, sync_*, query_*, measure_*. Even the generic delete_band_schedule is predictable given get_band_schedule covers both alarms and reminders.
With 11 tools, the server is well-scoped for a Mi Band health and schedule domain. The count covers device status, health data retrieval, synchronization, live measurement, and schedule management without feeling bloated.
The tool surface covers the domain well: cached and fresh health data retrieval, daily summaries, bounded detail queries, explicit sync, live heart-rate measurement, and full create/read/update/delete for band alarms and reminders. No critical dead-ends are apparent for the stated purpose.
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Your lab results, DNA files and wearable data explained in your agent, with action plans. EU-hosted.
Your Google Health data (Fitbit, Pixel Watch): sleep, HRV, readiness and biological age.
Run and manage H Company's Computer-Use Agents from any MCP client.
Related MCP Servers
- AlicenseCqualityCmaintenanceEnables 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
- FlicenseNot gradedqualityCmaintenanceEnables AI to query Xiaomi Mi Band health data (steps, sleep, heart rate) from Gadgetbridge SQLite exports via the MCP protocol, allowing natural language questions about daily activity.1-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query personal health data collected by any wearable or phone fitness app through Android Health Connect or Apple Health, exposing read-only tools for metrics like heart rate, sleep stages, VO2 max, and body composition. It can run locally over USB with nothing stored, or be self-hosted on Cloudflare Workers with D1 to retain history beyond Health Connect's 30-day limit.20 npmMIT
- 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