mi-health-mcp

프로젝트 소개

mi-health-mcp는 현재 로그인된 샤오미 계정 본인 및 인증된 가족 구성원의 수면, 심박수, 걸음 수를 MCP 프로토콜을 통해 Hermes 등 MCP 클라이언트에 제공합니다. 서비스는 Cloudflare Workers에서 실행됩니다. 이 프로젝트는 wusaki0723/mi-health-mcp에서 파생되었으며, GPL-3.0 라이선스를 유지하고 Misty02600/mi-fitness-python 및 shkyyy18/mi_fitness_data_bridge의 인터페이스 구현을 참고했습니다.

Related MCP server: boyuan-health-bridge

배포

Node.js 20 이상과 Cloudflare 계정이 필요합니다.

git clone https://github.com/<your-github-account>/mi-health-mcp.git
cd mi-health-mcp
npm install
npx wrangler login
npx wrangler kv namespace create MI_HEALTH_KV

명령 출력의 namespace ID를 wrangler.toml의 kv_namespaces[0].id에 작성합니다. KV namespace ID는 Cloudflare 리소스 식별자이며 접근 자격 증명이 아닙니다. 공개 저장소는 Workers Builds가 Worker 진입점과 binding을 인식할 수 있도록 wrangler.toml을 반드시 커밋해야 합니다. Fork 후 배포 전에 반드시 자신의 계정에 있는 namespace ID로 교체해야 합니다.

그런 다음 액세스 토큰을 설정하고 배포합니다:

npx wrangler secret put AUTH_TOKEN
npx wrangler deploy

AUTH_TOKEN 값은 직접 생성한 긴 무작위 문자열을 사용하고, 소스 코드, wrangler.toml 또는 Git에 작성하지 마세요.

passToken 로그인

Xiaomi Account 브라우저 Cookie의 userId, passToken, deviceId를 Cloudflare Secret으로 설정하는 것을 권장합니다. deviceId는 일반적으로 wb_로 시작합니다. Worker는 이를 사용하여 sid=miothealth의 단기 건강 API session으로 교환합니다. 원본 passToken은 KV, 로그 또는 MCP 반환에 기록되지 않습니다.

npx wrangler secret put XIAOMI_USER_ID
npx wrangler secret put XIAOMI_PASS_TOKEN
npx wrangler secret put XIAOMI_DEVICE_ID

Cloudflare Dashboard의 Worker 「Settings > Variables and Secrets」에서도 동일한 이름의 Secret을 추가할 수 있습니다. XIAOMI_USER_ID와 XIAOMI_PASS_TOKEN은 반드시 함께 설정해야 합니다. XIAOMI_DEVICE_ID는 선택 사항이며, 설정 시 해당 passToken을 획득한 동일한 브라우저 세션의 deviceId를 사용해야 합니다.

KV binding 이름은 MI_HEALTH_KV로 유지해야 합니다. AUTH_TOKEN, XIAOMI_USER_ID, XIAOMI_PASS_TOKEN은 반드시 Cloudflare Secret을 사용하고, 소스 코드, 구성 파일 또는 Git에 작성하지 마세요.

Hermes 구성

mcp_servers:
  mi_health:
    url: "https://<worker-name>.<account-subdomain>.workers.dev/mcp"
    headers:
      Authorization: "Bearer ${MI_HEALTH_AUTH_TOKEN}"

URL을 직접 배포한 Worker 주소로 교체하세요. MI_HEALTH_AUTH_TOKEN 값은 해당 Worker의 AUTH_TOKEN Secret과 일치해야 합니다. 예시에는 실제 자격 증명이 포함되어 있지 않습니다.

Hermes skill

저장소 내 skills/mi-health/SKILL.md는 "나/본인" 및 "가족" 요청을 올바른 도구로 분기하고, 간결한 결과의 필드 의미를 설명합니다. 저장소가 공개된 후 원본 파일 URL에서 설치할 수 있습니다:

