Zepp Life MCP
The Zepp Life MCP server provides tools to cache, synchronize, and query health and fitness data from Zepp Life (Xiaomi/Huami wearables) using cloud sessions or local export files.
Capabilities:
Check connection status and sync health.
Sync selected data types (daily activity, sleep, heart rate, workouts, body measurements) to a local SQLite cache with optional date ranges and force full sync.
Retrieve user profile info, optionally including connected devices.
Get daily activity summaries for specific dates or ranges.
Query time series metrics (steps, distance, active kcal, weight, sleep minutes) with aggregations (sum, avg, min, max, latest) and granularity (day/week/month).
Query sleep sessions with details (light, deep, REM, awake, wake count) and optional nap and sleep stage breakdowns.
Query workouts filtered by activity type, minimum distance, and/or minimum duration.
Query heart rate samples, filterable by type (resting, active, passive, workout).
Query body measurements (weight, BMI, body fat, muscle mass, water percentage) with option for latest only.
Get data coverage showing available date ranges and days with data for each type.
Automatically manage SQLite database schema upgrades and create backups for destructive migrations.
Provides tools to access and sync health data from Zepp Life (Xiaomi ecosystem), including steps, sleep, heart rate, workouts, and body measurements, either via local export files or cloud session.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Zepp Life MCP Show my workouts from the last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Zepp Life MCP
MCP server for Zepp Life data.
This project provides local caching, sync, and MCP tools for Zepp Life data from either exported files or the Zepp cloud session flow.
Supported sources
export_filefor local Zepp exportscloud_sessionforapptoken-based cloud access
Related MCP server: Mi Fitness MCP CN
Current data coverage
The current implementation supports:
daily steps, distance, and active calories
sleep sessions with light, deep, REM, awake time, and wake count
passive and resting heart rate (
slp.rhr)workouts with readable sport names for known Zepp sport codes
weight and body-composition measurements
Cloud coverage can vary by account, region, and upstream endpoint stability. Export mode is the safest option when you need predictable full-history access.
Cloud connections are lazy: server startup and tools/list do not wait for Zepp login. The first data tool establishes one shared connection. If user_id is omitted, the adapter attempts to discover the numeric UID from the last 30 days of band summary data and stores it in the system keyring.
Install
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'Setup
Cloud session
You need an apptoken.
Typical flow:
Open
https://user.huami.com/privacy2/index.htmlSign in to the Zepp Life account
Open browser DevTools
Find the
apptokencookie
Then configure the server:
zepp-life-mcp setup --mode cloud_session --token "<apptoken>" --region eu
zepp-life-mcp doctor--user-id remains supported and can be supplied explicitly if automatic discovery is unavailable.
Export file mode
zepp-life-mcp setup --mode export_file --export-path ~/Downloads/ZeppExport
zepp-life-mcp doctorUse
zepp-life-mcp sync --start-date 2022-01-01 --end-date 2022-12-31
zepp-life-mcp serveMCP client config
Example Claude Desktop config:
{
"mcpServers": {
"zepp-life": {
"command": "zepp-life-mcp",
"args": ["serve"]
}
}
}MCP tools
All tool responses keep the backward-compatible JSON envelope with status: "ok" or status: "error". Failed calls also use MCP isError: true.
Tool | Purpose |
| Report configuration, lazy connection state, and sync health |
| Sync selected data types with optional |
| Return the connected user ID/timezone and accept the compatible |
| Query one date or a date range of daily activity |
| Query |
| Query sleep sessions by sleep start date with optional naps/stages |
| Query workouts with activity, duration, and distance filters |
| Query resting/active/passive/workout heart-rate samples |
| Query weight/body metrics with optional latest-only output |
| Report first/last dates and days with data by type |
Sync and storage behavior
SQLite schema upgrades run automatically through
PRAGMA user_versionmigrations.Destructive rebuild migrations create a timestamped database backup first.
Sync cursors are scoped by source, user, and data type.
Empty successful syncs update the attempt/success state and advance the logical date cursor.
Failed or partial syncs report
failed_data_types; a failed pass never advances its cursor.Existing 0.1.0 databases are upgraded in place without reinterpreting legacy calendar dates.
Example prompts
Show my workouts from the last 30 daysHow has my weight changed this year?Summarize my sleep for the past weekSync my latest Zepp Life data
Commands
zepp-life-mcp --help
zepp-life-mcp setup --help
zepp-life-mcp doctor
zepp-life-mcp sync --help
zepp-life-mcp serveDevelopment
uv run ruff check src tests scripts
uv run pytest -q
uv run python -m buildTroubleshooting
Connection: failedverify
apptokenprovide
--user-idif automatic UID discovery is unavailable
No export data foundverify the extracted archive path
verify that CSV or JSON export files are present
syncreturns no datatry another date range
try export mode if cloud coverage is incomplete
Security
apptokenis stored via the system keyringdo not commit
.env, exported health data, or local SQLite filesprefer interactive setup over pasting secrets into shell history
Disclaimer
This is an unofficial project and is not affiliated with Xiaomi or Zepp Health.
Available Tools
10 toolsget_connection_statusA
Check connection status to data source and last sync time
Inputs: no named parameters.
get_daily_summaryB
Get daily activity summary for a date or date range
Inputs: date, start_date, end_date, timezone.
get_data_coverageA
Get data coverage information - which dates have data for each type
Inputs: data_types.
get_profileC
Get user profile information
Inputs: include_devices.
query_body_measurementsB
Query body measurements (weight, body composition) for a date range
Inputs: start_date (required), end_date (required), metrics, latest_only.
query_heart_rateB
Query heart rate samples for a date range
Inputs: start_date (required), end_date (required), sample_type, limit.
query_metric_seriesC
Query time series data for a specific metric
Inputs: metric (required), start_date (required), end_date (required), granularity, +1 more.
query_sleepB
Query sleep sessions for a date range
Inputs: start_date (required), end_date (required), include_naps, include_stages.
query_workoutsC
Query workouts for a date range
Inputs: start_date (required), end_date (required), activity_types, min_duration_minutes, +1 more.
sync_dataC
Synchronize data from source to local cache
Inputs: data_types, start_date, end_date, force_full_sync.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource or action (connection status, profile, coverage, daily summary, body measurements, heart rate, metric series, sleep, workouts, syncing). No two tools overlap in purpose.
Tools use consistent verb_noun patterns, but with two prefixes: 'get_' for status/profile/coverage/summary and 'query_' for data types. The pattern is clear but not perfectly uniform, causing minor inconsistency.
10 tools is well-scoped for a health data query server, covering connection management, data overview, and various specific data types without excess.
Covers all major data types (daily summary, body, heart rate, sleep, workouts, metric series) and auxiliary functions (status, coverage, profile, sync). Missing write operations, but reads are comprehensive for the stated purpose.
Maintenance
Related MCP Connectors
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseCqualityCmaintenanceMCP server for Mi Fitness cloud data. Provides a local SQLite-backed server to sync and query daily activity, heart rate, and body measurements.128MIT
- AlicenseCqualityCmaintenanceEnables 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.1021MIT
- AlicenseNot gradedqualityCmaintenanceSelf-hosted MCP server that syncs Xiaomi fitness data to SQLite and provides authenticated tools to query health metrics (steps, sleep, HR, etc.) for AI assistants like Grok.GPL 3.0
- AlicenseNot gradedqualityCmaintenanceMCP server exposing self-hosted health data from a vivo WATCH GT via 14 tools for querying metrics like heart rate, SpO2, stress, and sleep over stdio and Streamable HTTP.8AGPL 3.0