The Garmin Connect MCP server integrates Garmin fitness data with LLMs via the Model Context Protocol, enabling comprehensive running analysis, training planning, and wellness tracking through natural language interaction.
Activity Data
Retrieve recent and historical running activities with detailed metrics (pace, heart rate, cadence, power, stamina, impact load, GAP, elevation)
Access splits, weather conditions, advanced running dynamics, and trail-specific data (ClimbPro gradient analysis, Run/Walk detection)
Download activity files in TCX, GPX, or FIT formats
Training Analysis
Check training status, readiness, load balance, aerobic/anaerobic training effect, and recovery time
Analyze acute vs. chronic training load (ATL/CTL) for injury prevention
Evaluate workout execution quality against plans and get daily workout suggestions
Performance & Goals
Access VO2max, fitness age, lactate threshold, race predictions, and personal records (5K to marathon)
Calculate Jack Daniels VDOT training paces, threshold zones, and analyze endurance/hill scores
Set and track race goals; review long-term performance trends
Heart Rate & Wellness
Get daily heart rate, HRV, heart rate zone distributions, sleep data (stages/quality), stress levels, Body Battery, SpO2, and respiration
View weekly wellness trend summaries
Workout & Training Plan Management
Create structured workouts (interval, tempo, etc.) with custom pace/heart rate/cadence/power targets and sync to Garmin devices
List, view, and schedule Garmin training plans aligned with personal calendars
Gear & Device Management
Track running shoe mileage, wear rates, and get replacement alerts
Access connected Garmin device info, settings, and configuration
Methodology Support Supports Jack Daniels VDOT, Norwegian Double Threshold, 80/20 Training, Hanson's Method, and Pfitzinger plans.
Privacy Automatically filters PII (owner names, profile IDs, GPS coordinates) from all API responses.
Provides access to Garmin Connect data to retrieve running performance metrics like VO2 Max and training status, analyze activity details, monitor health indicators such as heart rate and sleep, and manage personalized training plans.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Garmin Connect MCPAnalyze my recent runs and suggest a workout based on my recovery status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 계정
설치
인증
최초 1회 인증이 필요합니다.
이메일, 비밀번호를 입력하면 OAuth 토큰이 ~/.garminconnect/에 저장됩니다. MFA 사용 시 코드 입력 프롬프트가 나타납니다.
토큰이 만료되면 다시 실행하거나,
.env파일에 자격증명을 설정하면 자동 갱신됩니다.
Claude Desktop 연동
~/Library/Application Support/Claude/claude_desktop_config.json에 추가:
uv의 전체 경로를 사용해야 합니다.which uv로 확인하세요.
설정 후 Claude Desktop을 재시작하면 도구가 활성화됩니다.
환경 변수 (선택)
.env.example을 참고하여 .env 파일을 생성합니다.
변수 | 설명 | 기본값 |
| Garmin Connect 이메일 | - |
| Garmin Connect 비밀번호 | - |
| 토큰 저장 경로 |
|
| Base64 인코딩 토큰 (CI/Docker용) | - |
제공 도구 (24개)
Activities
도구 | 설명 | 주요 파라미터 |
| 최근 러닝 활동 목록 (GAP, RWD 포함) |
|
| 날짜 범위로 러닝 활동 조회 |
|
| 활동 상세 정보 (스태미나, 임팩트 로드 포함) |
|
| km별 스플릿 데이터 |
|
| 활동 중 날씨 조건 (온도, 습도, 풍속) |
|
| ClimbPro 경사 구간 분석 (등급, GAP) |
|
Summary
도구 | 설명 | 주요 파라미터 |
| 주간 러닝 요약 |
|
| 월간 러닝 요약 + 전월 비교 |
|
Training
도구 | 설명 | 주요 파라미터 |
| 훈련 상태 |
|
| 훈련 준비도 점수 |
|
| VO2max + 피트니스 나이 |
|
| 5K/10K/하프/풀 예상 기록 | 없음 |
| 젖산역치 심박/페이스 |
|
Heart Rate
도구 | 설명 | 주요 파라미터 |
| 일간 심박 데이터 |
|
| 심박변이도 (HRV) |
|
| 활동별 심박존 분포 |
|
Wellness
도구 | 설명 | 주요 파라미터 |
| 수면 데이터 |
|
| 스트레스/바디배터리/SpO2/호흡수 |
|
| 주간 웰니스 트렌드 |
|
Records & Goals
도구 | 설명 | 주요 파라미터 |
| 개인 기록 (1K~마라톤) | 없음 |
| 피트니스 목표 |
|
Workout
도구 | 설명 | 주요 파라미터 |
| 워크아웃 생성 및 Garmin에 업로드 (시간/거리 기반, 페이스/심박/케이던스/파워 타겟) |
|
| 저장된 워크아웃 목록 |
|
Gear
도구 | 설명 | 주요 파라미터 |
| 러닝화 목록 + 누적 거리 + 마모율 | 없음 |
워크아웃 생성 가이드
create_running_workout으로 구조화된 러닝 워크아웃을 생성하고 Garmin 워치에 동기화할 수 있습니다.
Step 타입
타입 | 설명 |
| 워밍업 |
| 인터벌 (고강도) |
| 회복 조깅 |
| 완전 휴식 (서서 쉬기) |
| 쿨다운 |
| 반복 그룹 |
종료 조건 (Step 기간)
필드 | 타입 | 설명 | 예시 |
| int | 시간 기반 |
|
| int | 거리 기반 |
|
하나의 워크아웃에서 시간/거리 기반 step을 혼합 사용할 수 있습니다.
Target 타입
타입 | 값 형식 | 예시 |
| min:sec/km |
|
| bpm |
|
| spm |
|
| watts |
|
옵션
워크아웃 메모:
description파라미터로 전체 설명 추가Step 메모: 각 step에
"description": "메모"추가마지막 회복 건너뛰기: repeat step에
"skip_last_rest": true추가
예시: 4x1km 거리 기반 인터벌
상세 워크아웃 생성 가이드는 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 |
개발
개인정보 보호
모든 Garmin API 응답에서 다음 개인정보 필드가 자동으로 제거됩니다:
소유자 정보:
ownerId,ownerFullName,ownerDisplayName,userId, 프로필 이미지 URL프로필 ID:
userProfilePK,userProfileId,profileId,profileNumber사용자 정보:
displayName,fullName,userPro,userRolesGPS 좌표:
startLatitude,startLongitude,endLatitude,endLongitude
이 필터링은 src/garmin_mcp/sanitize.py의 strip_pii() 함수를 통해 재귀적으로 처리됩니다.
기술 스택
python-garminconnect - Garmin Connect API 클라이언트
FastMCP - MCP 서버 프레임워크
uv - Python 패키지 매니저
garth - OAuth 토큰 관리
라이선스
MIT