Mi Fitness MCP

MCP server for Mi Fitness data.

This project provides a local SQLite-backed MCP server for Mi Fitness cloud data.

Current data coverage

Confirmed with the current cloud flow:

• daily activity

  • steps

  • distance

  • active calories

• heart rate

• body measurements

  • weight

  • BMI

  • fat, water, bone, and muscle metrics

  • visceral fat

  • basal metabolism

• official Xiaomi workout sessions

  • sport/category, duration, distance, calories, pace, cadence, speed, elevation

  • heart-rate zones, training effect/load, recovery time, VO2 max when supplied

Not yet supported:

• sleep. The available endpoint and payload contract have not been confirmed, so sleep is intentionally not advertised or synchronized yet.

Related MCP server: Mi Fitness MCP CN

Install

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

Setup

You need:

• userId

• passToken

Typical flow:

1. Open https://account.xiaomi.com

2. Sign in to your Xiaomi account

3. Open browser DevTools

4. Inspect cookies for account.xiaomi.com

5. Copy userId and passToken

Configure the server. The interactive prompt hides passToken and stores credentials in the system keyring:

mi-fitness-mcp setup --mode mi_fitness_cloud --user-id "<userId>" --region ru
mi-fitness-mcp doctor

For automation, prefer --pass-token-stdin or MI_FITNESS_PASS_TOKEN. The legacy --pass-token argument remains available for backward compatibility but is deprecated because command-line arguments may be visible in shell history and process listings.

Xiaomi accounts may be hosted in regional Mi Fitness backends. ru remains the default for compatibility, while the adapter can discover and persist another accepted global/EU region such as de, i2, sg, or us. This does not change the Xiaomi userId + passToken login flow.

For local endpoint exploration there is also a probe script:

uv run python probe_mifitness.py --user-id "<userId>"

The probe prompts for passToken without echo. For automation, provide MI_FITNESS_USER_ID and MI_FITNESS_PASS_TOKEN, or use --pass-token-stdin with a protected input source. Secret command-line arguments are intentionally unsupported.

Use

mi-fitness-mcp sync --start-date 2025-04-01 --end-date 2025-05-31
mi-fitness-mcp serve

MCP client config

Example Claude Desktop config:

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

Example prompts

• Show my daily activity for the last 14 days

• How has my resting heart rate changed this month?

• Summarize my latest body measurements

• Show my running workouts from the last 30 days

• Summarize workout volume by sport or ISO week

• Compare this month's workout totals with last month

• What were my longest-distance and fastest-pace workout records?

• Sync my latest Mi Fitness data

MCP tools

• get_connection_status

• sync_data

• get_profile

• get_daily_summary

• query_metric_series

• query_heart_rate

• query_body_measurements

• query_workouts

• summarize_workouts

• get_workout_records

• compare_workout_periods

• get_data_coverage

Existing tool names, argument semantics, and status: ok|error response envelopes remain backward compatible. Sync reports successful and failed data types separately; a partial sync returns ok, while a sync where every requested type fails returns error.

Commands

mi-fitness-mcp --help
mi-fitness-mcp setup --help
mi-fitness-mcp doctor
mi-fitness-mcp sync --help
mi-fitness-mcp serve

Development

uv run ruff check .
uv run pytest -q
uv run python -m build

The current test suite contains 89 tests and reports 78% statement coverage. CI runs on Python 3.11, 3.12, and 3.13, keeps HTTP tests offline with respx, and installs the built wheel in a clean environment before checking mi-fitness-mcp --help.

Configuration compatibility

• SQLite schema changes use the existing versioned migration runner; existing tables and data are preserved.

• busy_timeout configures SQLite lock waiting in milliseconds and defaults to 5000.

• auto_sync_on_start, stale_after_minutes, store_raw_payloads, default_lookback_days, and logs_path are retained for config-file compatibility but are deprecated no-ops.

Troubleshooting

• Connection: failed

  • verify userId and passToken

  • verify the configured region; global/EU accounts may resolve to another backend

• Credentials not found

  • run setup again

• sync returns no data

  • try another date range

  • verify that the data actually exists in Mi Fitness cloud

Security

• passToken is stored via the system keyring

• userId is masked in CLI and MCP diagnostics; passToken is never printed

• do not commit .env, local config files, or real credentials

• rotate tokens if they were pasted into chats or shell history

Disclaimer

This is an unofficial project and is not affiliated with Xiaomi.