Skip to main content
Glama

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-china

Or use uv (recommended):

uv pip install garmin-china

Related 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-auth

Token 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 details

  • activity_splits / activity_split_summaries / activity_typed_splits — Split data

  • activity_hr_in_timezones / get_activity_gear — Heart rate time zones and gear

  • count_activities / get_activity_types — Statistics and types

  • download_workout / get_workouts / get_workout_templates — Training plans

  • get_activity_weather / get_activity_exercise_sets — Weather and exercise sets

  • steps_data / daily_steps / get_weekly_steps — Steps

  • get_activities_fordate — Query activities by date

Recovery & Health (18)

  • user_summary / daily_summary — Daily summary

  • sleep — Sleep analysis

  • hrv / hr_intraday / resting_hr — Heart rate variability and heart rate

  • body_battery — Body battery

  • stress / get_weekly_stress — Stress

  • spo2 / respiration — Blood oxygen and respiration

  • hydration — Hydration

  • weight — Weight

  • training_status / training_readiness — Training status and readiness

  • vo2max / race_predictions — VO2 max and race predictions

  • get_goals / personal_record — Goals and personal records

  • endurance_score / hill_score / lactate_threshold / get_fitness_age — Fitness metrics

  • weekly_health / stats_trend / progress_summary — Weekly reports and trends

  • weekly_intensity_minutes — Weekly intensity minutes

  • user_summary / garmin_weekly_health — Health aggregation

Weather & Heat Stress (7)

  • weather_now — Real-time weather + running heat stress assessment + pace degradation

  • weather_forecast — Hourly forecast

  • weather_at — Historical conditions at a specified time

  • weather_log — Weather log archive (24-hour retrospective)

  • weather_pace — Pace heat correction calculator

  • garmin_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 tools
activitiesB

活动列表 — 指定日期范围内的活动(跑步/骑行等)

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

    C2.3/5.0

    Scored across 55 tools

    Disambiguation3/5

    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 Consistency2/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Connects 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.
      138
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      Enables 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.
      40
      3
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
      -