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 Connect China MCP Server

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 Reports & Trends (10)

• 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