zepp-mcp

Read your Zepp / Amazfit health and workout data from any MCP client.

🖥️ 100% local · stdio transport · no server, no cloud relay, no third party

Ask your assistant "how has my SWOLF trended this month?" or "did I sleep worse on days I trained hard?" and get answers from your own watch data.

› How have my swims gone this week?

  Date     Distance   SWOLF   Strokes   Avg HR
  Aug 16      567 m      36       323      131
  Aug 15      756 m      38       481      139
  Aug 14      630 m      38       361      138

  SWOLF is trending down across the week — you're covering
  each length with fewer strokes and less time.

Built on the private Zepp mobile API, with every decoder verified against real captured responses.

Contents

• Features · Setup for Users · Developer Setup

• Architecture · Tools · Privacy · How it works

• Known gaps · Contributing · Legal and safety

Related MCP server: Mi Fitness MCP

Features

• Every sport, named honestly. 141 Zepp sport codes are named — running, cycling, swimming, team and racket sports, gym work, martial arts, dance, water and winter sports and more. Each carries a sport_name_confidence (confirmed on real data, corroborated by other clients, or catalogued from the watch's sport list) and a sport_family, so "all my cycling" covers outdoor, indoor, road and mountain rides. Each family has its own metrics: SWOLF and stroke counts for swims, pace and cadence for runs, sets and reps for the gym, jump counts for skipping. You can name any code yourself with ZEPP_SPORT_CODES.

• Sleep with all four stages. Light, deep, REM and awake, not just the two most implementations report.

• Sleep in depth. Latency, time in bed and efficiency, plus each morning's overnight HRV, readiness score, sleep respiratory rate and overnight SpO₂ (ODI), for one night or a whole month.

• Recovery and stress. Readiness and its sub-scores, HRV (overnight and all-day RMSSD), resting-HR trend, all-day stress, PAI, Body Charge, respiratory rate, SpO₂ spot checks and daily goals, each with a summary and a trend line.

• Training analytics. Volume by week, month or sport. Aggregate pace computed correctly: total distance over total moving time, never an average of paces. Records within a range, Zepp's own personal-best flags, and progression series for 20 metrics (SWOLF, pace, cadence, VO₂ max, ground contact time, …).

• One-call overviews. "How have the last 30 days gone?" is a single tool call.

• Per-minute heart rate and steps, with no-reading markers preserved as null rather than dropped, and hourly step totals.

• Lactate threshold HR and pace, tracked over time from the watch's own estimate log — the anchor for every training zone — plus VO2 max, per-run time-in-zone distribution and, once a Zepp Coach plan is active, per-session plan progress.

• Running dynamics: ground contact time, vertical oscillation, running power and stride ratio, alongside the elevation and climb fields runs share with hikes and rides.

• Lap and stream decoding for individual workouts: per-length swim laps, per-set strength sets (reps, load, rest), km splits, cadence and stride per second, and pauses. Moving and paused time are separated on every workout.

• Smart-scale body composition. Weight, height and BMI, plus body fat, water and muscle percentages, bone mass, visceral fat and BMR when synced from a real bio-impedance scale rather than a manual entry.

• Honest about uncertainty. Unverified units are flagged, unknown sport codes are named as unknown, and an empty response is never reported as confirmed absence.

• Nothing stored. No health data touches disk. Only the API token is cached, so restarts don't trigger a fresh login.

• Local by construction. A stdio child process on your machine. No hosted service, no relay, no listening port.

Setup for Users

If you just want to use the server with your MCP client, you don't need to clone the repository. You can run it directly using uvx (the uv tool runner).

Add the server to your claude_desktop_config.json and pass your credentials securely via environment variables:

{
  "mcpServers": {
    "zepp": {
      "command": "uvx",
      "args": ["zepp-mcp"],
      "env": {
        "ZEPP_EMAIL": "your-email@example.com",
        "ZEPP_PASSWORD": "your-password"
      }
    }
  }
}

• macOS · ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows · %APPDATA%\Claude\claude_desktop_config.json

Restart the app completely afterwards.

Install the server globally for Claude Code. Make sure to pass your credentials securely as environment variables:

export ZEPP_EMAIL="your-email@example.com"
export ZEPP_PASSWORD="your-password"
claude mcp add zepp -s user -- uvx zepp-mcp

-s user makes it available in every project. Verify with claude mcp list.

Create or edit ~/.gemini/config/mcp_config.json (global, applies to all projects):

{
  "mcpServers": {
    "zepp": {
      "command": "uvx",
      "args": ["zepp-mcp"],
      "env": {
        "ZEPP_EMAIL": "your-email@example.com",
        "ZEPP_PASSWORD": "your-password"
      }
    }
  }
}

For a single project only, place the same file at .agents/mcp_config.json in your project root instead.

Restart the Antigravity session afterwards — MCP servers are loaded at startup.

Developer Setup

If you want to contribute, run tests, or modify the code locally. Requires uv and Python 3.11+.

git clone https://github.com/DhavalBhimani44/zepp-mcp.git
cd zepp-mcp
uv sync

cp .env.example .env      # add ZEPP_EMAIL and ZEPP_PASSWORD
chmod 600 .env

Verify it works — the test suite needs no network and no credentials:

uv run pytest              # 264 tests against the fixture corpus
uv run tools/smoke_test.py # starts the server, lists its tools

Then check your account connects:

uv run python -c "from zepp_mcp.server import zepp_auth_status; print(zepp_auth_status())"

Connecting a local clone

If you're testing your local clone, configure your client to use the local directory instead of uvx.

{
  "mcpServers": {
    "zepp": {
      "command": "uv",
      "args": ["--directory", "/path/to/zepp-mcp", "run", "zepp-mcp"]
    }
  }
}

(Credentials are read from your local .env, so they stay out of the config file)

claude mcp add zepp-local -s user -- uv --directory /path/to/zepp-mcp run zepp-mcp

Add to ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace):

