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

배포 전에 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는 KV 네임스페이스 ID와 계정 자격 증명을 보관하므로 gitignore에 포함됩니다. 커밋된 .example 파일을 템플릿으로 사용하세요.