# Garmin China MCP

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

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

## 安装

```bash
pip install garmin-china
```

或使用 [uv](https://docs.astral.sh/uv/)（推荐）：

```bash
uv pip install garmin-china
```

## 认证

首次使用需登录 Garmin Connect 中国区获取 token：

```bash
# 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`）：

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

### Claude Desktop

编辑 `claude_desktop_config.json`：

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

### 使用 uvx（无需安装）

```json
{
  "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 计划任务自动归档：

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

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

## 自检

```bash
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](https://pypi.org/project/garminconnect/) 0.2.40 + [garth](https://pypi.org/project/garth/) 0.6.3（OAuth 认证）
- [mcp](https://pypi.org/project/mcp/) ≥ 1.29.0（Model Context Protocol）
- 天气数据源：中国气象局公共气象服务中心（weather.com.cn）

## License

MIT