hermes skills install https://raw.githubusercontent.com/<your-github-account>/mi-health-mcp/main/skills/mi-health/SKILL.md
hermes skills list

skill은 자동으로 예약 작업을 생성하지 않습니다. 기존 작업에 연결하려면 먼저 작업 및 최근 실행 기록을 확인한 후 작업 ID로 추가하세요:

hermes cron status
hermes cron list
hermes cron runs <job-id>
hermes cron edit <job-id> --add-skill mi-health

예약 작업은 독립적인 세션에서 실행되므로, prompt에 조회 대상, 일수, 시간대, 전송 위치, 실패 시 처리 방식을 명확히 지정해야 합니다. prompt에 자격 증명을 넣지 마세요. 정기 작업은 provider와 model을 고정하여 전역 기본값 변경 후 동작이 바뀌지 않도록 해야 합니다.

사용 절차

1. XIAOMI_USER_ID와 XIAOMI_PASS_TOKEN을 구성한 후 health_login_refresh를 호출합니다. XIAOMI_DEVICE_ID는 선택적 Secret으로, 필요 시 해당 passToken을 획득한 브라우저 세션을 지정하는 데 사용됩니다. Worker는 miothealth session을 교환하고 캐시합니다. 실패 시 현재 캐시된 세션을 삭제하지 않습니다.

2. health_me로 현재 계정을 확인합니다. 개별 원시 요약을 조회할 때는 health_latest, health_sleep, health_heart 또는 health_steps를 호출하고, 추세 분석이 필요할 때는 health_analyze를 우선적으로 호출하고 사용자의 현재 IANA 시간대를 전달합니다.

3. 가족 구성원을 조회할 때는 먼저 health_relatives를 호출한 후 target: "relative"와 반환된 relative_uid를 전달합니다.

health_login_start와 health_login_poll은 호환성 유지용으로만 남아 있습니다. 이 QR 코드 흐름은 일부 계정에서 Xiaomi에 의해 거부되어 70036을 반환할 수 있으며, 샤오미 운동 건강 App에서도 QR 코드가 지원되지 않는다는 메시지가 표시될 수 있습니다. 이 프로젝트는 이를 검증된 로그인 방식으로 설명하지 않습니다.

건강 조회는 기본적으로 target: "self"이며 본인 데이터 인터페이스를 사용하고 relative_uid를 전송하지 않습니다. 가족 조회는 유효한 relative_uid를 반드시 제공해야 하며, 가족 목록의 첫 번째 항목을 자동으로 선택하지 않습니다.

MCP tools

• health_me: 현재 로그인 상태와 user_id를 반환하며 자격 증명은 반환하지 않습니다.

• health_login_status: 현재 건강 API session 사용 가능 여부와 로그인 방식을 반환하며 자격 증명은 반환하지 않습니다.

• health_login_refresh: 샤오미 계정 Secret을 사용하여 session을 강제로 갱신하며, 실패 시 기존 캐시된 세션을 유지합니다.

• health_relatives: 조회 가능한 가족 구성원의 relative_uid와 메모를 나열합니다.

• health_latest: 최신 수면, 심박수, 걸음 수 요약을 조회합니다.

• health_analyze: 기본적으로 30일을 조회하고, 최근 7개 전체 일수와 이전 기록으로 개인 기준선을 구축합니다. 종료되지 않은 당일 활동을 분리하고, 누락된 날짜, 동기화 지연, 수면 단계 완전성, 심박수 샘플링 품질을 보고하며, 비진단적 robust statistics를 출력합니다.

• health_sleep: 최근 1~30일의 일별 수면 요약을 조회하며, 하루 최대 1건입니다.

• health_heart: 최근 1~30일의 일별 심박수 통계를 조회하며, 전체 샘플 포인트는 반환하지 않습니다.

