Renpho Health MCP — 스마트 체중계 데이터를 Claude 트레이닝 코치에게

Cloudflare Workers에 배포되는 원격 MCP 서버로, Renpho 스마트 체중계의 체성분 데이터(체중, 체지방, 제지방량, 근육량, 수분, 골격근, 내장지방, 기초대사량, 대사 나이 등)를 Renpho Health 클라우드 API를 통해 Claude에 노출합니다. 커스텀 커넥터로 한 번 추가하면 Claude 웹, 데스크톱, 모바일에서 모두 작동합니다. Strava 및 Google Health 커넥터와 함께 사용하면 코치가 훈련 부하, 회복 상태 그리고 체성분을 모두 확인할 수 있습니다.

데이터 소스: Renpho Health 앱(파란색 아이콘)의 백엔드인 cloud.renpho.com입니다. 레거시 Renpho 앱(renpho.qnclouds.com)의 계정은 지원되지 않으므로, 앱에서 먼저 마이그레이션하세요.

StartupBros-com/renpho-mcp-server(로컬 stdio 서버)의 역공학 프로토콜과 forkerer/RenphoGarminSync-CLI를 기반으로, google-health-mcp 스타일의 다중 사용자 원격 Worker로 재구성했습니다.

도구

문제 해결: 측정값이 누락되었거나, 오래되었거나, 잘못된 사람에게 귀속된 것 같으면 먼저 run_diagnostics를 실행하세요. 하위 증상으로 추론하게 두지 않고 데이터가 실제로 어디에 있는지(어떤 테이블/프로필, 바인딩 여부)를 보고합니다.

Related MCP server: Oura Ring MCP Server

필드 매핑 (Renpho Health API)

RenphoHealth/scale/queryAllMeasureDataList의 원시 레코드에는 ~57개의 키가 있습니다. 도구는 지표를 단위 접미사가 붙은 snake_case로 이름을 바꾸고, enum 코드를 디코딩하며, 봉투 노이즈를 제거하고, 인식되지 않는 항목은 extra 아래에 유지하여 Renpho가 필드를 추가해도 데이터가 손실되지 않도록 합니다 (src/measurements.ts 참조).

0으로 보고된 지표는 "측정되지 않음"을 의미하며 생략됩니다. Renpho ID는 JavaScript의 안전 범위를 초과하는 64비트 정수이므로, 클라이언트는 파싱 전에 이를 문자열로 다시 인용합니다 (src/json.ts).

데이터를 가져오는 방법

• 로그인 (renpho-aggregation/user/login)은 expAt이 포함된 bearer 토큰을 반환하며, 만료 직전까지 KV에 캐시(봉인)되고 다시 로그인하여 갱신됩니다 — Renpho에는 refresh 토큰이 없습니다.

• device/count 는 계정의 데이터 테이블과 레코드 수를 나열하며 모든 도구 호출 시 새로 가져옵니다. 이것이 신선도 신호입니다.

• 테이블당 두 개의 저장소. 각 measurements_info_N 테이블은 두 엔드포인트에서 읽습니다: scale/queryAllMeasureDataList(레거시 저장소, device/count가 집계하는 행)와 scale/queryBodyCompositionMeasureData(8전극/다중 주파수 체중계 — 예: MorphoScan — 에서 사용하는 최신 저장소, device/count는 집계하지 않음). 행은 id로 병합되며, 둘 다 존재할 때는 더 풍부한 필드 집합을 가지므로 체성분 복사본을 유지합니다. source.endpoint는 판독값이 어느 저장소에서 왔는지 알려줍니다.

• 측정 페이지(각 200개 레코드)는 KV에 캐시됩니다. 레거시 페이지는 테이블, 프로필 세트 및 레코드 수로 키가 지정되므로, 새로운 측정이 있으면 키가 변경되어 자동으로 무효화됩니다. 체성분 페이지에는 카운트가 없으며 대신 15분 동안 캐시됩니다. 페이지네이터는 각 저장소의 정렬 방식을 감지하여 요청된 창에 필요한 만큼만 이동합니다(호출당 저장소별 최대 30페이지 / 6,000개 레코드).

• 선택: 로그인한 계정(bUserId)에 바인딩된 판독값이 기본적으로 반환됩니다. 아직 바인딩되지 않은 경우(와이파이 체중계가 앱이 판독값을 바인딩하기 전에 업로드함) 계정의 첫 번째 체중계 사용자 프로필로 대체되며 그렇게 명시합니다. 가족 구성원의 경우 scale_user_id를 전달하세요.

캐싱 및 암호화

