Garmin MCP

中文 | English

把 佳明（Garmin Connect） 的训练与健康数据接进你的 AI 助手，让它直接回答 「我这个月跑了多少」「分析一下我昨天那次跑步」「我最近是不是练过量了」「我昨晚睡得怎么样」。

只读。不会修改或删除你的任何记录，也永远不接触你的账号密码。 国区（connect.garmin.cn）和国际版（connect.garmin.com）都支持。

你：我上周跑得怎么样
AI：（调用 get_period_stats + list_activities）上周 3 次共 17.8 km，平均配速 6'37"，比前一周少 12%…

它能做什么

图表是服务端直接生成的 PNG，跑友不需要装浏览器自动化之类的东西。

Related MCP server: garmin-mcp

数据来自哪

支持哪些客户端

同一份代码，五个客户端都能接——区别只在「配置文件写在哪」。

每个客户端的图文步骤见 docs/。

快速开始

方式一：一键脚本（推荐）

git clone https://github.com/hongshunanhai/garmin-mcp.git
cd garmin-mcp
./install.sh

脚本会自动完成四件事：

[1/4] 找 Python（3.11+）
[2/4] 建 .venv 并装依赖（mcp / websockets / pillow，不污染系统）
[3/4] 弹出登录窗口 → 你正常登录一次
[4/4] 自动检测并写入各客户端配置

想只配某一个客户端 / 用国际版账号：

./install.sh --client=claude
./install.sh --site=global
./install.sh --client=codex --no-login

macOS 用户也可以直接双击 install.command。

方式二：手动配置

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
./.venv/bin/python garmin_mcp.py login     # 弹窗登录

然后把这两行填进你客户端的 MCP 配置（路径换成你的实际路径）：

{
  "mcpServers": {
    "garmin": {
      "command": "/绝对路径/garmin-mcp/.venv/bin/python",
      "args": ["/绝对路径/garmin-mcp/garmin_mcp.py"]
    }
  }
}

登录是怎么工作的

佳明和大多数国内运动 App 不一样，有三个坑：

1. 关键 Cookie 全是 HttpOnly（session / JWT_WEB / SESSIONID）——document.cookie 读不到；

2. 每个请求还要带 Connect-Csrf-Token（页面 <meta name="csrf-token">）和 Sec-Fetch-Site: same-origin，缺一个直接 403；

3. 会话只有 约 2 小时，但可以静默续期。

所以登录是这样做的：

python3 garmin_mcp.py login
  → 先弹一个本地小页面：「你的佳明账号在哪个站点？」
        [ 佳明中国 ]  connect.garmin.cn   +86 手机号
        [ Garmin 国际版 ]  connect.garmin.com  邮箱 / 非 +86
  → 你点一下，随后起一个独立 Chrome 窗口（自己的 profile，不动你日常浏览器）
  → 打开对应站点的 SSO 登录页（国区是中文页，国际版是英文页）
  → 你自己输 邮箱/手机号 + 密码 + 验证码
  → 工具通过 Chrome DevTools 协议读 HttpOnly Cookie（Storage.getCookies）
  → 顺便读 <meta name="csrf-token">
  → 校验通过后写入 ~/.garmin-mcp/session.json（权限 600）

第一次调用任意工具时如果没登录，也会走这个流程（选站点 → 登录窗口 → 自动继续刚才那次调用）。

之后：

• 自动续期：每次调用前检查有效期，快过期就 POST /modern/di-oauth/refreshToken 静默换新 Cookie（佳明的续期凭据是一次性的，工具会立刻落盘，不用你管）

• 掉线兜底：真过期了，工具会自动弹出登录窗口让你重新登录（多数情况 SSO Cookie 还在，点一下「Sign In」就进去了）

• 换账号：python3 garmin_mcp.py logout 后再 login

账号密码全程只输入给佳明自己的登录页，本工具只保存登录后的会话 Cookie， 而且只在你的机器上。

国区 / 国际版

两站部署的是同一份前端代码，接口路径完全一致，只有域名和 SSO 不同：

工具会记住你登录的站点，之后所有请求自动走对应的域名；换站点用 logout 再 login。

提供的工具（24 个；默认只读，写操作需显式开启）

核心数据

训练与装备

社交与成就

其它

写操作（默认关闭，见下一节）

明确没有封装：上传 FIT、删除活动、改标题、发评论等其它写操作。

创建课表并推到手表（可选，默认关闭）

这个能力会修改你的账号数据，所以分成两条通道：

日常用页面就够了；只有想让 AI 在对话里「说完就建」时才需要开开关：

export GARMIN_ALLOW_WRITE=1        # 或在客户端配置的 env 里加