• health_steps: 최근 1~30일의 일별 걸음 수 요약을 조회하며, 하루 최대 1건입니다.

본인 조회 시 target을 생략하거나 명시적으로 {"target":"self"}를 전달합니다. 가족 조회 시 반드시 다음을 전달해야 합니다:

{
  "target": "relative",
  "relative_uid": "...",
  "days": 7
}

추세 분석 예시:

{
  "target": "self",
  "days": 30,
  "recent_days": 7,
  "timezone": "Europe/Berlin"
}

health_analyze는 건강 API가 이미 반환한 날짜를 다시 계산하지 않습니다. timezone은 현재 자연일을 식별하는 데만 사용되며, 당일 걸음 수와 일별 심박수를 partial로 표시하고 전체 일수 기준선에서 제외합니다. 수면은 기상 날짜 기준으로 완료된 기록으로 간주합니다. 같은 날짜에 중복 요약이 있는 경우 분석기는 유효한 측정, 샘플링 또는 수면 단계 완전성, 기록 시간, 안정 키를 기준으로 결정적으로 하나를 선택합니다. recent_days는 최근 자연일 창을 나타냅니다. 누락되었거나 품질 부족으로 제외된 날짜는 더 이른 기록으로 대체되지 않습니다. 결과는 먼저 data_quality를 반환합니다. missing_dates는 해당 날짜의 기록이 누락되었음을, missing_measurements는 기록은 존재하지만 대상 값이 비어 있거나, 숫자가 아니거나, 음수임을 의미합니다. 둘 다 0이 아닌 알 수 없음으로 처리됩니다. 결과는 또한 최신 데이터 동기화 지연, 수면 단계 완전성 비율, 심박수 샘플링 품질을 보고합니다. 전체 일수 샘플링 수 중앙값의 50% 미만인 날짜는 low_sample_dates에, 유효한 샘플링 수가 없는 날짜는 unknown_sample_dates에 나열되며, 둘 다 심박수 추세에 포함되지 않습니다. 추세 비교는 반올림되지 않은 median, MAD, IQR 및 robust z-score를 사용하며 출력 시에만 반올림합니다. 샘플이 부족하면 insufficient_data를 반환하고 억지로 추세 결론을 내리지 않습니다. 모든 비교는 개인 이력 요약이며 질병 진단이나 약물 조언에 사용할 수 없습니다.

사용 경계

오직 자신의 샤오미 계정에 로그인하고 인증된 가족 구성원의 데이터를 조회하는 용도로만 사용하세요. 타인의 개인정보를 침해하거나 샤오미 사용자 약관을 위반하는 용도로 사용하지 마세요.

본인 데이터는 POST /app/v1/data/get_fitness_data_by_time을 사용합니다. 중국 지역 조회 창은 앞뒤로 각각 18시간 확장된 후 기록의 zone_offset에 따라 날짜에 귀속됩니다. zone_offset이 없으면 UTC+8로 폴백합니다. 본인 steps 기록은 인터페이스의 증분 의미에 따라 일별로 집계됩니다. 본인 heart 샘플 포인트는 일별 통계로 변환됩니다. sleep은 같은 날에 낮잠이 아니고, 지속 시간이 더 길고, 업데이트 시간이 더 새로운 기록을 우선 유지합니다. 가족 데이터는 /app/v1/relatives/*의 daily_report를 사용하며, 같은 날 기록을 중복 합산하지 않습니다.

MCP 반환은 필드 화이트리스트를 사용하며 AUTH_TOKEN, passToken, cUserId, serviceToken, ssecurity 또는 Cookie를 반환하지 않습니다. .dev.vars, .env, wrangler.toml 또는 .wrangler/를 커밋하지 마세요.

라이선스

이 프로젝트는 GNU General Public License v3.0(GPL-3.0)을 사용하며, 상위 프로젝트 Misty02600/mi-fitness-python의 라이선스와 일치합니다.