google-health-mcp

Google Health API용 MCP 서버로, 로컬 SQLite 캐시와 추세 분석을 제공합니다.

Claude Code 및 기타 MCP 클라이언트를 위해 설계되었습니다. 데이터는 사용자 머신의 데이터베이스에 동기화되므로 쿼리가 빠르고, 오프라인에서도 작동하며, API 할당량을 소모하지 않습니다.

기능

• 로컬 SQLite 캐시 - 한 번 동기화하고 즉시 쿼리

• 증분 동기화 - 실행할 때마다 마지막으로 중단된 지점부터 새 항목만 가져옵니다.

• 오프라인 모드 - 자격 증명이나 네트워크 없이 캐시 제공

• 추세 - 주간, 월간, 분기별 집계 및 두 기간 비교

• ECG - 판독값 전체(파형 포함)를 저장하며, 요청 시에만 반환

• doctor - 할당량을 소모하지 않고 오프라인 및 읽기 전용으로 설정을 진단

Related MCP server: google-health-mcp-server

데이터 유형

요구 사항

• Python 3.13+ (CI에서 3.13 및 3.14로 테스트됨)

• 건강 데이터가 있는 Google 계정과 인증에 사용할 Google Cloud 프로젝트가 필요합니다. 결제 계정은 필요 없습니다 - 콘솔에서 설정 내내 무료 평가판을 제안하지만 모두 거부할 수 있습니다.

설정

1. 설치

pip install google-health-mcp

또는 설치하지 않고 실행할 수 있습니다. 이 경우 아래에서 실행하는 모든 google-health-mcp ... 명령은 uvx google-health-mcp ...가 됩니다.

uvx google-health-mcp --version

2. Google Cloud 프로젝트 만들기

각 사용자는 자신의 OAuth 클라이언트를 등록합니다. 콘솔에서 7단계로 진행되며, 페이지 이름은 2026년 8월 기준 Google의 이름입니다.

Google의 설정 페이지는 다른 곳으로 안내할 수 있으니 아래 단계를 따르세요. Google의 빠른 시작은 https://www.google.com을 리디렉션 URI로 사용하는 웹 클라이언트를 생성하는데, 이는 사용자 머신에서 실행되는 프로그램보다 OAuth Playground에 적합합니다. 이 서버는 해당 파일을 거부하며 그 이유를 알려줍니다. 해당 페이지는 아래 페이지 중 하나의 이름이 변경되었는지 확인하는 용도로만 사용하세요.

1. 프로젝트. console.cloud.google.com/projectcreate에서 프로젝트를 만들고 선택합니다.

2. API. API 사용 설정 페이지에서 Google Health API를 사용 설정합니다.

3. 시작하기. Google Auth Platform을 열고 시작하기를 완료합니다 - 앱 이름, 지원 이메일, 외부 사용자 유형, 연락처 이메일. 이 작업을 완료하기 전까지 새 프로젝트에는 Audience, Data Access 또는 Clients 페이지가 없습니다.

4. 사용자. 테스트 사용자에서 본인의 Google 계정을 추가합니다. 이 단계를 건너뛰면 403: access_denied 오류로 로그인에 실패합니다.

5. 데이터 액세스. 범위 추가 또는 삭제를 클릭하고 "Google Health API"를 검색한 후 아래 OAuth 범위에 나열된 읽기 전용 범위를 선택합니다.

6. 클라이언트. 데스크톱 앱 유형의 OAuth 클라이언트를 만들고 해당 JSON을 다운로드합니다. 데스크톱 클라이언트는 루프백 리디렉션을 자동으로 허용하므로 등록할 항목이 없습니다. 웹 클라이언트는 그렇지 않으며 동의 단계에서 실패합니다.

7. 게시. Audience 페이지로 돌아가 앱 게시를 클릭합니다.

가장 골치 아픈 단계는 7단계이므로, 추측하지 말고 확인해 볼 가치가 있습니다. 앱의 게시 상태가 테스트 중인 동안 Google은 동의 후 7일이 지나면 만료되는 리프레시 토큰을 발급합니다. 따라서 모든 것이 정상 작동하다가 일주일 후 동기화가 중단되며, 그 원인을 알 수 없습니다. Audience 페이지에는 "프로덕션"으로 표시되어도 토큰 서버는 다를 수 있습니다. 브랜딩 페이지의 확인 상태 줄과 google-health-mcp doctor는 다릅니다. 후자는 저장된 토큰의 만료 기간이 짧을 때 오류를 명확히 표시합니다.

3. 인증

다운로드한 클라이언트 JSON을 편집하지 말고 서버가 찾는 위치에 넣습니다:

mkdir -p ~/.config/google-health-mcp
cp ~/Downloads/client_secret_*.json ~/.config/google-health-mcp/google_client.json
google-health-mcp auth

