Skip to main content
Glama

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 파일을 생성합니다.

변수

설명

기본값

GARMIN_EMAIL

Garmin Connect 이메일

-

GARMIN_PASSWORD

Garmin Connect 비밀번호

-

GARMIN_TOKEN_DIR

토큰 저장 경로

~/.garminconnect

GARMINTOKENS

Base64 인코딩 토큰 (CI/Docker용)

-

제공 도구 (24개)

Activities

도구

설명

주요 파라미터

get_recent_activities

최근 러닝 활동 목록 (GAP, RWD 포함)

count (기본 20, 최대 100)

get_activities_by_date

날짜 범위로 러닝 활동 조회

start_date, end_date

get_activity_detail

활동 상세 정보 (스태미나, 임팩트 로드 포함)

activity_id

get_activity_splits

km별 스플릿 데이터

activity_id

get_activity_weather

활동 중 날씨 조건 (온도, 습도, 풍속)

activity_id

get_activity_typed_splits

ClimbPro 경사 구간 분석 (등급, GAP)

activity_id

Summary

도구

설명

주요 파라미터

get_weekly_running_summary

주간 러닝 요약

end_date, weeks (최대 12)

get_monthly_running_summary

월간 러닝 요약 + 전월 비교

year, month

Training

도구

설명

주요 파라미터

get_training_status

훈련 상태

date

get_training_readiness

훈련 준비도 점수

date

get_vo2max_and_fitness

VO2max + 피트니스 나이

date

get_race_predictions

5K/10K/하프/풀 예상 기록

없음

get_lactate_threshold

젖산역치 심박/페이스

start_date, end_date

Heart Rate

도구

설명

주요 파라미터

get_heart_rate_data

일간 심박 데이터

date

get_hrv_data

심박변이도 (HRV)

date

get_activity_hr_zones

활동별 심박존 분포

activity_id

Wellness

도구

설명

주요 파라미터

get_sleep_data

수면 데이터

date

get_daily_wellness

스트레스/바디배터리/SpO2/호흡수

date

get_weekly_wellness_summary

주간 웰니스 트렌드

end_date, weeks (최대 4)

Records & Goals

도구

설명

주요 파라미터

get_personal_records

개인 기록 (1K~마라톤)

없음

get_goals

피트니스 목표

status (active/completed/all)

Workout

도구

설명

주요 파라미터

create_running_workout

워크아웃 생성 및 Garmin에 업로드 (시간/거리 기반, 페이스/심박/케이던스/파워 타겟)

name, steps, description

get_workouts

저장된 워크아웃 목록

count (기본 20, 최대 100)

Gear

도구

설명

주요 파라미터

get_running_gear

러닝화 목록 + 누적 거리 + 마모율

없음

워크아웃 생성 가이드

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

Step 타입

타입

설명

warmup

워밍업

interval

인터벌 (고강도)

recovery

회복 조깅

rest

완전 휴식 (서서 쉬기)

cooldown

쿨다운

repeat

반복 그룹

종료 조건 (Step 기간)

필드

타입

설명

예시

duration_seconds

int

시간 기반

"duration_seconds": 300 (5분)

distance_meters

int

거리 기반

"distance_meters": 1000 (1km)

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

Target 타입

타입

값 형식

예시

pace

min:sec/km

"min": "4:30", "max": "4:50"

heart_rate

bpm

"min": 140, "max": 155

cadence

spm

"min": 170, "max": 185

power

watts

"min": 280, "max": 320

옵션

  • 워크아웃 메모: 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 인터벌 워크아웃 만들어줘"

  • "내 러닝화 중 교체 시기가 된 것이 있는지 확인해줘"

  • "수면과 훈련 준비도의 상관관계를 분석해줘"

  • "최근 트레일러닝의 경사 구간별 성과를 분석해줘"

  • "트레일러닝에서 걷기/달리기 비율을 확인해줘"

지원하는 러닝 훈련 방법론

방법론

활용 데이터

Jack Daniels VDOT

VO2max, PR, 레이스 예측

Norwegian Double Threshold

젖산역치, 심박존

80/20 Training

심박존 분포

Hanson's Method

주간/월간 볼륨, 페이스 트렌드

Pfitzinger

주간 볼륨, 장거리 런 분석

트레일/울트라 분석

ClimbPro 경사 구간, 날씨, RWD, GAP

개발

# 코드 수정 후 패키지 재설치 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.pystrip_pii() 함수를 통해 재귀적으로 처리됩니다.

기술 스택

라이선스

MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/leewnsdud/garmin-connect-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server