{
  "mcpServers": {
    "zepp": {
      "command": "uv",
      "args": ["--directory", "/path/to/zepp-mcp", "run", "zepp-mcp"]
    }
  }
}

Credentials are read from your local .env.

Architecture

Everything inside the dashed box runs on your laptop. There is no server in the middle, and the single outbound connection is the same HTTPS call the Zepp app itself makes.

flowchart TB
    subgraph machine["YOUR MACHINE - the whole system lives here"]
        direction TB

        client["<b>MCP Client</b><br/>Claude Code · Claude Desktop<br/>any MCP host"]

        subgraph proc["zepp-mcp · local child process"]
            direction TB
            tools["<b>server.py</b><br/>14 MCP tools"]
            norm["<b>workouts.py · decode.py · events.py · analysis.py</b><br/>stream decoding · lap splitting · event decoding<br/>sentinel stripping · unit attribution · aggregates"]
            http["<b>client.py</b><br/>empty-200 classifier · re-auth once<br/>pagination · in-memory cache · pacing"]
            auth["<b>auth.py</b><br/>password login · region discovery"]
            tools --> norm
            norm --> http
            http --> auth
        end

        env["<b>.env</b><br/>credentials · mode 0600"]
        cache[("<b>~/.zepp-mcp/token.json</b><br/>API token only · mode 0600<br/>no health data on disk")]
    end

    zepp["<b>Zepp Cloud API</b><br/>api-mifit-region.zepp.com"]

    client <-->|"<b>stdio</b> · JSON-RPC over stdin/stdout<br/>no network · no open port"| tools
    env -.->|"read at startup"| auth
    auth -.->|"token only"| cache
    http <-->|"<b>HTTPS · read-only</b><br/>the only outbound connection"| zepp

Reading the diagram

Lifecycle. You never start the server. Your MCP client spawns it when it launches, speaks JSON-RPC over the pipe, and kills it on exit. Every session gets a fresh process — which is exactly why the token is cached, so a restart does not mean a fresh login against Zepp's shared 10-attempt lockout.

Tools

Every value says whether it was measured by the watch or derived by the server (aggregate pace, weighted averages, trends), and every metric carries a verification level. The full inventory, with evidence per row, is in docs/capability-matrix.md.

Configuration

Privacy

This is health data. The design reflects that.

• Nothing is hosted. zepp-mcp is a local stdio process. There is no backend I run, no account to create, and no relay your data passes through.

• No health data is written to disk. Responses are cached in memory only, and never for long: anything covering the last week (or coming back empty) expires after five minutes, because a watch that syncs late fills in past days; older ranges expire after an hour.

• Only the API token is cached, at ~/.zepp-mcp/token.json (mode 0600). Set ZEPP_TOKEN_CACHE=off to disable and log in every time.

• Credentials live in .env, never in client config files, never in source, never in logs.

• The fixture corpus is anonymised and CI-gated. Captures come from a real account, so tools/check_fixtures.py runs on every push and fails the build on any name, MAC address, serial number, email, coordinate stream or credential-shaped token. GPS-bearing workouts are excluded entirely — a running route starts where you live.

• Location never reaches the model by accident. Split rows embed a geohash of where each kilometre ended; it is stripped at decode time. GPS streams are returned only when explicitly requested.