브라우저에 이 앱은 Google에서 인증되지 않았습니다라는 경고가 표시됩니다. 이는 정상이며, 이 앱은 사용자 본인의 앱입니다. 이러한 건강 범위는 제한적으로 분류되며, 인증은 사용자 100명 이상일 때만 중요합니다. 고급을 클릭한 다음 google-health-mcp(안전하지 않음)(으)로 이동을 클릭하고 범위를 승인합니다.

이 플로우는 localhost:8081에서 콜백을 수신하므로 해당 포트가 비어 있어야 합니다. 토큰은 0600 권한으로 ~/.config/google-health-mcp/google_tokens.json에 저장됩니다. 액세스 토큰은 1시간 동안 유효하며 자동으로 갱신됩니다. 리프레시 토큰은 회전하지 않으므로 브라우저가 있는 머신에서 생성된 토큰을 헤드리스 머신에 복사할 수 있습니다.

앱을 게시하기 전에 인증한 경우 나중에 google-health-mcp auth를 다시 실행하세요. 게시해도 이미 발급된 토큰이 연장되지는 않으며, 해당 토큰은 여전히 7일 후에 만료됩니다.

4. MCP 클라이언트에 등록

claude mcp add -s user google-health -- google-health-mcp

대신 uvx로 실행: claude mcp add -s user google-health -- uvx google-health-mcp.

5. 확인

google-health-mcp doctor

3단계(인증) 전후로 실행해 볼 만합니다. 포트 8081이 비어 있는지, 이 호스트에서 브라우저를 열 수 있는지 보고합니다. 이는 auth가 시작되기 전에 실패하는 두 가지 경우입니다.

오프라인 및 읽기 전용: 어떤 경로가 어디서 확인되었는지, 자격 증명 파일의 형식이 올바른지, 토큰이 단기인지, 캐시가 최신 상태로 유지되고 있는지 보고합니다.

6. 첫 번째 동기화(선택 사항)

쿼리 도구는 매일 첫 사용 시 동기화되므로 건너뛸 수 있습니다. 캐시를 미리 채우거나 더 오래된 기록을 가져오려면:

google-health-mcp sync --days 30
google-health-mcp sync --since 2023-10-01     # backfill

CLI 사용법

google-health-mcp                Start the MCP server (stdio transport)
google-health-mcp -V, --version  Print the installed package version
google-health-mcp auth           Interactive OAuth setup
google-health-mcp doctor         Check the setup and report what needs fixing
google-health-mcp sync           Sync data to the local cache
  --days N              Days of history for a first sync (default: 30)
  --types TYPE,...      Data types to sync (default: all). One or more of:
                        heart_rate, activity, exercises, sleep, weight, spo2,
                        hrv, azm, breathing_rate, skin_temperature,
                        core_temperature, cardio_fitness, food_log, ecg, irn
  --since YYYY-MM-DD    Fetch from this date, ignoring the incremental cursor
  --until YYYY-MM-DD    Inclusive end date for a --since window; together they
                        re-fetch exactly that window, to repair a gap in the
                        middle of the cache
google-health-mcp import         Import exported JSON data files
  --data-dir PATH       Directory containing the JSON files

MCP 도구 참조

쿼리 도구는 데이터 유형별로 매일 첫 번째 쿼리에서 동기화한 후 캐시를 읽습니다.

인수를 사용하지 않는 health_get_devices 및 health_get_lifetime_stats를 제외한 모든 쿼리 도구는 다음을 허용합니다:

• start_date - YYYY-MM-DD, YYYY-MM 또는 30d(상대적). 기본값: 최근 30일.

• end_date - YYYY-MM-DD. 기본값: 오늘.

• live - true이면 캐시를 읽기 전에 API에서 이 기간을 다시 가져옵니다. 새로 고침 실패는 캐시에서 자동으로 응답하지 않고 보고됩니다.

health_get_exercises는 운동 이름에 대해 대소문자를 구분하지 않는 부분 문자열 일치인 exercise_type도 사용합니다. health_get_ecg는 include_waveform도 사용합니다. 추적에는 수천 개의 전압이 포함되므로 기본 응답에는 분류, 평균 심박수, 지속 시간 및 샘플 수가 대신 포함됩니다.

health_sync

• data_types - all 또는 위의 CLI 사용법에 나열된 이름의 쉼표로 구분된 하위 집합(irn은 부정맥 알림). 기본값: all.

• days - 첫 번째 동기화의 기록 일수(기본값: 30). 이후 동기화는 증분입니다.

• since / until - 캐시된 내용과 관계없이 정확한 기간을 가져옵니다.

health_trends

