mi-health-mcp

프로젝트 소개

mi-health-mcp는 샤오미 운동 건강(Mi Fitness)의 가족 데이터(수면, 심박수, 걸음 수)를 MCP 프로토콜을 통해 RikkaHub 등 LLM 클라이언트에 노출합니다. 서비스는 Cloudflare Workers에서 실행되며, 자체 서버 구축이 필요 없고 Cloudflare 무료 할당량 내에서 사용할 수 있습니다. 본 프로젝트는 Misty02600/mi-fitness-python의 인터페이스 리버스 엔지니어링 결과를 Cloudflare Worker + MCP 서비스로 재작성한 것이며, 업스트림에 감사드립니다.

Related MCP server: Health Vault

원클릭 배포

배포 과정에서 Cloudflare KV 바인딩이 필요합니다. 버튼 흐름에서 KV namespace 생성 또는 선택을 요청하면 안내에 따라 완료하고, 바인딩 이름이 MI_HEALTH_KV인지 확인하세요.

버튼이 작동하지 않을 때 수동 배포

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

git clone https://github.com/wusaki0723/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에 채워 your-kv-namespace-id를 교체합니다. 그런 다음 액세스 토큰을 설정하고 배포합니다:

npx wrangler secret put AUTH_TOKEN
npx wrangler deploy

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

배포 후 구성

1. KV namespace 생성:

   npx wrangler kv namespace create MI_HEALTH_KV

2. 명령 출력의 namespace ID를 wrangler.toml의 [[kv_namespaces]]에 채워 your-kv-namespace-id를 교체한 후 다시 배포합니다. 원클릭 배포 시에는 버튼 흐름에서 안내에 따라 KV를 생성하고 바인딩할 수도 있습니다.

3. MCP 인증 토큰을 대화형으로 설정합니다. 토큰은 직접 긴 랜덤 문자열을 생성하세요:

   npx wrangler secret put AUTH_TOKEN

4. 구성 변경 시 다시 배포:

   npx wrangler deploy

KV binding 이름은 반드시 MI_HEALTH_KV로 유지해야 합니다.

클라이언트 구성

RikkaHub에서 「설정 > MCP > 새 연결 > Streamable HTTP」를 열고 다음을 입력합니다:

• URL: https://<your-domain>/mcp

• 사용자 정의 Header: Authorization: Bearer <your-token>

여기서 <your-token>은 배포 시 설정한 AUTH_TOKEN과 완전히 일치해야 합니다.

사용 흐름

1. 클라이언트가 먼저 health_login_start를 호출하여 loginUrl을 가져옵니다.

2. 임의의 QR 코드 도구를 사용하여 loginUrl을 QR 코드로 렌더링합니다.

3. 샤오미 운동 건강 앱으로 QR 코드를 스캔하고 로그인을 확인합니다.

4. 클라이언트가 health_login_poll을 폴링하여 success가 반환될 때까지 대기합니다.

5. 로그인 성공 후 health_latest, health_sleep, health_heart 또는 health_steps를 사용하여 데이터를 조회합니다.

Worker는 QR 코드 이미지를 생성하지 않습니다. 조회 시 가족 목록을 동적으로 읽어 첫 번째 항목을 사용하며, 코드에 사용자 ID를 하드코딩하지 않습니다.

사용 범위

자신의 샤오미 계정에 로그인하고, 권한을 부여받은 가족 데이터를 조회하는 용도로만 사용하세요. 타인의 개인정보를 침해하거나 샤오미 사용자 약관을 위반하는 용도로 사용하지 마세요.

라이선스

본 프로젝트는 GNU General Public License v3.0(GPL-3.0)을 채택하며, 업스트림 Misty02600/mi-fitness-python의 라이선스와 동일합니다.