Garmin China MCP

Garmin Connect 중국 지역 MCP 서버 — 55개의 도구로 훈련 데이터, 회복 지표, 날씨 열 스트레스 평가 및 건강 집계를 포함합니다.

WorkBuddy, Claude Desktop 등 MCP(Model Context Protocol)를 지원하는 모든 클라이언트에 적합합니다.

설치

pip install garmin-china

또는 uv 사용 (권장):

uv pip install garmin-china

Related MCP server: Garmin Connect China MCP Server

인증

처음 사용 시 Garmin Connect 중국 지역에 로그인하여 token을 받아야 합니다:

# PowerShell
$env:GARMIN_EMAIL='你的邮箱@qq.com'
$env:GARMIN_PASSWORD='你的佳明密码'
garmin-china-auth

# Bash
export GARMIN_EMAIL='你的邮箱@qq.com'
export GARMIN_PASSWORD='你的佳明密码'
garmin-china-auth

Token은 ~/.garmin-china/tokens/에 저장됩니다. GARMIN_TOKEN_DIR 환경 변수로 경로를 덮어쓸 수 있습니다.

⚠️ 반드시 일반 권한 터미널에서 인증을 실행하세요. 관리자 터미널을 사용하면 token 파일의 소유자가 Administrators가 되어 일반 프로세스가 읽을 수 없습니다.

MCP 클라이언트 구성

WorkBuddy

~/.workbuddy/mcp.json 편집 (참고: .mcp.json이 아님):

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-china",
      "disabled": false
    }
  }
}

Claude Desktop

claude_desktop_config.json 편집:

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-china"
    }
  }
}

uvx 사용 (설치 불필요)

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-china"]
    }
  }
}

구성 후 클라이언트를 다시 시작하고, 커넥터 관리에서 garmin 서버를 신뢰하면 됩니다.

도구 목록 (55개)

훈련 및 활동 (20)

• activities / last_activity / get_activity — 활동 목록 및 상세

• activity_splits / activity_split_summaries / activity_typed_splits — 구간 데이터

• activity_hr_in_timezones / get_activity_gear — 심박수 시간대 및 장비

• count_activities / get_activity_types — 통계 및 유형

• download_workout / get_workouts / get_workout_templates — 훈련 계획

• get_activity_weather / get_activity_exercise_sets — 날씨 및 세트 수

• steps_data / daily_steps / get_weekly_steps — 걸음 수

• get_activities_fordate — 날짜별 활동 조회

회복 및 건강 (18)

• user_summary / daily_summary — 일일 요약

• sleep — 수면 분석

• hrv / hr_intraday / resting_hr — 심박 변이도 및 심박수

• body_battery — 신체 배터리

• stress / get_weekly_stress — 스트레스

• spo2 / respiration — 혈중 산소 및 호흡

• hydration — 수분 보충

• weight — 체중

• training_status / training_readiness — 훈련 상태 및 준비도

• vo2max / race_predictions — 최대 산소 섭취량 및 경기 예측

• get_goals / personal_record — 목표 및 개인 기록

• endurance_score / hill_score / lactate_threshold / get_fitness_age — 체력 지표

주간 보고서 및 트렌드 (10)

• weekly_health / stats_trend / progress_summary — 주간 보고서 및 트렌드

• weekly_intensity_minutes — 주간 강도 시간

• user_summary / garmin_weekly_health — 건강 집계

날씨 및 열 스트레스 (7)

• weather_now — 실시간 날씨 + 달리기 열 스트레스 평가 + 페이스 감소

• weather_forecast — 시간별 예보

• weather_at — 지정 시간 과거 실제 상황

• weather_log — 기상 로그 아카이브 (24시간 이전 데이터)

• weather_pace — 페이스 열 보정 계산기

• garmin_run_conditions — 달리기와 기후 통합 평가 (등가 페이스 포함)

• garmin_weekly_health — 주간 건강 집계

날씨 로그 아카이브 (선택 사항)

공식 시간별 실제 상황은 24시간 이전 데이터만 제공합니다. Windows 예약 작업을 등록하여 자동 아카이브:

garmin-china-weather --install    # 注册（每 6 小时归档一次）
garmin-china-weather --uninstall  # 卸载

로그는 ~/.garmin-china/weather-log/에 저장됩니다.

자체 점검

garmin-china-selftest            # 检查协议与工具注册
garmin-china-selftest --call     # 额外调用真实数据验证

주의 사항

• garminconnect를 0.3.x로 업그레이드하지 마세요 — 중국 지역 DI token이 모두 실패합니다. 0.2.40으로 고정되었습니다.

• 인증은 일반 권한 터미널을 사용해야 합니다 — 관리자 터미널을 사용하면 token 파일 권한 문제가 발생합니다.

• Garmin 중국 지역(garmin.cn)만 지원합니다 — 국제판 Garmin Connect에는 적용되지 않습니다.

기술 스택

• Python ≥ 3.11

• garminconnect 0.2.40 + garth 0.6.3 (OAuth 인증)

• mcp ≥ 1.29.0 (Model Context Protocol)

• 날씨 데이터 출처: 중국 기상국 공공 기상 서비스 센터 (weather.com.cn)

License

MIT