Zepp Cloud MCP

Read-only MCP server for Amazfit / Zepp fitness data, designed for Cloudflare Workers.

It talks directly to the unofficial Zepp/Huami cloud API, normalizes the useful health and workout streams, and exposes a bounded MCP interface for ChatGPT or other MCP clients.

This project is unofficial and is not affiliated with Zepp Health, Huami, or Amazfit. The upstream API is private/undocumented and can change without notice.

Architecture

Amazfit watch
    -> Zepp mobile app
    -> Zepp Cloud
    -> Cloudflare Worker
    -> Streamable HTTP MCP (/mcp)
    -> ChatGPT / MCP client

There is no desktop ZeppBridge process and no persistent health-data database in Cloudflare.

Related MCP server: garmin-mcp

MCP tools

All tools are read-only. get_raw_metric does not accept arbitrary URLs, paths, headers, or query strings.

Security model

• ZEPP_APP_TOKEN is a Cloudflare Worker secret.

• MCP_SECRET is a separate Worker secret used as Authorization: Bearer ... on /mcp.

• Zepp email/password are never stored.

• Zepp tokens are never returned in MCP responses.

• Upstream redirects are followed only when they stay on the configured HTTPS Zepp origin.

• Public errors do not echo arbitrary upstream response text.

• No D1, KV, R2, or permanent copy of fitness history is required.

• Cloudflare Cache API is used only for short-lived response caching.

• Date ranges are limited to 31 inclusive days per call.

• Workout samples/routes are bounded and disclose when downsampling occurred.

Quick start

Requirements: Node.js 22+, npm, and a Cloudflare account.

npm install

Edit the non-secret values in wrangler.jsonc:

{
  "ZEPP_USER_ID": "YOUR_ZEPP_USER_ID",
  "ZEPP_REGION_HOST": "https://api-mifit-us3.zepp.com",
  "USER_TIMEZONE": "Asia/Jakarta"
}

The user ID committed in this repository is deliberately a dummy value.

Set secrets:

npx wrangler secret put ZEPP_APP_TOKEN
npx wrangler secret put MCP_SECRET

Verify locally:

npm run types
npm run typecheck
npm test

Optional live Zepp credential probe (read-only):

MCP_SECRET=local-probe-secret \
ZEPP_APP_TOKEN='YOUR_TOKEN' \
ZEPP_USER_ID='YOUR_USER_ID' \
ZEPP_REGION_HOST='https://api-mifit-us3.zepp.com' \
USER_TIMEZONE='Asia/Jakarta' \
npm run test:live

The live probe checks recent heart rate, band data, and the HRV event API, and prints only authentication/status and response shape information rather than your measurements.

Deploy:

npx wrangler deploy

Your MCP endpoint will be:

https://<worker>.workers.dev/mcp

Every MCP request must include:

Authorization: Bearer <MCP_SECRET>

See docs/DEPLOY.md and docs/MCP_SETUP.md for the full setup.

Zepp token rotation

The app token is intentionally treated as an externally acquired credential. If zepp_status starts returning auth_expired, rotate only the Worker secret:

npx wrangler secret put ZEPP_APP_TOKEN

No code change or Zepp password is required.

Supported / deliberately unsupported data

The server includes the reviewed ZeppBridge mappings for daily activity, sleep, HR, HRV/RMSSD, readiness, stress, SpO2, respiratory rate, PAI, training load, VO2max, lactate threshold and workout details where Zepp supplies them.

Weight and blood-pressure retrieval are deliberately not exposed. Missing data remains missing; it is not converted to zero or fabricated. Empty Zepp event responses are not automatically treated as proof that a capability is unsupported.

Workout detail follows the verified Zepp semantics used by ZeppBridge, including power, ground-contact time, vertical oscillation, vertical ratio, GPS/elevation and Zepp's equivalent pace. Equivalent pace is kept separate from ordinary pace rather than derived from speed.

Documentation

• Cloudflare deployment

• MCP client setup

• Zepp authentication

• Unofficial API behavior and normalization notes

Development

npm run typecheck
npm test
npx wrangler deploy --dry-run --outdir dist

GitHub Actions runs install -> Worker type generation -> strict TypeScript -> tests -> Wrangler dry run on main and pull requests.

Credits

The Zepp endpoint mappings and a number of normalization/decoder semantics are informed by ZeppBridge. This project builds a Worker-native, direct-cloud MCP surface rather than using ZeppBridge's desktop SQLite MCP architecture.