内容
# Garmin MCP
一款模型上下文协议（MCP）服务器，暴露您的Garmin Connect数据（步数、睡眠、心率、心率变异性、压力、身体电池、活动、训练准备度、身体成分）给任何兼容MCP的客户端。
使用 [FastMCP](https://gofastmcp.com) 和 [python-garminconnect](https://github.com/cyberjunky/python-garminconnect) 构建。通过HTTP与 bearer-token 认证运行 — 准备好部署到 Render。
## 工具列表
| 工具 | 返回内容 |
| --- | --- |
| `get_user_profile` | 显示名称、完整名称、单位系统 |
| `get_daily_stats` | 步数、卡路里、静息心率、压力、身体电池、强度分钟 |
| `get_steps_intraday` | 每天的分桶步数样本 |
| `get_daily_steps` | 日期范围内的每日总步数 |
| `get_heart_rates` | 心率样本 + 静息心率 |
| `get_sleep_data` | 阶段、分数、SpO2、心率变异性、呼吸 |
| `get_stress_data` | 压力水平、休息 vs. 活动时长 |
| `get_body_battery` | 身体电池值 |
| `get_body_composition` | 体重、BMI、身体脂肪、肌肉质量 |
| `get_floors` | 上升/下降的楼层数 |
| `get_hrv_data` | 夜间心率变异性 |
| `get_training_readiness` | 训练准备度分数 |
| `get_recent_activities` | 最近的活动 |
| `get_activities_by_date` | 日期范围内的活动，可选类型过滤 |
| `get_last_n_days_summary` | 最近N天的每日统计 |
## 本地开发（macOS / Linux）
```bash
pip install -r requirements.txt
cp .env.example .env
# 填写 GARMIN_EMAIL, GARMIN_PASSWORD, MCP_BEARER_TOKEN
set -a && source .env && set +a
python server.py
```
## 本地开发（Windows / PowerShell）
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# 为此 PowerShell 会话设置凭证
$env:GARMIN_EMAIL = "you@example.com"
$env:GARMIN_PASSWORD = "your-garmin-password"
$env:MCP_BEARER_TOKEN = "a-long-random-string" # 可选
python server.py
```
如果 `Activate.ps1` 被阻止，请运行一次：
`Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.
要从 `.env` 文件加载变量而不是内联设置：
```powershell
Copy-Item .env.example .env # 然后编辑 .env
Get-Content .env | Where-Object { $_ -match '^\s*[^#].+=' } | ForEach-Object {
$name, $value = $_ -split '=', 2
Set-Item "Env:$($name.Trim())" $value.Trim()
}
```
令牌缓存路径是操作系统感知的（它位于您的 Windows 临时目录中），因此不需要额外的配置。如果您想让令牌持久化到某个永久位置，可以使用 `GARMINTOKENS` 环境变量覆盖它。
## 验证它是否正在运行
访问 `http://localhost:8000/mcp` 以确认服务器正在响应（您将获得一个 4xx 状态码 — 这是预期的；MCP 客户端执行 POST/SSE）。
## 部署到 Render
[](https://render.com/deploy?repo=https://github.com/nmldias/GARMIN-MCP)
单击部署 `render.yaml` 蓝图 — Render 然后提示您输入以下环境变量。或者手动执行：
1. 将此仓库推送到 GitHub。
2. 在 [render.com](https://render.com)：**新建 → Web 服务 → 连接 GitHub → 选择此仓库**。Render 自动检测 `render.yaml`.
3. 在环境选项卡中，填写：
- `GARMIN_EMAIL`
- `GARMIN_PASSWORD`
- `GARMINTOKENS_BASE64` （仅当您的帐户启用 MFA 时 — 请参见下文）
- `MCP_BEARER_TOKEN` 是自动生成的；从仪表板复制它。
4. 部署。当构建为绿色时，您的 URL 为 `https://<service>.onrender.com/mcp`.
### 处理 MFA
服务器非交互式运行，因此无法提示 MFA 代码。本地启动令牌：
```bash
pip install garminconnect
python bootstrap_tokens.py
# 输入电子邮件 + 密码 + MFA 代码
# 将打印的 GARMINTOKENS_BASE64 字符串复制到 Render
```
Garmin OAuth 刷新令牌有效期约为 1 年 — 设置一次并忘记。
## 连接 MCP 客户端
将服务器作为自定义连接器添加到任何兼容 MCP 的客户端：
- **网址**: `https://<service>.onrender.com/mcp`
- **名称**: `Garmin`
- **身份验证**: Bearer 令牌 → 使用 `MCP_BEARER_TOKEN`
启用连接器以使用工具。
## 安全说明
- `MCP_BEARER_TOKEN` 是互联网和您的 Garmin 数据之间的唯一凭证 — 生成一个长随机值，如果泄露，请旋转。
- Garmin 凭证存储在环境变量中，从不写入仓库。
- 令牌缓存位于服务器下的 `/tmp/.garminconnect`；Render 的文件系统是短暂的，因此服务器在实例生命周期内重用缓存令牌，并在冷启动时从 `GARMINTOKENS_BASE64` 重新启动。
