zepp-mcp

Zepp/Amazfit の健康・フィットネスデータ（歩数、睡眠、心拍数、ワークアウト）を MCP クライアント（例: Claude）向けのツールとして公開する MCP サーバーです。Hono で構築され、Cloudflare Workers 上にデプロイされています。

アカウントのメールアドレス/パスワードを使用して Zepp のクラウド API に対して認証し、取得したセッショントークンを Cloudflare KV ネームスペースにキャッシュします。キャッシュされたトークンの期限が切れると自動的に再認証します。

必要条件

• Node.js と npm

• Cloudflare アカウント

• Wrangler（開発依存関係としてインストール）

• Zepp/Amazfit アカウント（メールアドレス + パスワード）

Related MCP server: Garmin Health MCP Server

セットアップ

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

デプロイ前に、同じシークレットを（.dev.vars の代わりに）Cloudflare Worker に設定します:

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"]
    }
  }
}

その他の 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 には KV ネームスペース ID とアカウント認証情報が含まれるため、gitignore されています。チェックイン済みの .example ファイルをテンプレートとして使用してください。