RENPHO_CACHE KV 네임스페이스에 기록되는 모든 것 — 세션 토큰 및 측정 페이지 — 은 SESSION_ENCRYPTION_KEY 시크릿에서 파생된 키로 AES-256-GCM 봉인되며, 사용자별로 키가 지정됩니다(이메일의 SHA-256). 시크릿이 설정되지 않으면 캐싱이 단순히 비활성화됩니다. 캐시 실패는 요청을 중단시키지 않습니다.

Renpho 전송 자체는 앱에 포함된 정적 키를 사용하는 AES-128-ECB입니다. WebCrypto에는 ECB 모드가 없으므로 Worker는 순수 JS aes-js(src/crypto.ts, 테스트에서 OpenSSL과 바이트 단위로 검증됨)를 사용합니다.

로그인 작동 방식 (한 번 읽어보세요)

Renpho에는 OAuth가 없습니다. Worker는 Claude에 대한 OAuth 서버(workers-oauth-provider)이며, /authorize 페이지는 Renpho 로그인 양식입니다. 이메일/비밀번호는 Renpho에서 한 번 확인된 후 grant의 암호화된 props 내부에 저장됩니다 — 암호화 키는 Claude가 보유한 토큰에서 파생되므로 KV 내용만으로는 복호화할 수 없습니다. 자격 증명이 필요한 이유는 Renpho 세션 토큰이 몇 시간 후에 만료되고 새 토큰을 얻는 유일한 방법이 다시 로그인하는 것이기 때문입니다.

• Claude에서 커넥터 연결을 해제하면 grant가 삭제됩니다(저장된 자격 증명도 함께). delete_my_data는 캐시를 지웁니다.

• ALLOWED_EMAILS(쉼표로 구분)를 설정하면 다른 사람의 Renpho 계정이 귀하의 배포에 연결하는 것을 차단합니다. 비워 두면 모든 Renpho 사용자가 사용할 수 있습니다(각 사용자는 자신의 데이터만 볼 수 있습니다).

배포

옵션 A — GitHub Actions (로컬 wrangler 불필요)

.github/workflows/deploy.yml의 워크플로우는 master에 푸시할 때마다(및 요청 시) 배포합니다. 앱 시크릿은 GitHub가 아닌 Cloudflare에 있습니다 — GitHub에는 Cloudflare API 토큰 + 계정 ID만 보관됩니다.

1. Cloudflare 대시보드에서 두 개의 KV 네임스페이스를 생성합니다 (Storage & Databases → KV): OAUTH_KV 및 RENPHO_CACHE. 해당 id를 wrangler.jsonc에 붙여넣고 커밋합니다.

2. Cloudflare API 토큰을 생성합니다 (My Profile → API Tokens → "Edit Cloudflare Workers" 템플릿) 및 계정 ID를 기록합니다.

3. GitHub 저장소 시크릿 CLOUDFLARE_API_TOKEN 및 CLOUDFLARE_ACCOUNT_ID를 추가합니다.

