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": [
    {
      "type": "warmup",
      "duration_seconds": 600,
      "description": "가볍게 조깅"
    },
    {
      "type": "repeat",
      "count": 4,
      "skip_last_rest": true,
      "steps": [
        {
          "type": "interval",
          "distance_meters": 1000,
          "target": { "type": "pace", "min": "4:20", "max": "4:40" },
          "description": "목표 페이스 유지"
        },
        {
          "type": "recovery",
          "duration_seconds": 120,
          "description": "천천히 조깅으로 회복"
        }
      ]
    },
    {
      "type": "cooldown",
      "duration_seconds": 600,
      "description": "마무리 조깅"
    }
  ]
}

상세 워크아웃 생성 가이드는 AGENTS.md를, 전체 도구 요청/응답 규격은 TOOL_SPEC.md를 참조하세요.

활용 예시

Claude Desktop에서 다음과 같이 활용할 수 있습니다:

• "이번 주 러닝 요약해줘"
• "최근 3개월 주간 볼륨 트렌드 분석해줘"
• "내 VO2max 기준으로 Jack Daniels VDOT 훈련 페이스 계산해줘"
• "최근 활동들의 심박존 분포를 보고 80/20 비율을 지키고 있는지 확인해줘"
• "내일 4x1km 인터벌 워크아웃 만들어줘"
• "내 러닝화 중 교체 시기가 된 것이 있는지 확인해줘"
• "수면과 훈련 준비도의 상관관계를 분석해줘"
• "최근 트레일러닝의 경사 구간별 성과를 분석해줘"
• "트레일러닝에서 걷기/달리기 비율을 확인해줘"

지원하는 러닝 훈련 방법론

개발

# 코드 수정 후 패키지 재설치
uv sync --reinstall-package garmin-mcp

# Claude Desktop 재시작으로 MCP 서버 반영

개인정보 보호

모든 Garmin API 응답에서 다음 개인정보 필드가 자동으로 제거됩니다:

• 소유자 정보: ownerId, ownerFullName, ownerDisplayName, userId, 프로필 이미지 URL
• 프로필 ID: userProfilePK, userProfileId, profileId, profileNumber
• 사용자 정보: displayName, fullName, userPro, userRoles
• GPS 좌표: startLatitude, startLongitude, endLatitude, endLongitude

이 필터링은 src/garmin_mcp/sanitize.py의 strip_pii() 함수를 통해 재귀적으로 처리됩니다.

기술 스택

• python-garminconnect - Garmin Connect API 클라이언트
• FastMCP - MCP 서버 프레임워크
• uv - Python 패키지 매니저
• garth - OAuth 토큰 관리

라이선스

MIT