zepp-mcp

Servidor MCP que expone datos de salud y fitness de Zepp/Amazfit (pasos, sueño, frecuencia cardíaca, entrenamientos) como herramientas para clientes MCP (p. ej. Claude). Construido con Hono y desplegado en Cloudflare Workers.

Se autentica contra la API en la nube de Zepp usando el correo electrónico y la contraseña de tu cuenta, guarda en caché el token de sesión resultante en un espacio de nombres KV de Cloudflare y se vuelve a autenticar automáticamente cuando el token en caché expira.

Requisitos

• Node.js y npm

• Una cuenta de Cloudflare

• Wrangler (instalado como dependencia de desarrollo)

• Una cuenta de Zepp/Amazfit (correo electrónico + contraseña)

Related MCP server: Garmin Health MCP Server

Configuración

1. Instala las dependencias:

   npm install

2. Crea tu configuración de Wrangler a partir del ejemplo y completa un ID de espacio de nombres KV:

   cp wrangler.example.jsonc wrangler.jsonc

   Crea el espacio de nombres KV si aún no tienes uno y luego pega su ID en wrangler.jsonc:

   npx wrangler kv namespace create ZEPP_KV

3. Crea tu archivo local de secretos a partir del ejemplo:

   cp .dev.vars.example .dev.vars

   Completa ZEPP_EMAIL y ZEPP_PASSWORD con las credenciales de tu cuenta de Zepp.

Desarrollo

Ejecuta el servidor localmente:

npm run dev

El endpoint MCP se sirve en /mcp (transporte HTTP Streamable). / devuelve un payload JSON básico de estado.

Verifica los tipos del proyecto:

npm run typecheck

Despliegue

npm run deploy

Antes de desplegar, configura los mismos secretos en tu Worker de Cloudflare (en lugar de .dev.vars):

npx wrangler secret put ZEPP_EMAIL
npx wrangler secret put ZEPP_PASSWORD

Después de desplegar, Wrangler imprime la URL pública del Worker (p. ej. https://zepp-mcp.<your-subdomain>.workers.dev). El endpoint MCP es esa URL más /mcp, p. ej. https://zepp-mcp.<your-subdomain>.workers.dev/mcp. Ten en cuenta que el endpoint no tiene autenticación integrada — cualquiera con la URL puede llamarlo — así que trátalo como un secreto si te importa, o añade tu propia autenticación delante.

Usar el servidor MCP desplegado

Apunta cualquier cliente MCP que admita el transporte HTTP Streamable a 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 se conecta a servidores HTTP remotos a través de un proxy stdio local (mcp-remote). Añade esto a tu claude_desktop_config.json:

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

Reinicia Claude Desktop después de editar la configuración. Las herramientas zepp_* deberían aparecer entonces en el selector de herramientas.

Otros clientes MCP

Cualquier cliente con soporte nativo de HTTP Streamable (p. ej. Cursor, Windsurf) se puede apuntar directamente a la URL /mcp; consulta la documentación de ese cliente para conocer su formato de configuración. Los clientes que solo admiten servidores stdio pueden usar el patrón de proxy mcp-remote mostrado arriba.

Herramientas

Las herramientas de rango de fechas aceptan from_date / to_date opcionales en formato YYYY-MM-DD y por defecto usan los últimos 30 días.

Estructura del proyecto

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

Notas

• Los tokens de sesión se guardan en caché en KV durante 24 horas y se renuevan automáticamente ante una respuesta 401/403.

• wrangler.jsonc y .dev.vars están en gitignore porque contienen tu ID de espacio de nombres KV y las credenciales de la cuenta: usa los archivos .example incluidos en el repositorio como plantillas.