Garmin Connect MCP Server

garmin-mcp

Garmin Connect 러닝 데이터를 LLM에 제공하는 MCP(Model Context Protocol) 서버입니다.

Claude Desktop 등 MCP 클라이언트와 연동하여 러닝 훈련 분석, 계획 수립, 워크아웃 생성 등을 수행할 수 있습니다.

주요 기능

• 러닝 활동 조회 - 최근 활동, 날짜별 조회, 상세 분석, 스플릿 데이터 (47개 필드: 페이스, 심박, 케이던스, 러닝 다이나믹스, 파워, HR존, GAP, 경사도, 스태미나, 온도 등)
• 트레일러닝 분석 - ClimbPro 경사 구간 분석, 등급별 난이도, Grade Adjusted Pace, Run/Walk Detection, 날씨 조건
• 주간/월간 요약 - 볼륨 트렌드, 전월 대비 비교
• 훈련 지표 - VO2max, 훈련 상태, 훈련 준비도, 레이스 예측, 젖산역치
• 심박/HRV - 일간 심박, 심박변이도, 활동별 심박존 분포
• 웰니스 - 수면, 스트레스, 바디배터리, SpO2
• 개인 기록/목표 - PR, 피트니스 목표
• 워크아웃 생성 - 시간/거리 기반 인터벌, 템포 등 구조화된 워크아웃을 Garmin 워치에 전송 (페이스/심박/케이던스/파워 타겟)
• 러닝화 관리 - 신발별 누적 거리 + 마모율 추적
• 개인정보 보호 - 모든 API 응답에서 PII(소유자 이름, 프로필 ID, GPS 좌표) 자동 필터링

요구 사항

• Python 3.10+
• uv 패키지 매니저
• Garmin Connect 계정

설치

git clone https://github.com/leewnsdud/garmin-connect-mcp.git
cd garmin-connect-mcp
uv sync

인증

최초 1회 인증이 필요합니다.

uv run python scripts/auth.py

이메일, 비밀번호를 입력하면 OAuth 토큰이 ~/.garminconnect/에 저장됩니다. MFA 사용 시 코드 입력 프롬프트가 나타납니다.

토큰이 만료되면 다시 실행하거나, .env 파일에 자격증명을 설정하면 자동 갱신됩니다.

Claude Desktop 연동

~/Library/Application Support/Claude/claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "garmin-mcp": {
      "command": "/Users/<username>/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/garmin-mcp",
        "run",
        "garmin-mcp"
      ]
    }
  }
}

uv의 전체 경로를 사용해야 합니다. which uv로 확인하세요.

설정 후 Claude Desktop을 재시작하면 도구가 활성화됩니다.

환경 변수 (선택)

.env.example을 참고하여 .env 파일을 생성합니다.

제공 도구 (24개)

Activities

Summary

Training

Heart Rate

Wellness

Records & Goals

Workout

Gear

워크아웃 생성 가이드

create_running_workout으로 구조화된 러닝 워크아웃을 생성하고 Garmin 워치에 동기화할 수 있습니다.

Step 타입

종료 조건 (Step 기간)

하나의 워크아웃에서 시간/거리 기반 step을 혼합 사용할 수 있습니다.

Target 타입

옵션

• 워크아웃 메모: description 파라미터로 전체 설명 추가
• Step 메모: 각 step에 "description": "메모" 추가
• 마지막 회복 건너뛰기: repeat step에 "skip_last_rest": true 추가

예시: 4x1km 거리 기반 인터벌

{
  "name": "4x1km Intervals @4:30",
  "description": "10K 레이스 대비 VO2max 인터벌",
  "steps": [
    {
      "typ