Zepp MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Zepp MCP
Zeppの非公式クラウドAPIを使い、自分のワークアウトを読み取る個人用MCPサーバーです。Cloudflare Workers上で動作するTypeScript実装で、認証、履歴の取得、ワークアウト詳細の取得、GPS・心拍・高度・ケイデンス・パワー・ランニングダイナミクス等の時系列デコードに対応します。
Zepp Health、Huami、Amazfitの公式プロジェクトではなく、これらの企業とは無関係です。 非公式APIは予告なく変更・停止される可能性があります。MITライセンスで、動作やデータの正確性は無保証です。
現在のバージョンは0.2.16です。公開クローンでは合成データと通信モックによる77件のテストを実行し、ローカル専用フィクスチャがある環境ではFIT回帰テスト4件も実行します。実アカウントで認証、履歴39件の取得、福岡マラソンの詳細デコード(ケイデンス・歩幅・パワー・接地時間・上下動・上下動比を含む秒単位ストリーム)まで確認済みです。すべてのアカウント・地域・デバイスでの動作を保証するものではありません。
前提
CloudflareアカウントとWorkersへデプロイする権限
Node.js 22.12.0以降、npm、Git(同梱Wranglerの要件)
時計のワークアウトが同期されており、メールアドレス+パスワードでログインできるZeppアカウント
Streamable HTTPと独自Authorizationヘッダーに対応したMCPクライアント
Wranglerはプロジェクトの依存に含まれます。グローバルインストールは不要です。
Related MCP server: Fitbit / Google Health MCP
先に確認すること:Zeppアカウントの落とし穴
アプリへのログインがGoogleなどのソーシャルログインのみの場合、このサーバーへGoogleのパスワードを入力しても使えません。この実装はGoogle OAuthやソーシャルログインに対応していません。ワークアウトのあるアプリ側アカウントに、メールアドレスを紐付けてパスワードを設定する必要があります。 設定の場所・可否はアプリのバージョンやアカウント状態によります。
開発時に、次の事例を実際に経験しました。
メール+パスワード認証は成功するのに、履歴は0件でした。
時計データのあるアプリはGoogle連携ログインを使っていました。
アプリ側に同じメールを追加しようとすると「既に存在する」と拒否されました。
メール+パスワードで入っていたのは、別のデータのないアカウントだと判断しました。
同じメールアドレスに見えても、アプリのソーシャルログインとメール+パスワードのログインが同じアカウントとは限りません。既に使われているメールを紐付けられない場合は、利用可能な別メールをデータのある側へ紐付け、パスワードを設定してください。別の空アカウントを新規作成するだけでは解決しません。
diagnostics.user_idと、取得できた場合のdiagnostics.account_profile.display_nameが照合の補助になります。アプリにIDが表示されない場合もあり、表示名の一致だけで同一アカウントとは断定できません。
1. ソース取得・オフライン確認
git clone https://github.com/kyosuke25/zepp-mcp.git
cd zepp-mcp
npm ci
npx wrangler --version
npm run check
npm test
npm run check:publicnpm testは事前にwrangler deploy --dry-runでバンドルを作りますが、Cloudflareへのデプロイや実Zeppへの接続は行いません。test/fixtures/local/に手元専用の実データが無い場合、FIT回帰テスト4件は自動スキップします。実フィクスチャは配布・Git管理しません。
2. 自分のCloudflareへデプロイ
npx wrangler login
npx wrangler whoami
npx wrangler deploy必要なら、デプロイ前にwrangler.jsoncのWorker名zepp-mcpを自分用に変更してください。アカウントIDや配備先ホスト名の直書きは不要です。デプロイ時に表示される自分のWorker URLを控えます。
https://<worker-name>.<account-subdomain>.workers.devこれはプレースホルダです。このリポジトリに開発者の稼働サーバーURLは含めていません。シークレットをまだ設定していない段階では、/mcpは503で閉じています。
3. シークレット3つを設定
次の正確な名前で、Workerのシークレットを設定します。
名前 | 値 |
| ワークアウトのあるZeppアカウントに紐付けたメール |
| そのアカウントのZepp用パスワード |
| 自分で生成する独立したランダム文字列、32文字以上 |
MCP_AUTH_TOKENはパスワードマネージャーの生成機能等で作り、同じパスワードマネージャーへ保管してください。ZeppやGoogleのパスワードを流用しないでください。後でMCPクライアントにも同じ値を設定します。
方法A:Wrangler CLI
npx wrangler secret put ZEPP_EMAIL
npx wrangler secret put ZEPP_PASSWORD
npx wrangler secret put MCP_AUTH_TOKENそれぞれの対話プロンプトで値を入力します。値をコマンド引数、Git管理ファイル、チャットやIssueへ貼り付けないでください。
方法B:Cloudflareダッシュボード
Workers & Pagesから自分が作ったWorkerを開きます。
Settings → Variables and Secrets → Addを開きます。
種類にSecretを選び、上記の名前と値を入力します。3つともSecretとして登録してください。
画面のDeployで保存・適用します。
CLIとダッシュボードは代替手段です。両方で二重登録する必要はありません。詳しくはCloudflareのシークレット設定を参照してください。
4. 平文の地域設定
wrangler.jsoncのvarsに次の既定値があります。これらはシークレットではありません。
変数 | 既定値 | 意味 |
|
| 最初の認証リクエストのホストを選ぶ初期リージョン |
|
| 最初の認証フォームの国コード |
|
| 認証応答にルーティング情報がない場合のデータ取得先。autoなら認証リージョンを使用 |
トークン応答にregion/country_codeがあれば、それをapp_token交換に使います。履歴・詳細はlogin応答のAPIルート、認識できたlogin地域、トークン応答地域の順に優先し、設定値で上書きしません。国コードからAPIホストを推測しません。
us-west-2→us2、eu-central-1→de2、cn-north-1→cnを正規化します。認識済みの応答ルートがある場合、解釈できない補助メタデータは警告として扱います。有効な応答ルートが無く未知のルーティング情報だけがある場合は停止します。別シャードを自動探索する処理はありません。
自分の設定を変更する場合は、ローカルのwrangler.jsoncも合わせて管理してください。後のデプロイでダッシュボードの平文設定がローカル設定に戻る場合があります。
5. MCPクライアントから接続
Streamable HTTPの接続先は、自分のWorker URLに/mcpを付けたURLです。次のヘッダーを設定します。
Authorization: Bearer <your-MCP_AUTH_TOKEN>環境変数展開に対応したクライアントの設定例です。構文と展開方法はクライアントに合わせてください。
{
"mcpServers": {
"zepp": {
"type": "http",
"url": "${ZEPP_MCP_URL}",
"headers": {
"Authorization": "Bearer ${ZEPP_MCP_AUTH_TOKEN}"
}
}
}
}クライアントの秘密設定でZEPP_MCP_URLに自分の/mcp URL、ZEPP_MCP_AUTH_TOKENにWorkerのMCP_AUTH_TOKENと同じ値を渡します。${...}を展開できないクライアントでは、専用のURL・秘密ヘッダー入力欄を使ってください。Zeppのメール・パスワードをクライアントに渡す必要はありません。
Bearer付きのMCP initializeまたはtools/listへのPOSTがHTTP 200で返ればMCP接続は正常です。単にブラウザで/mcpを開くGETは、この確認の代わりになりません。/healthの200はWorker起動の確認だけで、Zepp認証成功を意味しません。
ツール一覧
ツール | 引数 | 動作 |
| なし | Zepp認証、アカウント・地域診断 |
| 任意の | 履歴1ページ。上流summaryの全フィールドを保持(秘密情報を除く)。次ページは返された |
|
| 履歴にあるIDとsourceで詳細1件を取得し、パワー・ランニングダイナミクスを含めデコードし、取得できた靴情報を |
| なし | 認証→履歴1ページ→先頭1件の詳細→デコード |
|
| 睡眠・心拍・歩数・活動の全応答とJSON・分単位心拍の展開 |
|
| ストレス・SpO2・PAI・負荷等のイベント1ページ |
|
| 運動負荷・VO2max等の統計1ページ |
| 任意の | mobileプロフィール、または指定範囲・キーのユーザープロパティ |
| 任意の | My Gearを1ページ取得。gearId→名前・累計距離の対応と全属性を返す |
|
| 既知ソースIDのデバイス設定メタデータ。ペアリング一覧ではない |
初回はrun_pocを1回だけ実行します。空履歴なら詳細取得を省略します。失敗時は診断を確認し、推測した設定で呼び出しを繰り返さないでください。認証以外のZepp APIはGETのみで、書き込み・自動ページングはありません。履歴・詳細取得のHTTP 401/403に限り、セッションを破棄して再認証し、同じ取得要求を最大1回だけ再試行します。再度の拒否で打ち切り、データ段の拒否は5分間の認証失敗キャッシュに保存しません。ログイン段(auth_tokens/auth_login)の失敗は5分間キャッシュし、自動再試行しません。
この版はBearerヘッダー認証です。OAuthログイン画面、クライアント自動登録、旧独立SSEエンドポイントはありません。任意ヘッダーを設定できないクライアントへの対応は別途必要です。
靴・ギア情報
list_workouts.items[]は上流summaryの全フィールドを元の型で保持します。gearIdもそのまま返します。キーが無い場合は省略します。未選択のnullとキー不在を、靴登録が無い証拠とはみなしません。IDから靴名を推測しません。
get_workout.metadataおよびrun_poc.workout.metadataには、詳細dataのトップレベルにあるgearId、shoe_id、gear、shoe等の靴属性が入ります。元のキー名とスカラー値を保持し、配列・オブジェクトも保持し、内部を含めて認証関連キーを除外します。靴情報が無い場合は靴キーを追加しません。時系列ストリームには追加しません。履歴のIDを詳細へ補完する処理もありません。
0.2.16はGET /users/{userId}/gearsを使います。list_gearの引数なしはstatus=1&limit=100で有効ギア一覧、gear_type: 0はgearType=0&limit=100で靴、gear_type: 1は自転車です。種別指定時はstatusを送りません。既知の型は0/1で、その他の数値の上流対応は保証しません。1ページのみで、upstream.data.nextは保持しますが未確認のカーソル引数は推測しません。
itemsとupstreamに秘密情報を除く全属性を保持し、gear_by_id[gearId]に対応の配列を返します。名前はnicknameを優先し、空ならbrandModel、両方無ければnull。total_distance_mは上流のtotalDistanceM、initial_distance_mはinitialDistanceMです。足し算や単位の推測は行いません。同じgearIdが複数あっても上書きせず全対応を残します。履歴のgearIdでこの辞書を引くと、靴名・累計距離を照合できます。プロトコル仕様にパス・応答形状・ホスト解決を記録しています。
0.2.16の本番検証では靴7件の名前・累計距離を取得し、履歴39件すべてのgearIdを照合できました。実ID・名前・距離の値はリポジトリへ保存していません。
詳細の全フィールド
0.2.12以降、detailの全キーをfield_inventoryへ出力します(認証情報キーを除く)。各項目はvalue_type、decode_status、sample_count、count_basisを持ちます。既知系列は従来どおりstreamsとtimelineへデコードし、それ以外の全フィールドはmetadataに元の値で保持します。未知の文字列・配列はundecoded_streamsにもキー・件数・rawを返すので、未対応の警告だけで捨てません。HYROX・筋トレ・水泳など、未知の種目固有フィールドにも同じ処理を適用します。
未知文字列の件数はセミコロン区切りのレコード枠数(末尾の区切りは除外、内部の空枠は保持)、配列は要素数です。これを秒数や意味的なサンプル数とは断定しません。オブジェクト・数値等はsample_count: null、count_basis: not_applicableです。未知形式の単位・列の意味・時刻は推測せず、原文を残して後の検証へ渡します。原文も健康・個人データとして扱ってください。
履歴の全フィールド
0.2.13以降、履歴summaryの許可リストはありません。新しい項目、種目固有データ、配列・オブジェクト・null・真偽値も保持します。パスワード・トークン・秘密鍵・認証ヘッダー・Cookie・認証セッション等のキーはネスト内も除外し、既知の秘密値はMCP出力時にredactします。training_sessions等の運動情報は保持し、認証用のsession_id等は除外します。実ID、表示名、メール等の個人情報はこの方針では秘密値と同一視しません。自分の認証済みMCPクライアントだけで扱い、公開Issueやリポジトリへ実応答を貼らないでください。
ワークアウト以外のデータ
API対応一覧には、公開資料で確認できたパスと取得可否の確度をまとめています。健康系APIには実アカウントで未検証のものがあります。propertiesとギアは0.2.16で対応しました。取得状況はAPI対応一覧とREPORTで区別しています。Zeppにある全データを参照可能にする方針ですが、全エンドポイントの特定や意味的なデコードが完了したという意味ではありません。
get_daily_dataはYYYY-MM-DDで最大31日(両端含む)。query_typeはdetailが既定、summaryも指定できます。構造化した全応答をupstreamへ、エンコードされた元の応答をencoded_upstreamへ返します。days[].summaryとdays[].decoded.summaryが展開済みのsummary、summary_decodeが形式・結果です。日付キー付きの応答、ラッパー配列、空白・パディング省略・URL-safe Base64も扱います。未知の形式はsummary: nullと警告を返し、原文を保持します。心拍バイトはheart_rate_minutesへ分位置とbpmを出し、0・254・255はnull。活動バイナリは意味未確認として原文保持します。日付・タイムゾーンは推測せず、日をまたぐ睡眠は前日も指定してください。get_health_eventsの期間はUnixミリ秒で最大31日、limitは1〜1000(既定200)、versionはv1が既定です。ストレスはall_day_stress、SpO2はblood_oxygen、PAIはPaiHealthInfo。負荷はversion: v2、event_type: exertion、sub_type: algo_result。全上流応答とJSON文字列の展開を保持します。その他のイベント名も指定できますが、上流対応や取得成功を保証しません。get_sport_statisticsは最大31日(両端含む)、既知のmetricはSPORT_LOAD・VO2_MAXです。limitは1〜1000(既定200)。未知の指標は上流が拒否する可能性があります。get_profile.sectionはprofileが既定で、/huami.health.getUserInfo.jsonへuserid付きでGETします。section: propertiesは数値IDの/users/{userId}/propertiesへpropertyNameとmodeを送ります。引数を追加しない場合は、アプリで確認したpropertyName=huami.watch&mode=RANGEでwatch設定の範囲を取得します。全名前空間の無条件取得ではありません。property_namesを明示した場合の既定はBATCH(指定キーのカンマ区切り照会)。property_mode: RANGEは名前空間・prefixを1つだけ指定します。BATCHのみ複数キーに対応し、上限100キーです。空のプロパティオブジェクトも有効な応答として保持します。get_device_settings.device_sourcesには日次応答のsource等で分かったソースIDを指定します。
0.2.16ではpropertiesのRANGE・BATCHとも本番HTTP 200を確認しました。既定のhuami.watch範囲は空でしたが、huami.midong.user.version範囲は2項目、そこから得た正確なキーのBATCHは1項目を返しました。RANGEのprefixをBATCHの完全一致キーとして使うと空になる場合があります。範囲照会の例:
{"section":"properties","property_names":["huami.midong.user.version"],"property_mode":"RANGE"}いずれも読み取り専用・自動ページングなし。取得先は認証応答で解決したホスト、健康系GETはappplatform: web、mobileプロフィール・properties・ギアはandroid_phoneを用います。401/403は最大1回だけ再認証・再試行し、別API・別地域へ自動で切り替えません。全応答はネストしたJSON/Base64 JSON内も認証情報を除外・redactします。空応答は計測不在の証拠とは限らず、機種・期間・地域・上流仕様の影響を受けます。
ローカル開発
cp .dev.vars.example .dev.vars
chmod 600 .dev.vars.dev.varsをエディタで開き、同じ3シークレットを設定します。.dev.varsはローカル専用で、本番へ自動登録されません。
npm run devローカルMCP URLはhttp://127.0.0.1:8787/mcpです。別ターミナルでnpm run pocを1回実行すると、.dev.varsを読み、ローカルMCP経由で実Zeppへ接続します。結果はGit除外されたoutput/poc-result.jsonに保存します。
実アカウントに接続しないデコード確認はnpm run fixtureで行えます。出力はoutput/fixture-decoded.jsonです。
診断とデータ形式
認証・履歴・詳細・PoCのdiagnosticsには、実装版、user_id、取得できた場合の表示名、設定値、解決地域、履歴ホスト、採用元、上流HTTPステータス等が入ります。login_region_shapeやrouting_warningsで解釈できなかった補助情報も判別できます。retry_countはisolate内の累計再試行数、last_retryは最後の再試行のstage・時刻(UTC)・HTTPステータスです。authentication_sourceは最後の認証処理がlogin(ログイン)、shared_login(同時ログイン待ち)、cache(有効期限内のセッション利用)、failure_cache(ログイン失敗のキャッシュ)だったかを示します。upstream_status_scope: last_observedのとおり、上流HTTPステータスは最後の観測値であり、キャッシュ利用時の上流再検証を意味しません。複数isolate間のセッション調停は行わないため、再認証後も別ログインで無効化される可能性は残ります。認証応答の原文、Location、パスワード、トークンは返しません。健康データの原文は秘密情報を除外・redactしたうえで保持します。実ID・表示名・位置情報は個人情報として扱い、公開Issueへ貼らないでください。
表示名のstatusはavailable / not_returned / withheldで、名前が返らない場合はnullです。追加プロフィールAPIは呼びません。authentication_method: email_passwordはWorkerが使った方式で、アプリのGoogle連携状態を検出した値ではありません。
streamsは各センサーの観測列、timelineは秒オフセットの和集合です。時刻はUTCで、欠測の補間・前値埋めは行いません。GPSは緯度・経度の差分を累積して1e8で割り、高度はcmの絶対値をmへ変換します。心拍は差分を累積します。ケイデンスcadence_spmはgait第4列を優先し、欠けている場合だけ区間歩数×60÷秒で推定してcadence_sourceで区別します。未対応ストリームは警告します。
パワー・ランニングダイナミクスはstreams.power_meter、streams.runPostureと結合後のtimelineに出力します。
出力フィールド | 単位・変換 |
| ランニングパワー、W |
| 接地時間、ms。65535はnull |
| 上下動、mm。65535はnull |
| 上下動比、%。エンコード値÷10、255はnull |
両ストリームの先頭列は秒差分として累積します。パワーは最初の差分が1ならoffset 1、runPostureは0ならoffset 0から始まります。0は同時刻の観測、2は2秒後の観測で、間の値は補完しません。固定の±1秒補正やGPSのtime列による位置合わせは行いません。同時刻の観測は元ストリームに残し、timelineは最後の観測を採用します。sample_alignmentはmode: delta_secondsと入力件数・0差分・ギャップ件数等を返します。
一時的な生ストリーム診断ツールは、FITとの最終突合完了後に撤去済みです。
セキュリティと公開範囲
ソースコードはpublicですが、稼働MCPの個人データへのアクセスはトークン必須です。 URLを知るだけでは利用できません。ネットワーク上のURL自体は公開され、
/healthのみ非機密の起動確認を返します。シークレット未設定・MCPトークンが32文字未満なら
/mcpは503、Bearerが無い・不一致なら401です。このリポジトリに実認証情報、実user_id、実配備先URL、CloudflareアカウントIDは含めていません。公開テストデータは合成値・ダミー認証値のみです。手元専用の実データはGit除外ディレクトリに隔離します。認証の固定キー/IVは公開プロトコルの定数で、個人のシークレットではありません。
.env、.dev.vars、.wrangler/、output/、dist/、test/fixtures/local/はGit対象外です。ファイルを強制追加しないでください。Zeppトークンはisolateのメモリ内だけで最大15分再利用します。認証失敗は同一isolateで5分抑制しますが、別isolateや再配備を跨ぐ共有・抑制はありません。
応答原文や認証ヘッダーをログへ出さない設計です。追加するログ・監視でも秘密情報や健康情報を記録しないでください。
MCPトークンを共有した相手は個人データを取得できます。保管先・クライアントを限定し、漏洩時は変更してください。
ファイル構成・ライセンス
src/zepp-client.tsとsrc/decoder.tsはMCPに依存しないモジュールです。src/index.tsがWorkers/MCPの入口、test/が合成データ・通信モック・workerd結合テスト、REPORT.mdが検証と公開前チェック結果です。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read your workouts, history, and stats; create and schedule new workouts. Writes are additive only.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Access COROS activity, training and health data, and manage training plans and workouts.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA stateless MCP server for Cloudflare Workers that exposes read-only Garmin Connect data (activities, health, sleep, training status, HRV, VO2 max) for a single securely linked personal account.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants such as Claude, ChatGPT and Gemini to read wearable health data — daily activity, sleep stages, heart rate, SpO2, HRV, workouts, weight and nutrition — through a self-hosted, OAuth-protected Cloudflare Worker endpoint. It also lets users log weight, body fat, water, food, exercises, mood and symptoms by voice or chat, while leaving sensor-recorded data read-only.MIT
- AlicenseNot gradedqualityBmaintenanceConnects Garmin Connect to AI assistants, answering questions about training, sleep, HRV and recovery with metrics computed in code rather than guessed from raw JSON. Queries daily readiness, training load, activity FIT analysis and personal records through a self-hosted Cloudflare Worker with OAuth.16 npm8MIT
- AlicenseNot gradedqualityBmaintenanceEnables users to connect ChatGPT or remote MCP clients to their own Garmin cloud health and activity data through a self-hosted, read-only OAuth-protected Cloudflare Worker.238 npmMIT