Garmin China MCP

Garmin Connect 中国区 MCP 服务器 — 55 个工具，覆盖训练数据、恢复指标、天气热应激评估与健康聚合。

适配 WorkBuddy、Claude Desktop 等任意支持 MCP（Model Context Protocol）的客户端。

安装

pip install garmin-china

或使用 uv（推荐）：

uv pip install garmin-china

认证

首次使用需登录 Garmin Connect 中国区获取 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 保存到 ~/.garmin-china/tokens/。可用 GARMIN_TOKEN_DIR 环境变量覆盖路径。

⚠️ 务必用普通权限终端运行认证。管理员终端会让 token 文件 owner 变成 Administrators，普通进程读不到。

配置 MCP 客户端

WorkBuddy

编辑 ~/.workbuddy/mcp.json（注意不是 .mcp.json）：

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-china",
      "disabled": false
    }
  }
}

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-china"
    }
  }
}

使用 uvx（无需安装）

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": ["garmin-china"]
    }
  }
}

配置后重启客户端，在连接器管理中信任 garmin 服务器即可。

工具列表（55 个）

训练与活动（20）

activities / last_activity / get_activity — 活动列表与详情
activity_splits / activity_split_summaries / activity_typed_splits — 分段数据
activity_hr_in_timezones / get_activity_gear — 心率时区与装备
count_activities / get_activity_types — 统计与类型
download_workout / get_workouts / get_workout_templates — 训练计划
get_activity_weather / get_activity_exercise_sets — 天气与组数
steps_data / daily_steps / get_weekly_steps — 步数
get_activities_fordate — 按日期查活动

恢复与健康（18）

user_summary / daily_summary — 每日摘要
sleep — 睡眠分析
hrv / hr_intraday / resting_hr — 心率变异性与心率
body_battery — 身体电量
stress / get_weekly_stress — 压力
spo2 / respiration — 血氧与呼吸
hydration — 补水
weight — 体重
training_status / training_readiness — 训练状态与准备
vo2max / race_predictions — 最大摄氧量与比赛预测
get_goals / personal_record — 目标与个人记录
endurance_score / hill_score / lactate_threshold / get_fitness_age — 体能指标

周报与趋势（10）

weekly_health / stats_trend / progress_summary — 周报与趋势
weekly_intensity_minutes — 周强度分钟
user_summary / garmin_weekly_health — 健康聚合

天气与热应激（7）

weather_now — 实时天气 + 跑步热应激评估 + 配速衰减
weather_forecast — 逐小时预报
weather_at — 指定时刻历史实况
weather_log — 气象日志归档（24h 回溯）
weather_pace — 配速热修正计算器
garmin_run_conditions — 跑步与气候合并评价（含等效配速）
garmin_weekly_health — 周健康聚合

天气日志归档（可选）

官方逐小时实况只回溯 24 小时。注册 Windows 计划任务自动归档：

garmin-china-weather --install    # 注册（每 6 小时归档一次）
garmin-china-weather --uninstall  # 卸载

日志保存到 ~/.garmin-china/weather-log/。

自检

garmin-china-selftest            # 检查协议与工具注册
garmin-china-selftest --call     # 额外调用真实数据验证

红线

不要升级 garminconnect 到 0.3.x — 中国区 DI token 会全部失败。已锁定 0.2.40。
认证须用普通权限终端 — 管理员终端会导致 token 文件权限问题。
仅支持 Garmin 中国区（garmin.cn）— 不适用于国际版 Garmin Connect。

技术栈

Python ≥ 3.11
garminconnect 0.2.40 + garth 0.6.3（OAuth 认证）
mcp ≥ 1.29.0（Model Context Protocol）
天气数据源：中国气象局公共气象服务中心（weather.com.cn）

License

MIT

garmin-china