4. master에 푸시합니다. Actions 로그에 Worker URL이 출력됩니다 (https://renpho-health-mcp.<subdomain>.workers.dev).

5. Cloudflare에서 앱 시크릿을 설정합니다 (Workers & Pages → renpho-health-mcp → Settings → Variables and Secrets, 유형 Secret): SESSION_ENCRYPTION_KEY = 임의의 긴 문자열. 선택적으로 ALLOWED_EMAILS 변수를 귀하의 Renpho 이메일로 설정합니다.

옵션 B — 로컬 wrangler

npm install
npx wrangler kv namespace create OAUTH_KV        # paste the id into wrangler.jsonc
npx wrangler kv namespace create RENPHO_CACHE    # paste the id into wrangler.jsonc
npx wrangler secret put SESSION_ENCRYPTION_KEY   # any long random string
npx wrangler deploy

Claude에서 연결

1. Settings → Connectors → Add custom connector.

2. URL: https://renpho-health-mcp.<subdomain>.workers.dev/mcp

3. Connect 클릭 → Renpho Health 이메일/비밀번호로 로그인 → 완료.

그런 다음 코치에게 물어보세요: "최신 체중계 측정값을 가져와서 지난달 체중 감량이 지방에서 왔는지 근육량에서 왔는지 알려줘."

커넥터 아이콘

Worker는 MCP serverInfo.icons(및 websiteUrl)에서 PUBLIC_URL/icon.png를 광고하므로 서버 브랜딩을 렌더링하는 클라이언트는 커넥터 목록에 이를 표시합니다. 기본값은 생성된 체중계 아이콘입니다(npm run icon). 공식 Renpho Health 앱 아이콘을 대신 사용하려면 App Store / Play Store 목록에서 PNG를 저장하고 포함하세요:

npm run icon:embed -- ~/Downloads/renpho-health-icon.png   # writes src/icon.ts + assets/icon.png
npm run deploy

(공식 마크는 Renpho의 상표입니다 — 개인 배포에는 괜찮지만 재배포에는 적합하지 않으므로 이 저장소에 포함되지 않았습니다.)

로컬 개발

cp .dev.vars.example .dev.vars   # set SESSION_ENCRYPTION_KEY
npm run dev                      # http://localhost:8787
npm test                         # vitest
npm run typecheck                # worker + tests
npm run icon                     # regenerate assets/icon.png + src/icon.ts

MCP Inspector로 흐름을 테스트하세요:

npx @modelcontextprotocol/inspector@latest
# Transport: Streamable HTTP → http://localhost:8787/mcp → Connect

작동 방식

Claude (web/desktop/mobile)
  └─ custom connector → /mcp
       └─ workers-oauth-provider  (this Worker IS Claude's OAuth server)
            └─ AuthHandler        (Renpho sign-in page; validates against Renpho)
                 └─ RenphoMCP (Durable Object) → RenphoClient → cloud.renpho.com

• src/index.ts — OAuthProvider + McpAgent Durable Object를 연결합니다.

• src/auth-handler.ts — 로그인 페이지(/authorize), 랜딩 페이지, 아이콘.

• src/renpho-api.ts — Renpho 클라이언트: 세션 캐시, 재시도/재로그인이 포함된 암호화 전송, 순서 무관 페이지네이터, 사용자 선택.

• src/measurements.ts — 원시 레코드 → 간결한 코칭 형태, 열거형, 분류, 프로필.

• src/stats.ts — 회귀, 가장자리 창 요약, 이동 평균, 목표 예측.

• src/tools.ts — 위의 코칭 도구.

• src/crypto.ts, src/json.ts, src/dates.ts — AES 헬퍼, big-int 안전 JSON, 시간대 정확 날짜. 모두 순수 함수이며 단위 테스트됨.

참고 사항 및 제한

• Wi-Fi 체중계 바인딩 지연. 일부 Wi-Fi 체중계는 앱이 계정에 바인딩하기 전에 판독값을 업로드합니다. 그때까지는 scale_user_id는 있지만 bound_user_id는 없습니다. 도구는 첫 번째 프로필로 대체하고 그렇게 명시합니다(selection: "fallback_scale_user"). run_diagnostics는 숨겨진 판독값을 나열합니다.

• 생체 임피던스는 노이즈가 많습니다. 수분, 시간대, 최근 운동이 체지방/수분 판독값을 몇 포인트씩 움직입니다. 하루 중 같은 시간에 측정하고 단일 판독값이 아닌 평균/추세를 읽으세요 — 추세 도구가 정확히 이 이유로 7일 가장자리 창과 이동 평균을 사용합니다.

• 단위. 질량은 kg, 체성분 지표는 %로 Renpho 앱과 일치합니다. muscle은 근육 질량(kg)으로, sinew는 골격근 %로 보고됩니다. 기기 펌웨어가 다르게 보고하는 경우 원시 값은 변경되지 않으며 레이블만 다릅니다.

• MorphoScan / 8전극 체중계. 이들의 판독값은 체성분 저장소(위 참조)에 있으며 분절 지방/근육, SMI 등 추가 기기별 필드를 포함합니다 — 도구는 이를 extra 아래에 전달합니다(include_details 요청 또는 run_diagnostics의 unrecognised_fields_seen 참조). 해당 필드 이름으로 이슈를 열어 제대로 매핑할 수 있게 해주세요.

• 전용 도구가 있는 것은 scale 카테고리뿐입니다. 둘레/줄자, 트레드밀, 로프 및 바디 스캔(MorphoScan) 데이터는 get_scale_users → device_categories에 표시되며 query_endpoint로 탐색할 수 있습니다.

• 속도 제한. Renpho는 과부하 시 코드 429를 반환합니다. 클라이언트는 백오프 후 재시도하며 캐시된 페이지가 계속 제공됩니다.

• 비밀번호 변경은 저장된 자격 증명을 깨뜨립니다 — 커넥터를 연결 해제하고 다시 연결하세요.

• 비공식 API. 모바일 앱의 비공개 API를 사용합니다. Renpho는 언제든지 변경할 수 있습니다. Renpho와 제휴하거나 보증하지 않습니다.

개인정보 보호

• 자격 증명은 Renpho 인증에만 사용되며 OAuth grant 내부에 암호화되어 저장됩니다. 아무것도 기록되지 않습니다.

• 건강 데이터는 귀하의 KV 네임스페이스에만 봉인되어 캐시되며 delete_my_data로 삭제할 수 있습니다. 제3자에게 전송되지 않습니다.

크레딧

• API 리버스 엔지니어링: forkerer/RenphoGarminSync-CLI 및 StartupBros-com/renpho-mcp-server (MIT).

라이선스

MIT