zepp-mcp

这是一个 MCP 服务器，将 Zepp/Amazfit 的健康与健身数据（步数、睡眠、心率、运动）以工具的形式提供给 MCP 客户端（例如 Claude）。它基于 Hono 构建，并部署在 Cloudflare Workers 上。

它使用你的账户邮箱/密码向 Zepp 的云 API 进行身份验证，将生成的会话令牌缓存在 Cloudflare KV 命名空间中，并在缓存的令牌过期时自动重新进行身份验证。

要求

• Node.js 和 npm

• 一个 Cloudflare 账户

• Wrangler（作为开发依赖安装）

• 一个 Zepp/Amazfit 账户（邮箱 + 密码）

Related MCP server: Oura MCP Server (Python)

设置

1. 安装依赖：

   npm install

2. 从示例创建你的 Wrangler 配置，并填入一个 KV 命名空间 ID：

   cp wrangler.example.jsonc wrangler.jsonc

   如果还没有 KV 命名空间，请先创建一个，然后将其 ID 粘贴到 wrangler.jsonc 中：

   npx wrangler kv namespace create ZEPP_KV

3. 从示例创建你的本地机密文件：

   cp .dev.vars.example .dev.vars

   在 ZEPP_EMAIL 和 ZEPP_PASSWORD 中填入你的 Zepp 账户凭据。

开发

在本地运行服务器：

npm run dev

MCP 端点位于 /mcp（Streamable HTTP 传输）。/ 返回一个基本的状态 JSON 负载。

对项目进行类型检查：

npm run typecheck

部署

npm run deploy

部署前，请在 Cloudflare Worker 中设置相同的机密（而不是使用 .dev.vars）：

npx wrangler secret put ZEPP_EMAIL
npx wrangler secret put ZEPP_PASSWORD

部署后，Wrangler 会打印 Worker 的公共 URL（例如 https://zepp-mcp.<your-subdomain>.workers.dev）。MCP 端点就是该 URL 加上 /mcp，例如 https://zepp-mcp.<your-subdomain>.workers.dev/mcp。请注意，该端点没有内置身份验证——任何拥有该 URL 的人都可以调用它——因此如果你在意这一点，请将其视为机密，或在它前面添加你自己的身份验证。

使用已部署的 MCP 服务器

将任何支持 Streamable HTTP 传输的 MCP 客户端指向 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 通过本地 stdio 代理（mcp-remote）连接到远程 HTTP 服务器。将以下内容添加到你的 claude_desktop_config.json：

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

编辑配置后重启 Claude Desktop。zepp_* 工具随后应该会出现在工具选择器中。

其他 MCP 客户端

任何原生支持 Streamable HTTP 的客户端（例如 Cursor、Windsurf）都可以直接指向 /mcp URL——请查阅该客户端的文档以了解其配置格式。仅支持 stdio 服务器的客户端可以使用上面展示的 mcp-remote 代理模式。

工具

日期范围工具接受可选的 from_date / to_date 参数，格式为 YYYY-MM-DD，默认使用最近 30 天。

项目结构

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

说明

• 会话令牌会在 KV 中缓存 24 小时，并在收到 401/403 响应时自动刷新。

• wrangler.jsonc 和 .dev.vars 已被 Git 忽略，因为它们包含你的 KV 命名空间 ID 和账户凭据——请使用已提交到仓库的 .example 文件作为模板。