创建课表默认不是“直接写”，而是弹一个页面给你确认：AI 把你说的计划翻译成课表， 本地打开一个仿佳明的编辑器（热身/跑步/恢复/缓和 + 重复组，可以改距离、配速、组数）， 你点「创建到佳明」才真正写入，页面上还能顺手排期、发送到设备。

你：帮我建一个热身 1.5 公里 7:30-8:00，然后 1 公里 5:00-5:30 快跑 + 1 公里 7:30-8:00 慢跑，重复 3 组
AI：（打开本地编辑器）
    热身 1.50 公里 @ 7'30"-8'00"
      重复 3 组：
        快跑 1.00 公里 @ 5'00"-5'30"
        慢跑恢复 1.00 公里 @ 7'30"-8'00"
    总距离 7.50 km · 预计 0:50:38
你：（点「创建到佳明」）
AI：已创建，id 38177913 → 在 Garmin 打开

页面上可以直接改：距离、时长、配速区间、重复次数、增删步骤；右边实时算总距离和预计时长。

设 GARMIN_WORKOUT_EDITOR=0 可以关掉页面，退回纯 JSON 的 dry-run。

纯命令行/脚本场景（以「4×800 米间歇」为例）：

1) create_workout  → 预览
   {"name":"800米间歇 4组","steps":[
      {"type":"warmup","duration_min":10},
      {"type":"repeat","times":4,"steps":[
         {"type":"interval","distance_m":800,"pace":"5:00"},
         {"type":"recovery","duration_min":2}]},
      {"type":"cooldown","duration_min":10}]}
   →  热身 10 分钟 / 重复 4 组: 快跑 800 米 @ 4'54"-5'04" / 慢跑恢复 2 分钟 / 缓和 10 分钟

2) 确认后 create_workout 加 confirm=true → 返回 workout_id

3) schedule_workout(workout_id, "2026-11-10", confirm=true)   排到下周二

4) push_workout_to_device(confirm=true)                       发送到设备
   → 手表下次和手机同步时收到这节课

支持的目标：

单值自动 ±5 秒是为了兼容佳明「配速目标必须是一个区间」的限制； 想要严格到时秒就显式写 pace_range。 支持的运动：run / bike / swim。

⚠️ 两点务必知道：

1. 写接口我只在网页代码里见过，没在你账号上真调过（为了不污染数据）。第一次请先 dry-run 看 JSON，再用 confirm=true 建一节测试课表，确认手表上显示正常后删掉。

2. 课表一旦排期并下发，手表会按它提示你训练；建错请立刻 delete_workout。

手机 / 多端使用（HTTP 模式）

默认是 stdio（只给本机客户端用）。想让手机也能连，用 HTTP 模式：

# 只监听本机（本机调试用，不需要 token）
./.venv/bin/python garmin_mcp.py --http --port 8765

# 对外提供服务（必须带 token）
./.venv/bin/python garmin_mcp.py --http --host 0.0.0.0 --port 8765 \
    --token "$(openssl rand -hex 16)" --readonly

客户端填：URL = http://<host>:8765/mcp，Header Authorization: Bearer <token>。

远程模式的三个差异（避免手机端体验错位）：

1. 不会弹「选站点」页，也不会弹课表编辑器 —— 这些窗口只会开在服务器屏幕上

2. 登录必须在有浏览器的本机完成，然后把 ~/.garmin-mcp/session.json 复制到服务器

3. 会话续期由服务器进程负责；如果续期失败，把新的 session.json 再拷一次

部署到一台常开的服务器

# 1. 本机先登录
./.venv/bin/python garmin_mcp.py login

# 2. 传代码和凭据
rsync -av --exclude .venv ./ user@server:/opt/garmin-mcp/
scp ~/.garmin-mcp/session.json user@server:/home/user/.garmin-mcp/session.json

# 3. 服务器上装依赖并启动
ssh user@server
cd /opt/garmin-mcp && python3 -m venv .venv && ./.venv/bin/pip install -r requirements.txt
./.venv/bin/python garmin_mcp.py --http --port 8765 --token <token> --readonly

建议用 systemd 常驻，并在前面加一层 HTTPS（Caddy / Nginx 反代，或 Cloudflare Tunnel）： 大部分手机端 App 只接受 https:// 的 MCP 地址。

给 AI / 搜索引擎看的摘要

仓库根目录有 llms.txt，用一段话说明了这个项目是什么、怎么装、能干什么， 方便 AI 助手和搜索引擎直接引用。

许可证（重要）

本项目采用 PolyForm Noncommercial License 1.0.0 —— 你可以：

• ✅ 自己用、改、分享给朋友

• ✅ 用于个人学习、业余爱好、跑步训练

• ✅ 学校、慈善机构、公益组织、政府机构使用

但不可以：

