zepp-mcp

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

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

• Tools · Privacy · How it works

• Known gaps · Contributing · Legal and safety

Related MCP server: google-health-mcp-server

Features

• All sports in one call. Swimming, running, walking, hiking and strength work, each with its own metrics — SWOLF and stroke counts for swims, pace and cadence for runs, set counts for the gym.

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

• Per-minute heart rate, with no-reading markers preserved as null rather than dropped.

• Lap and stream decoding for individual workouts.

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

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

Tools

Privacy

This is health data. The design reflects that.

• No health data is written to disk. Every call fetches live.

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

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
  workouts.py       index row -> normalised, sport-aware summary
  codes.py          sport codes, sleep stages, sentinels
  server.py         MCP tool definitions
examples/           runnable analyses with real output
tools/              anonymiser, privacy gate, smoke test
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

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

License

MIT © 2026 Dhaval Bhimani