English version: README.en.md

米桥（Mi Fitness Data Bridge）

Local-first data bridge that exports your own 小米运动健康 data to SQLite, JSON, CSV, Python, and MCP-compatible tools.

The 小米运动健康 App is happy to show you your steps, sleep, and heart rate — but never lets you take that data with you. This bridge puts your own data into a SQLite file on your own hard drive.

Trademark notice: 小米, 米家, and Mi Fitness are trademarks of 小米 Corporation. This project is an unofficial community project and is not affiliated with or endorsed by 小米.

The experimental cloud adapter may become unusable at any time because 小米 changes its private APIs. Use it only on accounts and data you are authorized to access.

Verified in practice

Recorded on 2026-07-20 on Windows (Python 3.14) from a commit on the main branch. All data are synthetic and involve no credentials or network access. (Test counts re-checked and updated on 2026-08-17.)

Test suite:

$ python -m pytest -q -p no:cacheprovider
........................................................................ [ 96%]
...                                                                      [100%]
75 passed in 10.27s

End-to-end synthetic demo (examples/synthetic_demo.py first populates the local SQLite cache with synthetic records, then runs the real JSON/CSV export pipeline):

$ python examples/synthetic_demo.py
Seeded synthetic database: C:\Users\<you>\AppData\Local\Temp\mi-fitness-demo-53el7cfh\mi_fitness.db
  daily_activity: 2026-07-15 .. 2026-07-15 (1 day(s))
  sleep: 2026-07-14 .. 2026-07-14 (1 day(s))
  workouts: 2026-07-15 .. 2026-07-15 (1 day(s))
  body_measurements: 2026-07-15 .. 2026-07-15 (1 day(s))

Export completed
  mi_fitness.json
  daily_activity.csv
  sleep.csv
  workouts.csv
  body_measurements.csv
  heart_rate.csv
  spo2.csv
  stress.csv
  abnormal_heart_beat.csv

JSON envelope:
  schema_version: 1.0
  source: mi_fitness_data_bridge
  records.daily_activity: 1 row(s)
  records.sleep: 1 row(s)
  records.workouts: 1 row(s)
  records.body_measurements: 1 row(s)

Sample sleep row (synthetic):
  start_at=2026-07-14T23:20:00 end_at=2026-07-15T07:05:00
  duration_minutes=465 score=86
  stages=[{"stage": "deep", "minutes": 82}, {"stage": "light", "minutes": 271}, {"stage": "rem", "minutes": 88}, {"stage": "awake", "minutes": 24}]

Related MCP server: garmin-givemydata

Merged health-assistant project

The health-assistant project (a local-first personal health dashboard: Strava, sleep, body composition, diet analysis) has been merged into this repository, and its original repository has been archived. The absorbed assets live under the docs/health-assistant/ directory:

• analytics.py — zero-dependency reference implementation of a training/recovery summary and recommendation engine (7-day training statistics, acute-to-chronic workload ratio, readiness checks, daily training recommendations).

• coaching_methodology.md — the interpretable cycling coaching, body composition, and sports nutrition methodology behind it.

• README.md — full migration notes, including the parts intentionally not ported (FastAPI dashboard, Strava OAuth/Webhook pipeline, meal photo analysis) and the reasons.

What this project does

• Reads 小米运动健康 data through an experimental China-region cloud adapter.

• Stores normalized records in a local SQLite database.

• Exports portable JSON or CSV without credentials.

• Exposes local MCP query tools for personal automation.

• Provides a reusable connector implementation for downstream projects (e.g., a personal fat-loss advisor).

It deliberately does not provide medical advice, weight-loss guidance, hosted account access, or multi-user cloud services.

Why this bridge?

Supported datasets

• Daily activity: steps, distance, active calories, and active minutes.

• Sleep records and sleep stages.

• Workout records.

• Body measurements: weight and available body composition fields.

• Heart-rate samples, including resting heart rate when available.

• Blood oxygen (SpO2), stress, and abnormal heartbeat events (depending on account/device availability).

Actual availability varies by device, account region, firmware, and 小米 upstream services.

Installation

git clone https://github.com/shkyyy18/mi-bridge.git mi_fitness_data_bridge
cd mi_fitness_data_bridge
python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Windows Git Bash:

source .venv/Scripts/activate
pip install -e ".[dev]"

macOS/Linux:

source .venv/bin/activate
pip install -e '.[dev]'

Configuration

A more secure interactive configuration path avoids writing the passToken directly into your shell history:

mi-fitness-bridge setup
mi-fitness-bridge doctor

When available, credentials are stored via the local keyring. Some fallback keyring implementations may not store secrets securely; please understand your OS's keyring behavior before using.

How to get user_id and passToken

This bridge uses 小米 account-level credentials (the same login state as the 米家 App). Use either of the following two methods:

Method 1: manual copy from the browser

1. Open account.xiaomi.com in your browser and sign in with your 小米 account (the same account as the 小米运动健康 App).

2. Open Developer Tools (F12) → Application → Cookies → https://account.xiaomi.com.

3. Copy the values of the userId and passToken cookies and paste them when mi-fitness-bridge setup prompts you.

Method 2: QR-code login tool

Sign in once by scanning a QR code with the open-source mijia-api:

pip install mijiaAPI
python -c "from mijiaAPI import mijiaAPI; mijiaAPI().login()"   # 终端出二维码，用米家 App 扫码

