mifit

mifit

Read your own Mi Fitness (小米运动健康) data from the Xiaomi cloud: a small Python library, a command-line tool and an MCP server for AI assistants.

The Mi Fitness app syncs your steps, heart rate, sleep and more to the Xiaomi cloud, but Xiaomi offers no public API for individuals. mifit signs in to your own account by QR code, reads that synced data and returns it as JSON or as Python objects, so you can build on it.

Unofficial. Not affiliated with, endorsed by or supported by Xiaomi.

See Disclaimer.

What it reads today

"Checked against the app" means the values were compared with what the Mi Fitness app shows, on one real account (China region, UTC+8). More is planned. Meanwhile, mifit raw (in Python raw_window and daily_report) returns the rows of any other key of the fitness-data or (with --daily) daily-report endpoint, uninterpreted.

What changed in each version, breaking changes included, is in CHANGELOG.md.

Install

Requires Python 3.12 or later; uv installs one for you if needed.

uv tool install mifit     # recommended: its own environment, `mifit` on your PATH

pipx install mifit # the same, with pipx pip install mifit # into the current environment, to use it as a library

Upgrade: uv tool upgrade mifit (or pipx upgrade mifit, pip install -U mifit).

Log in

mifit login

A QR code is drawn in the terminal, with the login URL below it. Scan it with the Xiaomi / Mi Fitness app on your phone (or open the URL) and approve the sign-in. Your password never passes through mifit.

The session is saved to ~/.mifit/session.json (on Windows %USERPROFILE%\.mifit\session.json). It grants access to your Mi Fitness account's health data (not only reading). It also holds your account's passToken, which mifit uses to renew the session when it expires. The passToken is account-level: it can obtain tokens for any Xiaomi service, so the file grants access to your whole Xiaomi account, not just your Mi Fitness health data, and it stays useful long after the session token itself has expired. Treat it like a password, and do not share it or commit it. On Linux and macOS the file is readable by you only; on Windows it relies on your user profile's permissions.

If Xiaomi asks for an extra security confirmation, mifit login prints a URL: open it, confirm, then run mifit login again.

Use with an AI assistant (MCP)

mifit mcp is a Model Context Protocol server: AI assistants such as Claude Desktop, Claude Code, Cursor and VS Code start it on your computer and read your Mi Fitness data when you ask them about it ("how did I sleep last week?").

What leaves your computer. The results of the tools the assistant calls are sent to the assistant's model provider, like the rest of the conversation. The login stays in ~/.mifit on this computer: the server runs locally on stdin/stdout, opens no network port, never puts a credential in a result, and only reads your health data (the login tools save the new session to ~/.mifit). GPS tracks are off: the server gives a workout's route only when it was started with --allow-gps (in the Claude Desktop extension: when its Allow GPS tracks switch is on) *and* the assistant asks for it, and a route shows where you were, including where you live. (To serve assistants on other machines instead, see Remote access (HTTP): that server does open a port.)

Log in once, in a terminal:

uvx mifit login

(or mifit login after uv tool install mifit). Without a terminal, ask the assistant to log you in: it calls login_start, which returns the QR code to scan with the Xiaomi or Mi Fitness app.

Add the server to your assistant. uvx (part of uv) downloads and runs mifit when needed:

claude mcp add --scope user mifit -- uvx mifit mcp

// Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json

// (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) {"mcpServers": {"mifit": {"command": "uvx", "args": ["mifit", "mcp"]}}}

// Cursor: ~/.cursor/mcp.json {"mcpServers": {"mifit": {"type": "stdio", "command": "uvx", "args": ["mifit", "mcp"]}}}

// VS Code: .vscode/mcp.json {"servers": {"mifit": {"command": "uvx", "args": ["mifit", "mcp"]}}}

After uv tool install mifit, the command can be mifit with the argument mcp instead. To allow GPS tracks, add --allow-gps after mcp (["mifit", "mcp", "--allow-gps"]).

mifit is also listed in the official MCP Registry as io.github.Jenwein/mifit, for clients that install servers from it.

Claude Desktop, in one click. Download mifit- .mcpb from the latest release and open it (or install it from Claude Desktop's Settings → Extensions): Claude Desktop (Windows, macOS) offers to install the extension. Its settings have an Allow GPS tracks switch, off by default. The extension runs the mifit release it came with: to update, install the .mcpb of the new release. Use either the extension or the JSON config above, not both.

Tools. Each reads one kind of data; dates are local calendar days.

Results are the records of the Python API with local times (2026-10-07T23:12:00+08:00) instead of Unix seconds, never raw. Dense data is cut down to at most 500 rows and the notes say how. A result is kept for five minutes, so asking again sends no new requests.

Ask in your own words; the assistant picks the tools. For example: "Did my resting heart rate go up this month?"

Remote access (HTTP)

mifit mcp --transport http runs the same server as a long-running service on streamable HTTP, so assistants on other machines can use it. Run it on the machine that keeps the login, such as a home server on your Tailscale or Headscale tailnet:

uv tool install mifit

mifit login # once, on the server: the session is saved in the server's ~/.mifit mifit mcp --transport http --host 100.64.0.5 --port 8766 --allowed-host mifit.ts.internal:8766

• --host ADDRESS: the address to listen on. The default, 127.0.0.1, serves this machine only; give the server's tailnet address to serve the tailnet. 0.0.0.0 listens on every interface.
• --port PORT: default 8766. --path PATH: the endpoint, default /mcp.
• --allowed-host HOST[:PORT]: a Host header to accept. The server answers only requests whose Host header it knows, and refuses the others with HTTP 421 (the MCP SDK's DNS rebinding protection, always on). It knows 127.0.0.1, localhost and [::1] (any port) when it listens on loopback or on every interface, and its --host address with the port otherwise. Add each name the clients connect by, as they send it: mifit.ts.internal:8766, or mifit.ts.internal:* for any port. Repeat the option for more names.
• --allow-gps works as it does on stdio.

Dates and local times are counted in the server's time zone. If it is not yours, start the server with yours, such as TZ=Asia/Shanghai (in the systemd unit below, its Environment= line).

At startup the server prints its URL and the Host headers it accepts on standard error. Then add it to each assistant by its URL:

claude mcp add --scope user --transport http mifit http://mifit.ts.internal:8766/mcp

codex mcp add mifit --url http://mifit.ts.internal:8766/mcp

Other clients take the URL as a streamable HTTP (http) server. To log in without a terminal on the server, ask the assistant: login_start returns the QR code in the tool result, nothing opens on the server's screen, and the session is saved on the server. If Xiaomi asks for a security confirmation, run mifit login in a terminal on the server (over SSH, say) and follow it.

Security. The HTTP server has no authentication. Anyone who can reach its port can read your Mi Fitness data through it, and can start a login that replaces you