Skip to main content
Glama
miband-health-mcp

miband-health-mcp

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 tools
delete_band_scheduleA
Destructive

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_reportA
Read-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_healthA
Read-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_alarmA
Destructive

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_reminderA
Destructive

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

    A4.2/5.0

    Scored across 11 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      10
      21
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets 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 PyPI
      5
      MIT