zepp-mcp

MCP-Server, der Zepp/Amazfit-Gesundheits- und Fitnessdaten (Schritte, Schlaf, Herzfrequenz, Workouts) als Tools für MCP-Clients (z. B. Claude) bereitstellt. Erstellt mit Hono und bereitgestellt auf Cloudflare Workers.

Er authentifiziert sich mit der E-Mail und dem Passwort deines Kontos gegenüber der Cloud-API von Zepp, cacht das daraus resultierende Sitzungstoken in einem Cloudflare-KV-Namespace und authentifiziert sich automatisch neu, sobald das gecachte Token abläuft.

Anforderungen

• Node.js und npm

• Ein Cloudflare-Konto

• Wrangler (als dev dependency installiert)

• Ein Zepp/Amazfit-Konto (E-Mail + Passwort)

Related MCP server: Garmin Health MCP Server

Einrichtung

1. Abhängigkeiten installieren:

   npm install

2. Erstelle deine Wrangler-Konfiguration aus dem Beispiel und trage eine KV-Namespace-ID ein:

   cp wrangler.example.jsonc wrangler.jsonc

   Erstelle den KV-Namespace, falls du noch keinen hast, und füge seine ID dann in wrangler.jsonc ein:

   npx wrangler kv namespace create ZEPP_KV

3. Erstelle deine lokale Secrets-Datei aus dem Beispiel:

   cp .dev.vars.example .dev.vars

   Trage deine Zepp-Zugangsdaten in ZEPP_EMAIL und ZEPP_PASSWORD ein.

Entwicklung

Server lokal ausführen:

npm run dev

Der MCP-Endpunkt wird unter /mcp bereitgestellt (Streamable-HTTP-Transport). / gibt eine einfache Status-JSON-Payload zurück.

Type-Check des Projekts durchführen:

npm run typecheck

Bereitstellung

npm run deploy

Setze vor der Bereitstellung dieselben Secrets in deinem Cloudflare Worker (statt in .dev.vars):

npx wrangler secret put ZEPP_EMAIL
npx wrangler secret put ZEPP_PASSWORD

Nach der Bereitstellung gibt Wrangler die öffentliche URL des Workers aus (z. B. https://zepp-mcp.<your-subdomain>.workers.dev). Der MCP-Endpunkt ist diese URL plus /mcp, also z. B. https://zepp-mcp.<your-subdomain>.workers.dev/mcp. Beachte, dass der Endpunkt keine integrierte Authentifizierung besitzt — jeder mit der URL kann ihn aufrufen — behandle ihn also wie ein Geheimnis, falls dir das wichtig ist, oder setze eine eigene Authentifizierung davor.

Verwendung des bereitgestellten MCP-Servers

Richte jeden MCP-Client, der den Streamable-HTTP-Transport unterstützt, auf https://<your-worker-url>/mcp aus.

Claude Code

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

Claude Desktop

Claude Desktop verbindet sich über einen lokalen stdio-Proxy (mcp-remote) mit entfernten HTTP-Servern. Füge Folgendes zu deiner claude_desktop_config.json hinzu:

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

Andere MCP-Clients

Jeder Client mit nativer Streamable-HTTP-Unterstützung (z. B. Cursor, Windsurf) kann direkt auf die /mcp-URL ausgerichtet werden — Details zum Konfigurationsformat findest du in der Dokumentation des jeweiligen Clients. Clients, die nur stdio-Server unterstützen, können das oben gezeigte mcp-remote-Proxy-Muster verwenden.

Tools

Datumsbereich-Tools akzeptieren optionale from_date- und to_date-Parameter im Format YYYY-MM-DD und verwenden standardmäßig die letzten 30 Tage.

Projektstruktur

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

Hinweise

• Sitzungstoken werden 24 Stunden lang in KV gecacht und bei einer 401/403-Antwort automatisch erneuert.

• wrangler.jsonc und .dev.vars sind in der Gitignore, da sie deine KV-Namespace-ID und Zugangsdaten enthalten — verwende die eingecheckten .example-Dateien als Vorlagen.