zepp-mcp

MCP server exposing Zepp/Amazfit health and fitness data (steps, sleep, heart rate, workouts) as tools for MCP clients (e.g. Claude). Built with Hono and deployed on Cloudflare Workers.

It authenticates against Zepp's cloud API using your account email/password, caches the resulting session token in a Cloudflare KV namespace, and re-authenticates automatically when the cached token expires.

Requirements

• Node.js and npm

• A Cloudflare account

• Wrangler (installed as a dev dependency)

• A Zepp/Amazfit account (email + password)

Related MCP server: Oura MCP Server (Python)

Setup

1. Install dependencies:

   npm install

2. Create your Wrangler config from the example and fill in a KV namespace ID:

   cp wrangler.example.jsonc wrangler.jsonc

   Create the KV namespace if you don't have one yet, then paste its ID into wrangler.jsonc:

   npx wrangler kv namespace create ZEPP_KV

3. Create your local secrets file from the example:

   cp .dev.vars.example .dev.vars

   Fill in ZEPP_EMAIL and ZEPP_PASSWORD with your Zepp account credentials.

Development

Run the server locally:

npm run dev

The MCP endpoint is served at /mcp (Streamable HTTP transport). / returns a basic status JSON payload.

Type-check the project:

npm run typecheck

Deployment

npm run deploy

Before deploying, set the same secrets in your Cloudflare Worker (instead of .dev.vars):

npx wrangler secret put ZEPP_EMAIL
npx wrangler secret put ZEPP_PASSWORD

After deploying, Wrangler prints the Worker's public URL (e.g. https://zepp-mcp.<your-subdomain>.workers.dev). The MCP endpoint is that URL plus /mcp, e.g. https://zepp-mcp.<your-subdomain>.workers.dev/mcp. Note that the endpoint has no built-in authentication — anyone with the URL can call it — so treat it as a secret if that matters to you, or add your own auth in front of it.

Using the deployed MCP server

Point any MCP client that supports the Streamable HTTP transport at https://<your-worker-url>/mcp.

Claude Code

claude mcp add --transport http zepp https://zepp-mcp.<your-subdomain>.workers.dev/mcp

Claude Desktop

Claude Desktop connects to remote HTTP servers via a local stdio proxy (mcp-remote). Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "zepp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://zepp-mcp.<your-subdomain>.workers.dev/mcp"]
    }
  }
}

Restart Claude Desktop after editing the config. The zepp_* tools should then show up in the tool picker.

Other MCP clients

Any client with native Streamable HTTP support (e.g. Cursor, Windsurf) can be pointed directly at the /mcp URL — check that client's docs for its config format. Clients that only support stdio servers can use the mcp-remote proxy pattern shown above.

Tools

Date-range tools accept optional from_date / to_date in YYYY-MM-DD format and default to the last 30 days.

Project structure

src/
  index.ts          Hono app, MCP server wiring, /mcp route
  tools/index.ts     MCP tool registrations
  zepp/
    auth.ts          Zepp login flow (token exchange + login)
    client.ts        ZeppClient: session caching + data API calls
    constants.ts      Zepp API URLs, headers, payload templates
    types.ts          Shared Zepp types
  lib/
    crypto.ts        AES-CBC helper used to encrypt the login token request
    kv-cache.ts       Session caching in Cloudflare KV

Notes

• Session tokens are cached in KV for 24 hours and refreshed automatically on a 401/403 response.

• wrangler.jsonc and .dev.vars are gitignored since they hold your KV namespace ID and account credentials — use the checked-in .example files as templates.