miband-mcp

Chenxi · Let AI read your wrist

A Python MCP Server with zero third-party dependencies: reads the SQLite database exported by Gadgetbridge (Xiaomi Band health data), and exposes it via the MCP protocol to any MCP-capable AI client (Reasonix / Claude / Cursor / Kimi / GLM, etc.), allowing AI to answer questions like "How many steps did I take today?" and "How did I sleep last night?".

Architecture

小米手环 9 / 9 Pro / 10 → Gadgetbridge（手机端采集）→ SQLite 导出 → miband-mcp（读库+聚合）→ MCP 协议 → AI

Related MCP server: garmin-givemydata

Provided Tools

Quick Start

1. Prepare the Data Source

• Install Gadgetbridge on your phone (the official repository is on Codeberg, not GitHub)

• Follow the official pairing guide to connect the band (Xiaomi Band 9 requires the band to initiate the connection: Band settings → System operations → Connect to a new phone)

• Extract the 32-character encryptKey from the Mi Fitness logs as the pairing key (note: once bound, it cannot be unbound, otherwise the key becomes invalid)

• Gadgetbridge settings → Automation → Enable Auto-export database

2. Run the MCP Server

# 零依赖，纯标准库
python miband_mcp.py --db /path/to/gadgetbridge.db

3. Connect to AI (using Reasonix as an example)

[[plugins]]
name    = "miband"
type    = "stdio"
command = "python"
args    = ["<路径>/miband_mcp.py", "--db", "<路径>/gadgetbridge.db"]
auto_start = true

Then start a new session with /new for it to take effect.

⚠️ Current Limitations

Data synchronization is manual: This project reads the SQLite database snapshot exported by Gadgetbridge and does not automatically pull data from the band.

Current workflow:

1. Band data is collected by Gadgetbridge (requires prior synchronization)

2. Manually send the exported database file (.db) to the computer running miband-mcp

3. AI reads the latest data from the database via MCP tools

Therefore: AI answers based on "the most recently synchronized data", not real-time data. If you need real-time reading, you can combine a Termux script + scheduled synchronization to automatically push the .db file to your computer (this project has not implemented this yet, PRs are welcome).

Development

python -m unittest discover -s tests -v   # 34 个测试，零依赖

License

MIT © ChenxiDawn · 晨熹