<div align="center">

# 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**

[![CI](https://github.com/DhavalBhimani44/zepp-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/DhavalBhimani44/zepp-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-server-000000.svg)](https://modelcontextprotocol.io)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
[![Runs locally](https://img.shields.io/badge/runs-100%25%20locally-success.svg)](#architecture)
[![Transport: stdio](https://img.shields.io/badge/transport-stdio-informational.svg)](#architecture)

</div>

---

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.

> [!NOTE]
> ### This runs entirely on your own machine
>
> `zepp-mcp` is a **local stdio server**. Your MCP client launches it as a
> child process on your laptop and talks to it over stdin/stdout — the same
> way it runs any local command.
>
> - **No hosted service.** There is nothing to sign up for and no backend I operate.
> - **No cloud relay.** Your health data never passes through any server but Zepp's own.
> - **No open port.** stdio only — nothing listens on the network.
> - **Your credentials stay in a local `.env`**, never in a client config file.
> - **The only outbound connection** is HTTPS from your machine to Zepp's API,
>   read-only, exactly as the Zepp app does it.
>
> See [Architecture](#architecture) for the full picture.

> [!IMPORTANT]
> **Unofficial.** This project is not affiliated with, endorsed by, or
> supported by Zepp Health or Huami. It talks to a private API that can change
> or break without notice. See [Legal and safety](#legal-and-safety).

## Contents

- [Features](#features) · [Setup for Users](#setup-for-users) · [Developer Setup](#developer-setup)
- [Architecture](#architecture) · [Tools](#tools) · [Privacy](#privacy) · [How it works](#how-it-works)
- [Known gaps](#known-gaps) · [Contributing](#contributing) · [Legal and safety](#legal-and-safety)

## 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](https://docs.astral.sh/uv/) tool runner).

<details open>
<summary><b>Claude Desktop</b></summary>

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

```json
{
  "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.

</details>

<details>
<summary><b>Claude Code</b></summary>

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

```bash
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`.

</details>

<details>
<summary><b>Antigravity CLI</b></summary>

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

```json
{
  "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.

</details>

> [!WARNING]
> Zepp counts failed logins against a **shared 10-attempt lockout**. This
> server never retries a failed login, and you shouldn't either. If
> authentication fails, check your credentials carefully before trying again.

## Developer Setup

If you want to contribute, run tests, or modify the code locally. Requires [uv](https://docs.astral.sh/uv/) and Python 3.11+.

```bash
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:

```bash
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:

```bash
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`.

<details>
<summary><b>Claude Desktop</b></summary>

```json
{
  "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)*

</details>

<details>
<summary><b>Claude Code</b></summary>

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

</details>

<details>
<summary><b>Antigravity CLI</b></summary>

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

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

Credentials are read from your local `.env`.

</details>

## 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.

```mermaid
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**

| Boundary | What crosses it |
| --- | --- |
| Client ↔ server | JSON-RPC over **stdio**. A pipe between two processes on your machine — not a socket, not a port. |
| Server ↔ Zepp | **HTTPS, read-only.** Your credentials and your data go nowhere else. The server never writes to your Zepp account. |
| Server ↔ disk | **The API token, and nothing else.** No workout, sleep or heart-rate data is ever persisted. |

**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

| Tool | Returns |
| --- | --- |
| `zepp_period_summary` | One-call overview of a period: activity, sleep, workouts, readiness, HRV, resting HR, stress, PAI |
| `zepp_daily_summary` | Steps, distance, active calories, activity periods and sleep per day, for any range; optional hourly steps |
| `zepp_sleep` | One night or a range: stages, score, latency, time in bed, efficiency, naps, overnight HRV, respiratory rate, SpO₂ |
| `zepp_health_metrics` | `readiness`, `hrv`, `resting_heart_rate`, `respiratory_rate`, `stress`, `spo2`, `pai`, `body_charge`, `daily_goals`, each with summary and trend |
| `zepp_heart_rate` | Per-minute heart rate for a day, plus statistics |
| `zepp_list_workouts` | All workouts, all sports, paginated, with sport-specific metrics, moving time, derived pace, zones and sets |
| `zepp_workout_stats` | Volume by week/month/year/sport, records, and per-workout progression for 20 metrics |
| `zepp_workout_detail` | Laps, strength sets, km splits, pauses, streams (HR, speed, cadence, stride) and GPS for one workout |
| `zepp_training_thresholds` | Lactate threshold HR/pace and VO2 max over time |
| `zepp_body_composition` | Smart-scale weight, BMI, and (real scale sync only) body fat/water/muscle %, bone mass, visceral fat, BMR |
| `zepp_profile` | Height, weight, age, wear hand, paired devices. Never names, locations or device keys |
| `zepp_describe_schema` | The metric catalogue: units, sources, verification level, known gaps |
| `zepp_raw_request` | Arbitrary GET, for endpoints not modelled yet |
| `zepp_auth_status` | Token expiry and region host |

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](docs/capability-matrix.md).

### Configuration

| Variable | Default | Effect |
| --- | --- | --- |
| `ZEPP_EMAIL`, `ZEPP_PASSWORD` | — | Credentials, from `.env` or the environment |
| `ZEPP_TIMEZONE` | system zone | IANA zone for data that carries none (stress, PAI) |
| `ZEPP_SPORT_CODES` | — | JSON (or a path to a JSON file) naming sport codes you have checked in the Zepp app, e.g. `{"17": "tennis"}` |
| `ZEPP_TOKEN_CACHE` | `~/.zepp-mcp/token.json` | Path, or `off` |
| `ZEPP_RESPONSE_CACHE` | on | In-memory response cache; `off` disables it. Never written to disk |
| `ZEPP_MIN_REQUEST_INTERVAL` | `0.35` | Seconds between outbound requests |
| `ZEPP_DEBUG` | off | Re-enables httpx request logging (which includes your user id) |

## 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:

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

See [CONTRIBUTING.md](CONTRIBUTING.md#adding-fixtures).

## How it works

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

<details>
<summary><b>An empty 200 is not an answer</b></summary>

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.

</details>

<details>
<summary><b>Stream encoding is per field, not global</b></summary>

`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.

</details>

<details>
<summary><b>Sleep has four stages, not two</b></summary>

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.

</details>

<details>
<summary><b>Sentinels are a set, not a value</b></summary>

`-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.

</details>

<details>
<summary><b>Units travel with the number</b></summary>

`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.

</details>

<details>
<summary><b>Times are local</b></summary>

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.

</details>

<details>
<summary><b>Unknown stays unknown</b></summary>

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.

</details>

## Known gaps

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

| Gap | Detail |
| --- | --- |
| Live verification | The 2026-10-31 expansion was verified against the committed corpus, not a live account. [`tools/probe_candidates.py`](tools/probe_candidates.py) settles the open rows; `ZEPP_LIVE=1 uv run pytest tests/test_live.py` checks every tool live. |
| Rolling training load, VO₂ max series | `WatchSportStatistics` is now called with the parameters other clients use, but its response has never been captured, so it is returned undecoded. Per-workout `exercise_load` and `VO2_max` are verified. |
| Strength exercise names | Sets, reps, per-set load and rest are decoded; exercise codes have no verified name table. The load column's unit (kg or lb) is unverified. |
| Lap column names | Swim columns 1, 13 and 14 and strength columns 1/4/5/21/22/28 are confirmed. The rest are inferred or raw. |
| `pool_swim_pace`, HRV SDNN, skin-temperature offset, Body Charge components | Units or meanings unconfirmed; flagged `_unverified`. |
| RTPC | Present on every sport, reads a constant 21 outside running, meaning unconfirmed. |
| Per-second HR, Body Charge stress blob, ECG, blood pressure, women's health | Index or route discovered but not decodable or not populated on any account available here. See the [capability matrix](docs/capability-matrix.md). |
| Multisport, GPS decoding | Built but untested: no triathlon recorded, and GPS workouts are deliberately excluded from the corpus. |
| Sport codes | 141 codes named: 9 confirmed on real data, 7 corroborated, 11 reported once, 112 catalogued from the watch's sport list, and 2 contested (13, 17), which stay `unknown_sport_<code>` with candidates. Catalogued names rest on a rule that holds 3/3 here, not on captures. External tables call code 8 "treadmill"; it is an outdoor walk on this account. See [Sport codes](docs/capability-matrix.md#sport-codes). |
| Zepp Coach | No dedicated endpoint across 22 probed routes ([details](docs/api-findings.md#training-plans--confirmed-2026-09-03)). Plan progress arrives through the workout row as `training_plan`. |
| `zepp_body_composition` fields | Fat/water/muscle/bone/BMR use a schema from a community capture (AlexxIT/SmartScaleConnect), not this project's own data. |

Help with any of these is welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).

## Examples

Three runnable analyses, with real output, live in
[`examples/`](examples/README.md): 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](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](CODE_OF_CONDUCT.md).

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](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](SECURITY.md). Please don't open a
public issue for anything credential-related.

## License

[MIT](LICENSE) © 2026 Dhaval Bhimani