garmin-china
Provides tools for accessing Garmin Connect China data, including training activities, recovery metrics, weather/heat stress assessment, and health aggregation, enabling AI agents to retrieve and analyze fitness and health information.
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-china what's my training readiness and today's weather for morning run?"
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 China MCP
Garmin Connect China Region MCP Server — 55 tools covering training data, recovery metrics, weather heat stress assessment, and health aggregation.
Compatible with WorkBuddy, Claude Desktop, and any client supporting MCP (Model Context Protocol).
Installation
pip install garmin-chinaOr use uv (recommended):
uv pip install garmin-chinaRelated MCP server: Garmin Coach MCP
Authentication
On first use, log in to Garmin Connect China to obtain a token:
# PowerShell
$env:GARMIN_EMAIL='你的邮箱@qq.com'
$env:GARMIN_PASSWORD='你的佳明密码'
garmin-china-auth
# Bash
export GARMIN_EMAIL='你的邮箱@qq.com'
export GARMIN_PASSWORD='你的佳明密码'
garmin-china-authToken is saved to ~/.garmin-china/tokens/. Override the path with the GARMIN_TOKEN_DIR environment variable.
⚠️ Run authentication in a normal-privilege terminal. An admin terminal will set the token file owner to Administrators, making it unreadable by normal processes.
Configure MCP Client
WorkBuddy
Edit ~/.workbuddy/mcp.json (note: not .mcp.json):
{
"mcpServers": {
"garmin": {
"command": "garmin-china",
"disabled": false
}
}
}Claude Desktop
Edit claude_desktop_config.json:
{
"mcpServers": {
"garmin": {
"command": "garmin-china"
}
}
}Using uvx (no installation required)
{
"mcpServers": {
"garmin": {
"command": "uvx",
"args": ["garmin-china"]
}
}
}After configuration, restart the client and trust the garmin server in the connector manager.
Tool List (55)
Training & Activities (20)
activities/last_activity/get_activity— Activity list and detailsactivity_splits/activity_split_summaries/activity_typed_splits— Split dataactivity_hr_in_timezones/get_activity_gear— Heart rate time zones and gearcount_activities/get_activity_types— Statistics and typesdownload_workout/get_workouts/get_workout_templates— Training plansget_activity_weather/get_activity_exercise_sets— Weather and exercise setssteps_data/daily_steps/get_weekly_steps— Stepsget_activities_fordate— Query activities by date
Recovery & Health (18)
user_summary/daily_summary— Daily summarysleep— Sleep analysishrv/hr_intraday/resting_hr— Heart rate variability and heart ratebody_battery— Body batterystress/get_weekly_stress— Stressspo2/respiration— Blood oxygen and respirationhydration— Hydrationweight— Weighttraining_status/training_readiness— Training status and readinessvo2max/race_predictions— VO2 max and race predictionsget_goals/personal_record— Goals and personal recordsendurance_score/hill_score/lactate_threshold/get_fitness_age— Fitness metrics
Weekly Reports & Trends (10)
weekly_health/stats_trend/progress_summary— Weekly reports and trendsweekly_intensity_minutes— Weekly intensity minutesuser_summary/garmin_weekly_health— Health aggregation
Weather & Heat Stress (7)
weather_now— Real-time weather + running heat stress assessment + pace degradationweather_forecast— Hourly forecastweather_at— Historical conditions at a specified timeweather_log— Weather log archive (24-hour retrospective)weather_pace— Pace heat correction calculatorgarmin_run_conditions— Combined running and climate evaluation (including equivalent pace)garmin_weekly_health— Weekly health aggregation
Weather Log Archive (Optional)
Official hourly observations only go back 24 hours. Register a Windows scheduled task for automatic archiving:
garmin-china-weather --install # 注册(每 6 小时归档一次)
garmin-china-weather --uninstall # 卸载Logs are saved to ~/.garmin-china/weather-log/.
Self-Check
garmin-china-selftest # 检查协议与工具注册
garmin-china-selftest --call # 额外调用真实数据验证Red Lines
Do not upgrade garminconnect to 0.3.x — All China region DI tokens will fail. Locked at
0.2.40.Authentication must use a normal-privilege terminal — An admin terminal will cause token file permission issues.
Only supports Garmin China region (garmin.cn) — Not compatible with international Garmin Connect.
Tech Stack
Python ≥ 3.11
garminconnect 0.2.40 + garth 0.6.3 (OAuth authentication)
mcp ≥ 1.29.0 (Model Context Protocol)
Weather data source: China Meteorological Administration Public Weather Service Center (weather.com.cn)
License
MIT
Available Tools
55 toolsactivitiesB
活动列表 — 指定日期范围内的活动(跑步/骑行等)
Inputs: end, start, activity_type. Returns: result
activity_detailA
活动详情 — 指定活动的详细数据(逐公里配速、心率分段等)
Inputs: activity_id (required). Returns: result
body_batteryC
身体电量 — 当日或指定日期范围的身体电量
Inputs: end, start. Returns: result
count_activitiesA
账户内活动总数
Inputs: no named parameters. Returns: result
daily_stepsC
每日步数 — 指定日期范围的每日步数
Inputs: end, start. Returns: result
download_workoutC
下载训练计划为 FIT 文件(base64)
Inputs: workout_id (required). Returns: result
garmin_run_conditionsA
【核心】把一次跑步与当时的真实气候合并评价:输出实际配速、当时温湿度、 热应激等级,以及折算到凉爽标准条件下的等效配速。 传入 target_pace(如 4'35")时,按热修正后的标准判定完成度—— 湿热天直接拿原始配速对比计划,会严重低估实际努力程度。 气温以气象站实况为准(客观且含湿度),手表实测温度作为体表微环境对照列出。
Inputs: activity_id (required), target_pace. Returns: result
garmin_weekly_healthB
获取最近 N 周的健康聚合趋势,分三个并行序列呈现:
强度分钟(中/高强度,高强度按 2 倍计入)
步数(周总步数、日均步数)
平均压力(数值越低越好,反映恢复/心理负荷) 用于观察训练负荷与恢复的长期趋势。weeks 默认 8 周,end 为结束日期(留空=今天)。 注:Garmin 三项指标的「周起始日」定义不同,故分序列列出,不直接按日期合并。
Inputs: end, weeks. Returns: result
get_activities_fordateC
指定某一天的活动中列表
Inputs: date. Returns: result
get_activityC
活动基础信息(原始)
Inputs: activity_id (required). Returns: result
get_activity_exercise_setsC
力量训练活动的动作组
Inputs: activity_id (required). Returns: result
get_activity_gearD
活动使用的装备
Inputs: activity_id (required). Returns: result
get_activity_hr_in_timezonesC
活动心率分时段数据
Inputs: activity_id (required). Returns: result
get_activity_splitsC
活动分段(每公里/每英里配速等)
Inputs: activity_id (required). Returns: result
get_activity_split_summariesD
活动分段汇总
Inputs: activity_id (required). Returns: result
get_activity_typed_splitsD
活动类型化分段
Inputs: activity_id (required). Returns: result
get_activity_typesB
所有可用运动类型
Inputs: no named parameters. Returns: result
get_activity_weatherD
活动天气数据
Inputs: activity_id (required). Returns: result
get_endurance_scoreD
耐力分数
Inputs: end_date, start_date. Returns: result
get_fitnessage_dataD
体适能年龄
Inputs: date, details. Returns: result
get_gearC
账户下所有装备(含默认运动关联)
Inputs: include_stats. Returns: result
get_goalsC
Garmin 目标(active/future/past)
Inputs: goal_type. Returns: result
get_hill_scoreD
爬坡分数
Inputs: end_date, start_date. Returns: result
get_lactate_thresholdD
乳酸阈值
Inputs: end_date, start_date. Returns: result
get_progress_summary_between_datesC
两日期间某指标的进度摘要
Inputs: metric, end_date, start_date. Returns: result
get_training_effectC
活动的训练效果(有氧/无氧训练负荷)
Inputs: activity_id (required). Returns: result
get_weekly_intensity_minutesC
每周强度分钟聚合(需起止两个日期)
Inputs: end_date, start_date. Returns: result
get_weekly_stepsC
每周步数聚合
Inputs: weeks, end_date. Returns: result
get_weekly_stressC
每周压力聚合
Inputs: weeks, end_date. Returns: result
get_workout_by_idD
指定训练计划详情
Inputs: workout_id (required). Returns: result
get_workoutsC
所有训练计划(含摘要)
Inputs: no named parameters. Returns: result
get_workout_templatesC
常用训练计划 JSON 模板库(简单跑/间歇/节奏/力量循环)
Inputs: no named parameters. Returns: result
hr_intradayC
心率日内 — 全天心率采样(抽稀到 24 个小时均值,不撑爆上下文)
Inputs: date. Returns: result
hrvC
心率变异性 (HRV) — 当日 HRV 值及七日均值
Inputs: date. Returns: result
hydrationC
水分摄入 — 当日饮水量
Inputs: date. Returns: result
last_activityC
最后一次活动 — 最近一次运动的摘要
Inputs: no named parameters. Returns: result
personal_recordB
个人记录 (PR) — 各距离最佳成绩
Inputs: no named parameters. Returns: result
race_predictionsC
比赛预测 — 5K/10K/半马/全马预测成绩
Inputs: end, start. Returns: result
respirationC
呼吸频率 — 当日呼吸数据
Inputs: date. Returns: result
resting_hrC
静息心率 — 当日静息心率值
Inputs: date. Returns: result
sleepB
睡眠详情 — 总时长、深睡/浅睡/REM/清醒、评分
Inputs: date. Returns: result
spo2C
血氧饱和度 (SpO2) — 当日血氧数据
Inputs: date. Returns: result
stats_trendA
多日趋势 — 近 N 天步数、睡眠、静息心率、VO2Max、训练状态一览
Inputs: days. Returns: result
steps_dataC
步数详情 — 当日步数明细
Inputs: date. Returns: result
stressC
压力 — 当日压力评分(平均/最高/最低)
Inputs: date. Returns: result
training_readinessD
训练准备度 — 当日身体准备训练的程度
Inputs: date. Returns: result
training_statusC
训练状态 — 训练状态、急慢性负荷比 (ACWR)、月度负荷构成、VO2Max
Inputs: date. Returns: result
user_summaryB
用户每日摘要 — 步数、心率、压力、VO2Max、训练负荷等综合指标
Inputs: date. Returns: result
vo2maxB
最大摄氧量 (VO2Max) — VO2Max 估值(当日无数据时自动回溯最近 7 天)
Inputs: date. Returns: result
weather_atA
查询指定时刻的历史天气实况(温度/湿度/露点/热应激)。 when 格式 'YYYY-MM-DD HH:MM'。 数据来自本地气象日志 + 官方 24 小时实况;官方接口仅回溯 24 小时, 更早的时刻需本地日志已归档过才查得到。
Inputs: when (required), city. Returns: result
weather_forecastA
查询未来天气预报:逐 3 小时(温度/天气/风)+ 每日概况 + 每日最佳训练窗口。 最长 7 天,用于安排本周课表时段、避开降雨与高温。 预报不含湿度,湿热季的精确配速修正需用 weather_now / weather_at 的实况露点。
Inputs: city, days. Returns: result
weather_logA
把过去 24 小时逐小时实况归档到本地气象日志,供日后回溯训练当时的气候。 官方只保留 24 小时,因此建议每天至少调用一次(尤其在复盘晨跑之前)。
Inputs: city. Returns: result
weather_nowA
查询实时天气实况,并给出跑步热应激评估与配速衰减比例。 含温度、湿度、露点、WBGT、风、气压、能见度、AQI。 信源为中国气象局公共气象服务中心(中国天气网)。city 支持城市名或 9 位城市码。 出门前判断今天能否按计划配速执行,用这个。
Inputs: city. Returns: result
weather_paceA
温湿度与配速的换算器。 mode='adjust' :把凉爽条件下的目标配速,换算成当前湿热环境应跑的配速; mode='normalize':把湿热天实跑配速,折算回凉爽标准条件的等效配速(评价完成度用)。 pace 支持 4'35" / 4:35 / 275(秒)。
Inputs: pace (required), temp_c (required), humidity (required), mode. Returns: result
weightC
体重 — 指定日期范围内的体重记录
Inputs: end, start. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 55 tools
Many tools exist for activities (e.g., activities, last_activity, activity_detail, get_activity, get_activity_splits, etc.) and weather (weather_now, weather_forecast, weather_at, etc.), causing confusion. However, descriptions are detailed enough to distinguish most, though some overlap remains (e.g., steps_data vs daily_steps).
Naming is inconsistent: some tools use plain nouns (sleep, stress, weight), others use snake_case with 'get_' prefix (get_hill_score, get_workout_templates), and a few use inconsistent patterns (garmin_weekly_health, garmin_run_conditions). No clear convention across the set.
55 tools is high for a single server, but the domain is broad (health metrics, activities, weather, training). Some tools could be consolidated (e.g., multiple activity detail tools), but the count is borderline appropriate for a comprehensive Garmin data interface.
The server covers a wide range of health metrics, activities, workouts, weather, and training analysis. It lacks write/update tools (e.g., create activity, edit workout) but is thorough for read-only queries. Minor gaps like missing workout creation or editing are acceptable for a data retrieval-focused server.
Maintenance
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Explore Garmin activity and health data with your AI assistant.
Access COROS activity, training and health data, and manage training plans and workouts.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Related MCP Servers
- AlicenseBqualityDmaintenanceConnects to Garmin Connect and exposes fitness and health data via 110+ tools for activities, health metrics, workouts, training analytics, and more to MCP-compatible clients.138MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants to access and manage Garmin Connect data through 95 tools, including real-time activities, metrics, and downloads.-
- AlicenseCqualityBmaintenanceEnables access to Garmin Connect fitness data through 39 fine-grained tools covering body, heart, sleep, stress, activity, steps, hydration, devices, nutrition, goals, and user profile.403MIT
- FlicenseNot gradedqualityCmaintenanceEnables read-only access to Garmin Connect China account data, including activities, splits, sleep summaries, and available training metrics, so users can analyze running volume, laps, recent training, and race preparation through natural language.1-