Garmin Connect MCP
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 "Deploy 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 MCP Analyze 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 좌표) 자동 필터링
Related MCP server: Garmin MCP Lite
요구 사항
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 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 거리 기반 인터벌
{
"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,userRolesGPS 좌표:
startLatitude,startLongitude,endLatitude,endLongitude
이 필터링은 src/garmin_mcp/sanitize.py의 strip_pii() 함수를 통해 재귀적으로 처리됩니다.
기술 스택
python-garminconnect - Garmin Connect API 클라이언트
FastMCP - MCP 서버 프레임워크
uv - Python 패키지 매니저
garth - OAuth 토큰 관리
라이선스
MIT
Available Tools
43 toolsanalyze_heart_rate_zonesC
Analyze heart rate zone distribution and time spent in each zone for an activity
Inputs: activity_id (required).
analyze_threshold_zonesB
Analyze lactate threshold zones for double threshold training
Inputs: no named parameters.
analyze_training_loadC
Analyze training load and recovery status to prevent injury
Inputs: weeks_back.
analyze_workout_qualityC
Analyze how well a workout was executed compared to plan
Inputs: activity_id (required), planned_workout.
calculate_training_pacesA
Calculate Jack Daniels training paces based on recent race performance
Inputs: race_distance (required), race_time (required).
calculate_vdot_zonesC
Calculate VDOT and training zones based on recent race performance or time trial
Inputs: race_distance (required), race_time (required).
download_activity_fileC
Download activity data in various file formats (TCX, GPX, FIT)
Inputs: activity_id (required), format.
get_activities_for_dateC
Get all activities for a specific date
Inputs: date (required).
get_activity_detailsB
Get comprehensive activity metrics including splits, advanced metrics, and performance data. Response size optimized for Claude context window.
Inputs: activity_id (required), maxchart, maxpoly, include_raw.
get_activity_summaryC
Get basic activity information including distance, time, pace, and elevation
Inputs: activity_id (required).
get_advanced_running_metricsC
Get advanced running metrics including stride length, vertical ratio, vertical amplitude, ground contact time
Inputs: activity_id (required).
get_body_batteryC
Get body battery energy levels throughout the day
Inputs: date.
get_daily_activityB
Get daily activity metrics including steps, floors climbed, and intensity minutes
Inputs: date.
get_devicesB
Get information about all connected Garmin devices
Inputs: no named parameters.
get_device_settingsC
Get device settings and configuration
Inputs: device_id.
get_endurance_scoreB
Get endurance performance score indicating aerobic endurance capability
Inputs: date.
get_gear_insightsB
Analyze running gear usage to surface mileage totals, replacement alerts, and recent utilization patterns
Inputs: distance_threshold_km, include_retired, max_items.
get_heart_rate_metricsC
Get heart rate metrics including resting heart rate and heart rate variability (HRV)
Inputs: date.
get_hill_scoreC
Get hill running performance score indicating uphill running capability
Inputs: date.
get_hrv_dataB
Get detailed heart rate variability (HRV) data for recovery and stress analysis
Inputs: date.
get_lactate_thresholdB
Get lactate threshold pace and heart rate data
Inputs: date.
get_paginated_activitiesB
Get activities with proper pagination support to handle large datasets
Inputs: start, limit, activity_type.
get_personal_recordsB
Get personal best times for running distances (5K, 10K, half marathon, full marathon)
Inputs: distances.
get_primary_training_deviceB
Get primary training device information for running activities
Inputs: no named parameters.
get_race_predictionsB
Get predicted race times based on current fitness level
Inputs: no named parameters.
get_recent_running_activitiesB
Get recent running activities with cursor-based pagination. Returns activities with pagination metadata and resource URIs for detailed data.
Inputs: limit, days_back, cursor.
get_recovery_timeB
Get recommended recovery time after recent activities
Inputs: no named parameters.
get_respiration_dataC
Get daily respiration data including breathing rate and patterns
Inputs: date.
get_running_trendsC
Get running performance trends over a specified period. Response size optimized for Claude context window.
Inputs: months_back.
get_sleep_analysisC
Get detailed sleep data including sleep stages, quality, and duration
Inputs: date.
get_spo2_dataB
Get blood oxygen saturation (SpO2) levels throughout the day
Inputs: date.
get_stress_levelsC
Get stress level data and analysis
Inputs: date.
get_training_effectB
Get aerobic and anaerobic training effect analysis
Inputs: days_back.
get_training_load_balanceB
Get acute vs chronic training load balance (ATL/CTL ratio) for injury prevention
Inputs: weeks_back.
get_training_plan_overviewB
Summarize a specific Garmin training plan including high-level details, phases, and schedule preview
Inputs: plan_id (required), schedule_weeks.
get_training_plan_scheduleB
Build a weekly schedule snapshot for a training plan, including personal calendar alignment when available
Inputs: plan_id (required), weeks, include_calendar.
get_training_readinessC
Get training readiness score and recommendations
Inputs: date.
get_training_statusB
Get current training status including training effect, load balance, and fitness trends
Inputs: date.
get_vo2maxB
Get current VO2 Max value and historical data
Inputs: date.
get_weekly_running_summaryC
Get comprehensive weekly running summary with trends and analysis
Inputs: weeks_back.
list_training_plansA
List available Garmin running training plans with optional filters for goal distance and experience level
Inputs: goal_distance, experience_level, max_items.
set_race_goalC
Set a target race goal and track progress
Inputs: race_distance (required), target_time (required), race_date (required).
suggest_daily_workoutC
Suggest appropriate workout based on current condition and training phase
Inputs: training_phase.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Most tools have distinct purposes, but there is some overlap in analysis tools (e.g., analyze_training_load, get_training_load_balance, get_training_status) and data retrieval tools (e.g., get_activities_for_date, get_paginated_activities, get_recent_running_activities) that could cause confusion. Descriptions help differentiate them, but the boundaries are not always clear.
Tool names follow a highly consistent verb_noun pattern throughout, with clear and descriptive naming (e.g., get_activity_details, analyze_heart_rate_zones, calculate_training_paces). There are no deviations in style or convention, making the set predictable and readable.
With 43 tools, the count is excessive for the server's purpose of Garmin Connect integration. Many tools could be consolidated (e.g., multiple get_* tools for similar data types), leading to a bloated and overwhelming interface that may hinder agent usability.
The tool set provides comprehensive coverage for fitness and training data, including activity retrieval, analysis, metrics, planning, and recovery. It supports full CRUD-like operations (e.g., get, analyze, set, suggest) across the domain, with no obvious gaps in functionality.
Maintenance
Related MCP Connectors
Adaptive running coach MCP server — training data, plans, and recovery for AI assistants.
AI coach for Garmin: builds training plans and structured workouts, synced straight to your watch.
Pace is a remote MCP server that exposes wearable and fitness data to Claude via the Model Context Protocol. It connects to Garmin, Oura, Whoop, Polar, Fitbit and 20+ devices and provides 15 tools for querying sleep, activity, recovery, and training data. Hosted on Google Cloud Run, OAuth 2.1 authentication, Streamable HTTP transport. Instructions: First you need to create an account at: https://pacetraining.co and connect your wearables. After that you can connect the remote Server via Custom Connector in Claude and OAuth 2.1 Flow startet.
Running coach: your AI reads your runs and recovery, and writes sessions to your watch or phone.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server that connects Garmin Connect data to Claude, enabling training analysis, recovery checks, and personalized plans based on real metrics like HRV, training load, and activities.24MIT
- AlicenseAqualityBmaintenanceA lightweight Garmin Model Context Protocol server with 12 curated endpoints for endurance athletes, enabling natural-language queries of activity, training, health, device, and goal data from Garmin Connect.28MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server for Garmin Connect integration. Access your activities, health data, training metrics, and more through Claude and other LLMs.2268MIT
- FlicenseAqualityDmaintenanceMCP server that connects AI assistants to Garmin Connect health and fitness data, enabling natural language queries about workouts, sleep, heart rate, and more.29-