• data_type - 일일 계열이 있는 모든 캐시된 유형. ECG 판독값과 리듬 알림은 에피소드이므로 추세가 없습니다. 기본값: activity.

• period - weekly, monthly, quarterly. 기본값: monthly.

• start_date / end_date - 기본값: 최근 12개월.

• compare - 두 기간(예: last_30d vs previous_30d, 2026-03 vs 2026-02, 2026-Q1 vs 2025-Q4). 설정하면 period, start_date 및 end_date는 무시됩니다.

OAuth 범위

데이터 액세스 페이지에서 다음 읽기 전용 범위를 선택합니다. 모두 https://www.googleapis.com/auth/googlehealth. 아래에 있습니다:

location.readonly 및 profile.readonly는 콘솔에서 제공하지만 이 패키지에서 의도적으로 요청하지 않는 두 가지입니다. 여기서는 둘 다 읽지 않기 때문입니다. 전자는 운동 중 기록된 GPS 추적입니다.

게시된 범위 페이지가 아닌 콘솔에서 목록을 읽으세요 - Google 문서나 API의 검색 문서에도 없는 읽기 전용 범위가 있으며, 검색 문서에는 nutrition.readonly가 아예 없습니다. 더 적게 요청하려면 데이터 액세스 페이지에서 더 적게 선택하고 인증 전에 config.py의 GOOGLE_SCOPES를 편집하세요. 이 경우 pip 또는 uvx 설치가 아닌 소스 체크아웃이 필요합니다. 권한 부여는 새로 고침 시 범위를 획득하지 않으므로 나중에 목록을 확장하려면 auth를 다시 실행해야 합니다.

구성

오프라인 / 캐시 전용 모드

기본적으로 서버는 요청 시 동기화하므로 cron 작업이 필요 없습니다. 대신 순수 읽기 전용으로 실행하려면 GOOGLE_HEALTH_MCP_OFFLINE=1을 설정하세요:

• 자격 증명이 필요 없습니다. 서버는 토큰 파일을 열지 않습니다.

• 네트워크 호출이 이루어지지 않습니다. 자동 동기화가 꺼져 있으며, live=True, health_get_devices, health_sync는 API에 접근하는 대신 명확한 "offline mode" 메시지를 반환합니다.

• 쿼리 도구는 캐시를 제공하며 "offline_mode": true로 표시됩니다.

일반적인 사용 사례:

• 여러 머신, 하나의 캐시 - 한 호스트가 공유 데이터베이스에 대해 cron 또는 systemd에서 google-health-mcp sync를 실행하고, 나머지 머신은 GOOGLE_HEALTH_MCP_OFFLINE=1을 설정하고 GOOGLE_HEALTH_MCP_DB_PATH를 같은 파일로 지정한 뒤 읽기만 합니다.

• CI 및 개인정보 보호 - 네트워크 접근과 자격 증명 없이 쿼리를 실행합니다.

속도 제한

Google은 developers.google.com/health/rate-limits에 문서화된 사용자별 요청 할당량을 적용합니다. 일반적인 동기화는 그에 한참 못 미칩니다. 하루 업데이트는 몇 건의 요청에 불과하며, 측정된 3년치 전체 데이터 유형 백필(backfill)은 약 250건이었습니다. 동기화가 중단되면 해당 데이터 유형은 부분 동기화로 기록되고 다음 실행은 처음부터 다시 시작하는 대신 커서(cursor)에서 재개됩니다.

기본값인 캐시에서의 쿼리는 할당량을 전혀 소모하지 않습니다.

데이터 안전

건강 데이터는 사용자 머신에만 남습니다. 이 서버에는 백엔드가 없고, 어디로도 아무것도 보내지 않으며, 사용자 자신의 자격 증명으로 Google API에만 통신합니다.

저장소에는 데이터베이스 파일, config/ 아래의 모든 항목, 그리고 대용량 파일의 커밋을 거부하는 pre-commit 훅이 포함되어 있습니다. 설치 방법은 CONTRIBUTING.md에 나와 있습니다.

기존 데이터 가져오기

내보내기나 직접 작성한 스크립트에서 얻은 JSON 파일 형태의 건강 데이터가 이미 있다면:

google-health-mcp import --data-dir /path/to/json/files/

예상 파일 이름: heart_rate.json, activity.json, exercises.json, sleep.json, weight.json, spo2.json, hrv.json. 각 파일이 기대하는 형식은 src/google_health_mcp/importer.py를 참조하세요. 가져오기는 이 일곱 가지 유형을 다루며, 그 외의 모든 것은 sync로 가져옵니다.

기여

개발 환경 설정, 테스트 워크플로, pre-commit 훅은 CONTRIBUTING.md를 참조하세요. 변경 사항은 CHANGELOG.md에서 추적됩니다.

라이선스

GPL-3.0-or-later