The login state is saved by default at ~/.config/mijia-api/auth.json (on Windows, %USERPROFILE%\.config\mijia-api\auth.json). The userId and passToken inside it can be used directly with this bridge — 小米 account-level credentials work across services, and the bridge uses them to obtain a 小米运动健康 (sid=miothealth) session. Note that auth.json stores credentials in plaintext: after entering the userId and passToken into this bridge (system keychain), it is recommended to delete that file.

Note:

• The passToken expires; when doctor reports authentication failure, simply re-fetch it using the steps above.

• For the browser method, sign in from your usual network environment; frequent or off-site operations may trigger 小米 account risk control (slider/SMS verification). If you hit risk control, switch to the QR-code method.

• Cookie names and the login flow are based on actual testing in 2026-08; they may vary by account region, device, or risk-control policy. 小米 may also adjust its private APIs at any time (see the experimental notice at the top).

• These two values are equivalent to your account login state. Do not leak them, and do not commit them to Git.

Sync

mi-fitness-bridge sync --start-date 2026-07-01 --end-date 2026-07-15

Or sync only one dataset:

mi-fitness-bridge sync --type sleep --start-date 2026-07-01 --end-date 2026-07-15
mi-fitness-bridge sync --type body_measurements --start-date 2026-07-01 --end-date 2026-07-15

The database defaults to the platform user data directory (determined by platformdirs). sync, export, serve, and doctor all support moving it with the --db flag or the MI_FITNESS_DB_PATH environment variable. Precedence: command line > environment variable > default location. Note that platformdirs does not respond to the LOCALAPPDATA environment variable on Windows; to customize the path, use one of the two methods above:

mi-fitness-bridge sync --db ./data/mi_fitness.db --start-date 2026-07-01 --end-date 2026-07-15
export MI_FITNESS_DB_PATH=./data/mi_fitness.db

Known limitation: incremental sync without a date argument starts from the time of the last local record; upstream corrections or backfills of earlier history are not pulled automatically. If needed, explicitly re-run that interval with an earlier --start-date (idempotent overwrite; no duplicate records are produced).

Export

Generate a portable JSON file:

mi-fitness-bridge export --format json --output exports/mi_fitness.json

Generate one CSV file per dataset:

mi-fitness-bridge export --format csv --output exports/csv

Filter by dataset and date:

mi-fitness-bridge export --format json --type sleep \
  --start-date 2026-07-01 --end-date 2026-07-15 \
  --output exports/sleep.json

Export files never contain the saved 小米 passToken, but they do contain identifying columns such as plaintext user_id — export files are sensitive personal data, so store them carefully. Exported health records are ignored by Git by default.

See Export format for export format details (JSON envelope structure, CSV layout, closed-interval date filtering rules).

MCP service

The compatibility command remains available:

mi-fitness-bridge serve
# legacy alias
mi-fitness-mcp serve

Available tools include connection status, sync, coverage, daily summary, body measurements, sleep, workouts, heart rate, blood oxygen (SpO2), and stress queries, as well as the agent-oriented workout_series workout time-series tool — it automatically downsamples according to the hard max_points cap (fixed time-bucket means, aggregated inside SQLite), and reports downsampled, source_points, returned_points, and method truthfully in the response, while also providing full-precision statistics (avg/min/max/percentiles) and time in heart-rate zones. List/summary tools such as query_workouts and get_daily_summary include data_quality (covered days, missing metrics, last sync time).

Client integration example (configuration JSON for MCP clients such as Claude Code / Codex):

{
  "mcpServers": {
    "mi-bridge": {
      "command": "mi-fitness-bridge",
      "args": ["serve"]
    }
  }
}

Note: serve is a stdio service; it communicates with the client over standard input/output, not an HTTP service. Running it directly in a terminal will look like it is “stuck” — that is it waiting for MCP messages from the client, which is normal. For everyday use, let your MCP client start it with the configuration above.

Use as a Python dependency

The normalized adapter remains available under a compatible module name:

from mi_fitness_mcp.adapters.mi_fitness_cloud import MiFitnessCloudAdapter

Downstream projects should install this package rather than vendor or copy the connector source code.

License

License history: versions released before 2026-08-03 were licensed under MIT (the MIT attribution of the upstream kubulashvili/mi-fitness-mcp and binglua/mi-fitness-mcp-cn is retained in the NOTICE section at the top of LICENSE); new code in the current version is AGPL-3.0-only. See LICENSE and THIRD_PARTY_NOTICES.md for details.

Privacy and security

• Safeguard the passToken, local database, export files, and logs; do not leak them.

• Export files do not contain the passToken, but they do contain identifying columns such as plaintext user_id, and are equally sensitive personal data.

• Do not run this bridge as a public credential proxy.

• Do not commit real health data or screenshots containing personal metrics.

• Always use synthetic data in bug reports and documentation.

• This software is only for personal data access and engineering research, not for diagnosis or treatment.

See SECURITY.md for responsible disclosure and THIRD_PARTY_NOTICES.md for provenance.

Development

pip install -e '.[dev]'
python -m pytest -q -p no:cacheprovider
python -m ruff check src tests

Release

See CHANGELOG.md for version history and docs/release-checklist.md for release and post-release checklist items.

Related projects

• garmin-mcp — a local-first MCP service for Garmin data. It shares the agent-safe-series/v1 data contract with this project (time-series downsampling field semantics are byte-for-byte aligned), so the same AI agent can seamlessly consume data from both services.

Support this project

If this tool helped you, give me a star on GitHub.