Zepp Cloud MCP

Unofficial. This project is not affiliated with, endorsed by, or supported by Zepp Health, Huami or Amazfit. It uses Zepp's private, undocumented cloud API, which can change or break at any time.

Why

Amazfit watches send a lot of data to Zepp Cloud: sleep stages, HRV, readiness, training load, strength sets, GPS routes. The Zepp app is the only place you can see it. Zepp Cloud MCP reads that data with your own app token, turns it into clean typed JSON, and serves it over the Model Context Protocol. You can then ask an assistant questions like "how did my sleep change after I started lifting in the evening?". The self-hosted Node server can also sync the data into a local SQLite database and show it on a private web dashboard.

Related MCP server: mcp-garmin

Features

• 19 read-only MCP tools for daily summary, sleep, heart rate, recovery (HRV, readiness, stress, SpO2), training status (load, VO2max), workouts, per-workout samples, GPS routes, strength sets, weight, blood pressure, Hybrid Charge, emotion/stress events and sync status.

• Long ranges. Date ranges up to 366 days. Ranges longer than Zepp's 31-day window are split into several upstream requests and merged.

• Strength training. Set-by-set exercises, reps, weight and volume, mapped to primary and secondary muscle groups.

• Two deployment targets:

  • Node server (VPS, home server) with an OAuth 2.1 authorization server, a dashboard, and a daily SQLite sync.

  • Cloudflare Worker: stateless, with a static bearer token and no database.

• OAuth 2.1 for remote connectors. Single owner, dynamic client registration, PKCE (S256), refresh tokens and token revocation. Works with ChatGPT and Claude custom connectors.

• Dashboard. Overview, Sleep, Recovery, Activity, Hybrid Charge, Workouts (with muscle map and OpenStreetMap route map), Training, Exercises, Weight and Sync pages, plus GPX/TCX export. The layout is responsive and works on phones.

• Safe by design.

  • No arbitrary upstream URLs.

  • The region host is validated against Zepp/Huami origins before any credentials are attached.

  • Raw payloads are sanitized.

  • Secrets come only from the environment.

Screenshots

Quick start (Node server)

Requirements:

• Node.js 22.5 or later. The sync store uses the built-in node:sqlite.

• A Zepp app token, your Zepp user ID and your regional API host. See docs/ZEPP_AUTH.md.

git clone https://github.com/aryarfani/zepp-cloud-mcp.git
cd zepp-cloud-mcp
npm ci
cp .dev.vars.example .env   # then edit .env (see the table below)
npm start                   # listens on http://127.0.0.1:8788

Check that it is running:

curl http://127.0.0.1:8788/health

To fill the local database right away instead of waiting for the daily sync, run:

npm run sync -- --days 30

Configuration

The Node server reads .env (via dotenv) and the process environment.

Deploy

Option A: Node server behind nginx (systemd)

/etc/systemd/system/zepp-mcp.service:

[Unit]
Description=Zepp Cloud MCP
After=network-online.target

[Service]
WorkingDirectory=/opt/zepp-cloud-mcp
ExecStart=/usr/bin/npx tsx src/server-node.ts
Restart=on-failure
User=zepp
# Secrets live in /opt/zepp-cloud-mcp/.env (chmod 600)

[Install]
WantedBy=multi-user.target

nginx (TLS through certbot or similar):

server {
  server_name zepp.example.com;
  location / {
    proxy_pass http://127.0.0.1:8788;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;          # streamable HTTP
    proxy_read_timeout 300s;
  }
  listen 443 ssl;
}

sudo systemctl enable --now zepp-mcp

You get these endpoints:

• /mcp: MCP over Streamable HTTP.

• /dashboard: the web dashboard.

• /authorize, /token, /register, /revoke: OAuth.

• /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource: OAuth discovery metadata.

• /health: health check.

Option B: Cloudflare Workers (stateless)

The Worker (src/index.ts) serves /mcp with the static MCP_SECRET bearer only. It has no OAuth, no dashboard, no sync, and no sync_status tool, so it exposes 18 tools.

npm ci
npx wrangler login
# edit wrangler.jsonc vars: ZEPP_USER_ID, ZEPP_REGION_HOST, USER_TIMEZONE
npx wrangler secret put ZEPP_APP_TOKEN
npx wrangler secret put MCP_SECRET
npm run deploy

See docs/DEPLOY.md for details.

Connecting a client

{
  "mcpServers": {
    "zepp": {
      "url": "https://zepp.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_SECRET" }
    }
  }
}

More detail is in docs/MCP_SETUP.md.

MCP tools

All tools are read-only. Each call fetches live from Zepp Cloud; only sync_status reads the local database. Dates are local YYYY-MM-DD in USER_TIMEZONE.

Range tools accept up to 366 days.

Architecture

flowchart LR
  W[Amazfit watch] --> A[Zepp app] --> Z[(Zepp Cloud API)]
  subgraph Node server
    C[Zepp client<br/>+ normalizers] --> M[MCP server /mcp]
    O[OAuth 2.1<br/>/authorize /token /register] --> M
    S[Daily sync] --> DB[(SQLite<br/>node:sqlite)]
    DB --> D[Dashboard /dashboard]
    C --> S
  end
  Z --> C
  M --> L[ChatGPT / Claude / Cursor]
  subgraph Cloudflare Worker
    CW[Zepp client] --> MW[MCP /mcp<br/>static bearer]
  end
  Z --> CW

The code layout:

Data and privacy

• You host it. Health data goes only between Zepp Cloud, your server and the MCP clients you connect. There is no telemetry.

• The Node server stores synced data in data/zepp.db and OAuth state in data/oauth-store.json. Both are git-ignored. Protect them like any other health record.

• The Worker keeps no durable storage. It only caches validated responses briefly.

• The server never stores your Zepp email or password. It uses an app token that you supply and rotate.

• Route maps load tiles from OpenStreetMap, so your browser requests map tiles for the areas you ran in.

Development

npm ci
npm run typecheck   # tsc --noEmit
npm test            # Workers (workerd) suite, then the Node suite
npm run test:node   # Node suite only
npm run dev         # wrangler dev (Worker)
npm start           # Node server

Other scripts:

• npm run test:live runs a read-only probe against your real account.

• npm run exercises:rederive rebuilds exercise labels in the local database.

Contributions are welcome. Please read CONTRIBUTING.md.

Roadmap

• Multi-user support (more than one Zepp account per server)

• Docker image and compose file

• Dashboard view for blood pressure and emotion events

• Assistant-side prompts and resources (weekly report templates)

• Automatic detection of the region host

Acknowledgements

• ZeppBridge was the original inspiration. Its sport catalog data is used under the MIT License.

• Gadgetbridge is the source of the strength exercise and muscle catalogs (AGPL-3.0-or-later).

• OpenStreetMap contributors provide the route map tiles.

• The Model Context Protocol SDK.

See THIRD_PARTY_NOTICES.md.

License

AGPL-3.0-or-later © Ary Arfani and contributors. If you run a modified version as a network service, you must offer its source to the users of that service.