Skip to main content
Glama

Zepp Life MCP

CI Release License

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_file for local Zepp exports

  • cloud_session for apptoken-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:

  1. Open https://user.huami.com/privacy2/index.html

  2. Sign in to the Zepp Life account

  3. Open browser DevTools

  4. Find the apptoken cookie

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 doctor

Use

zepp-life-mcp sync --start-date 2022-01-01 --end-date 2022-12-31
zepp-life-mcp serve

MCP 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

get_connection_status

Report configuration, lazy connection state, and sync health

sync_data

Sync selected data types with optional start_date, end_date, and force_full_sync

get_profile

Return the connected user ID/timezone and accept the compatible include_devices option

get_daily_summary

Query one date or a date range of daily activity

query_metric_series

Query steps, distance_m, active_kcal, weight_kg, or sleep_minutes by day/week/month with sum/avg/min/max/latest

query_sleep

Query sleep sessions by sleep start date with optional naps/stages

query_workouts

Query workouts with activity, duration, and distance filters

query_heart_rate

Query resting/active/passive/workout heart-rate samples

query_body_measurements

Query weight/body metrics with optional latest-only output

get_data_coverage

Report first/last dates and days with data by type

Sync and storage behavior

  • SQLite schema upgrades run automatically through PRAGMA user_version migrations.

  • 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 days

  • How has my weight changed this year?

  • Summarize my sleep for the past week

  • Sync 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 serve

Development

uv run ruff check src tests scripts
uv run pytest -q
uv run python -m build

Troubleshooting

  • Connection: failed

    • verify apptoken

    • provide --user-id if automatic UID discovery is unavailable

  • No export data found

    • verify the extracted archive path

    • verify that CSV or JSON export files are present

  • sync returns no data

    • try another date range

    • try export mode if cloud coverage is incomplete

Security

  • apptoken is stored via the system keyring

  • do not commit .env, exported health data, or local SQLite files

  • prefer 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 tools
get_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

    B3.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    10 tools is well-scoped for a health data query server, covering connection management, data overview, and various specific data types without excess.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Enables 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.
      10
      21
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Self-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
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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.
      8
      AGPL 3.0