• ❌ 拿去卖钱（收费安装、付费托管、卖服务）

• ❌ 用在商业产品里（公司内部生产环境也算）

一句话：随便用，别赚钱。 需要商用请联系我单独授权。

注意：这不是 OSI 认可的开源协议，属于 source-available（源码可用）。 如果你 Fork 或分发，需要保留 LICENSE 里的 Required Notice 一行。

隐私

数据的流向要说清楚：

你的机器 ──请求──▶ connect.garmin.cn / .com（佳明官方服务器）
   │
   └──工具返回的训练数据/图表──▶ 你使用的 AI 客户端 ──▶ 模型服务商

也就是说：本工具本身不经过任何第三方服务器，但工具返回的数据会进入你所用 AI 客户端的对话。 如果你用的是云端模型（DeepSeek、Claude、GPT 等），这部分数据会按该服务商的条款被提交处理—— 这点和你把跑步数据手动贴进对话框没有区别。

本机保存的东西：

仓库里没有任何用户数据；.gitignore 已排除 .venv/、__pycache__/、.ruff_cache/、session.json、本地 bundle。

常见问题

Q：提示「登录已过期」 A：工具会自己弹窗，跟着登录一次即可；或者终端跑 ./.venv/bin/python garmin_mcp.py login。

Q：Windows / Linux 能用吗？ A：能。工具会自动找 Chrome（macOS / Windows / Linux 的常见路径都覆盖）， 找不到时用兜底：garmin_mcp.py login --manual，按提示粘贴 Cookie。

注意虚拟环境里的解释器路径不同：

Windows 的 install.sh 需要 Git Bash / WSL；没有就用上面的手动配置。

Q：会话老是掉？ A：佳明的续期 token 是一次性的。如果你在浏览器里也登录了同一个账号， 或者在两个客户端里同时用，可能互相顶掉。重新 login 一次即可。 另外登录时勾上 Remember Me 会明显更稳。

Q：会不会把我的数据传出去？ A：本工具自身只请求佳明官方域名，没有任何第三方中转。数据隐私见上面的「隐私」一节。

Q：为什么不用 npx / uvx 分发？ A：单文件 Python + venv，好处是不依赖 Node 生态、跑友机器上只要有个 Python 就能跑。

更多见 docs/troubleshooting.md。

项目结构

garmin-mcp/
├── garmin_mcp.py        # 服务端主文件（登录 + 24 个工具 + 画图）
├── install.sh           # 一键安装器（自动配置 5 个客户端）
├── install.command      # macOS 双击版
├── requirements.txt
├── scripts/
│   ├── smoke_test.py    # CI 用的协议冒烟测试
│   ├── unit_tests.py    # 纯逻辑单测（不联网）
│   └── preflight.sh     # 发布前自检
├── docs/                # 各客户端接入说明 + 排错
├── examples/            # 可直接复制的配置样例
├── dsh-bundle/          # DeepSeek Harness 的 bundle 形式安装包
└── .github/workflows/   # CI：静态检查 + 冒烟测试 + 安装器测试

开发

发布前跑一次自检（推荐）：

./scripts/preflight.sh

它会依次检查：shell 语法、是否有未提交的改动、跟踪文件里有没有 Cookie 或个人绝对路径、 单元测试、MCP 握手。任何一项不过都会以非零码退出。

登录后逐工具自检（推荐先跑这个）：

./.venv/bin/python scripts/live_check.py

输出一张表：每个工具的状态（✅ / ⚠️ 无数据 / ❌ 报错）、耗时和一句摘要； 有 ❌ 时退出码为 1。也支持 --json / --only get_profile,get_gear / --activity <id>。

单独跑某一项：

./.venv/bin/python scripts/unit_tests.py     # 纯逻辑单测（不联网）
./.venv/bin/python scripts/smoke_test.py     # MCP 协议握手 + 工具清单
./.venv/bin/python scripts/installer_test.py # 安装器深测（临时 HOME，5 种形态）
./.venv/bin/python scripts/live_check.py     # 登录后逐工具跑一遍（要账号）
./.venv/bin/ruff check .                     # 静态检查
bash -n install.sh                           # 安装脚本语法

scripts/preflight.sh 会依次跑：shell 语法 → 未提交改动 → 敏感信息（Cookie/JWT/CSRF/SSO） → 单元测试 → MCP 握手 → ruff。CI 在 Ubuntu 和 macOS 上各跑一遍同样的东西。

免责声明

本项目为个人开发的第三方工具，与 Garmin 官方无关，通过公开的网页接口读取你自己账号的数据。 请遵守 Garmin 的服务条款，不要用于批量抓取或商业用途。

License

PolyForm Noncommercial License 1.0.0 —— 仅限非商业使用，详见上方「许可证」章节。