• Device secrets are allowlisted out. Device records carry the watch's Bluetooth pairing key. Only named, safe fields (model, firmware, data source id) are ever returned.

If you contribute a fixture, run uv run tools/anonymize_fixtures.py first, and install the pre-push hook — force pushes are blocked on main, so a bad push cannot be rewritten away:

ln -sf ../../tools/hooks/pre-push .git/hooks/pre-push

See CONTRIBUTING.md.

How it works

A few decisions are load-bearing, and each came from evidence rather than assumption.

Zepp returns HTTP 200 with an empty body both for "no data in this range" and for requests it silently rejects. The two are indistinguishable from a single response, so the client reports status: "no_data" with that ambiguity attached, and the server instructs the model not to state it as confirmed absence. Rendering it as "you didn't exercise that week" turns a fault into a fact.

heart_rate and temperature are delta-encoded; currentDistance and speed are absolute. Decoding one as the other yields entirely plausible numbers, so each was settled by decoding both ways and checking against the workout's own summary totals — currentDistance resolves to 75600 cm against a reported 756 m, and speed integrates to 1061 m against a reported 1064 m.

Stage modes 4/5/8/7 are light/deep/REM/awake, verified by recomputing each night's stage minutes and matching the summary's own lt/dp/dt/wk fields across three nights. Reporting deep + light as total sleep silently drops REM — 73, 53 and 96 minutes on those nights.

-1 is the general not-applicable marker, but altitude uses -20000, angle -361, elevation -100, temperature -274 (below absolute zero), and SpO₂ uses both -1 and 0. They are stripped per field family. Values also arrive as strings about half the time (dis is "756.0"), so stripping coerces before comparing — otherwise swolf: "-1" survives onto a bike ride.

elevationGain is centimetres: a hike reporting 27961 sits beside its own altitude_ascend: 279 in the same row. It is converted and renamed to elevation_gain_metres, because 27961 emitted raw reads as a plausible metre figure and turns a 280 m hill into an alpine ascent.

Workouts carry syncedTimezone; daily data carries a tz offset in seconds. Rendering in UTC turns an 08:05 swim into 02:35 and moves a 00:20 bedtime to the previous evening.

Sport codes are numeric with no name anywhere in the payload, so the map was built by confirming each code against the Zepp app. An unrecognised code reports as unknown_sport_<code> rather than a guess. Streams with unconfirmed units carry unit_verified: false, and unrecognised streams are returned raw rather than decoded with an assumed encoding.

Known gaps

Documented rather than hidden — zepp_describe_schema reports these at call time too.

Help with any of these is welcome — see CONTRIBUTING.md.

Examples

Three runnable analyses, with real output, live in examples/: swim technique against volume, training load against recovery, and within-session pacing decay.

Project layout

zepp_mcp/           the server
  auth.py           password login, region discovery, token cache
  client.py         HTTP, empty-200 classification, re-auth
  decode.py         band data, workout streams, laps, splits, gait
  events.py         readiness, HRV, respiratory rate, stress, PAI, SpO2, Body Charge
  workouts.py       index row -> normalised, sport-aware summary
  analysis.py       aggregates, records, trends (all derived, all labelled)
  metrics.py        metric catalogue: units, sources, verification levels
  sports.py         every sport code, with confidence, family and sources
  codes.py          confirmed sport codes, sleep stages, sentinels
  body.py           scale readings, profile, device allowlist
  server.py         MCP tool definitions
examples/           runnable analyses with real output
tools/              anonymiser, privacy gate, smoke test, endpoint probe
tests/fixtures/     anonymised real API captures
docs/               design spec and API reverse-engineering findings
spike/              the throwaway probe that produced the fixtures

Contributing

Contributions are welcome — see CONTRIBUTING.md for the development setup, testing approach, and the rules around fixtures and personal data. By participating you agree to the Code of Conduct.

Especially useful: sport codes from watches other than the maintainer's, and confirmation of the units flagged above.

Legal and safety

• Not medical advice. This is a data-access tool. Nothing it returns is a diagnosis, and it should not be used to make medical decisions.

• Unofficial and unsupported. Not affiliated with Zepp Health or Huami. The API is private and may change or break at any time.

• Your account, your responsibility. Review Zepp's terms before use. The server is read-only and never modifies your account, but automated access may not be something they permit.

• No warranty. See LICENSE.

Security

The threat surface is deliberately small: a local process with no listening port, one outbound HTTPS destination, and a single credential file.

To report a vulnerability, see SECURITY.md. Please don't open a public issue for anything credential-related.

License

MIT © 2026 Dhaval Bhimani