garmin-connect-mcp：把佳明手表变成 AI 助手的"体检报告生成器"

作者 Nicolasvegam 的 GitHub 头像

一个真实场景

周一早上，你准备出门跑 10 公里。往常你得打开佳明 App，翻菜单看静息心率、体力电量（Body Battery）、昨天的睡眠评分，再自己脑补一句"今天状态还行"。现在你直接对 Claude Code 说一句："看看我最近一周的恢复情况，判断今天该不该加量。"

Claude Code 会调用 garmin-connect-mcp 提供的工具，拉取你的静息心率曲线、HRV、体力电池充放电记录、睡眠分期，再把它整理成一段可读的分析。这就是这个项目存在的全部意义——把腕上那块屏里的数据，变成大模型能"看见"的事实。

项目背景：私有 API 的"翻译官"

佳明没有对外开放的官方 MCP 接入方式，但社区早就摸清了 Connect 的私有接口。这个项目的 API 端点与认证流程直接参考了 Python 社区的 python-garminconnect（作者 cyberjunky），并用 TypeScript 重写，包装成标准 MCP 服务。

作者 Nicolasvegam 在 2026 年 2 月 15 日建仓，起步版本 1.0.0，2026 年 10 月已迭代到 1.2.0，GitHub 187 stars / 97 forks，npm 上近 30 天下载 781 次。数字不算惊人，但 forks 比例超过 50%，说明用户更愿意把它接进自己的环境而不是只收藏——对一个工具型 MCP 来说，这是健康的信号。

类比：给 AI 装上"运动健康手环"

如果说 MCP 是给 AI 装上了手和眼，那这个项目就是给 AI 装上了一根运动手环。平时 AI 看不见你的静息心率是 62 还是 71，也读不出你昨晚深睡只有 40 分钟。装上之后，AI 的建议终于有了你自己的数据作为依据，而不是泛泛而谈的"注意休息"。

需要强调的是：它本身不含任何 AI 模型。它是一个纯数据通道，把佳明的私有 REST 接口翻译成 MCP 工具描述，推理完全交给客户端的模型。这种"只做管道不做引擎"的定位，恰恰让它能兼容 Claude Code、Claude Desktop、Cursor、Windsurf 以及任何 MCP 客户端。

核心功能：61 个工具，覆盖七大类

• 活动（12）：列表、按日期区间检索、最近一次活动、分段配速、心率区间时长、力量训练组数（次数×重量）、活动期间天气
• 每日健康（14）：每日汇总、步数与日内分布、静息/最高心率与时序、压力（全程/轻度/中度/高度分档时序）、体力电池充放电事件、呼吸率、血氧（SpO2）、强度分钟、爬楼层、补水、每日事件
• 趋势（4）：按区间/周聚合的步数、压力、强度分钟
• 睡眠（2）：分期、评分、卧床/清醒时间；原始睡眠含心率与血氧
• 身体成分（5）：体重、BMI、体脂率、肌肉量、称重记录、血压
• 表现与训练（11）：VO2 Max、训练准备度、训练状态与负荷、HRV、耐力分、爬坡分、5K/10K/半马/全马成绩预测、健身年龄、个人记录、乳酸阈值、骑行 FTP
• 资料与设备（13）：社交资料、单位设置、已注册设备与设置、最后使用设备、主训练设备、太阳能充电数据、装备与使用统计、目标、徽章、训练课程

写工具（write.tools.ts）还支持少量回写类操作，是少数能"改数据"而不只是"读数据"的工具集。

值得单独一提的是 get_race_predictions 和 get_lactate_threshold——前者基于 VO2 Max 反推比赛成绩，后者给出阈值心率与配速，属于把消费级手表数据往竞技训练方向推的实用功能。

上手门槛：CLI 与 WebUI 的差别

这个项目没有 Web UI，只有 stdio MCP 服务。安装方式极简，四种主流客户端都只需改一段配置：

claude mcp add garmin -e GARMIN_EMAIL=you@email.com -e GARMIN_PASSWORD=*** -- npx -y @nicolasvegam/garmin-connect-mcp

Cursor 加 .cursor/mcp.json，Claude Desktop 加 claude_desktop_config.json，Windsurf 加 ~/.codeium/windsurf/mcp_config.json，结构完全一致。核心依赖只有 6 个：@modelcontextprotocol/sdk、axios、axios-cookiejar-support、oauth-1.0a、tough-cookie、zod。

真正的门槛在认证：走的是佳明 SSO + OAuth1/OAuth2 双段流程，代码里模拟了 Android 客户端的 User-Agent，硬编码了 SSO embed/signin 端点、Consumer Key 从 thegarth.s3.amazonaws.com 动态拉取，并处理了 token 过期缓冲（60 秒）与最多 3 次重试。如果账号开了 MFA（带 ECG 功能的设备强制要求），必须先跑一次交互式 setup：

GARMIN_EMAIL='...' GARMIN_PASSWORD='...' npx -y @nicolasvegam/garmin-connect-mcp setup

setup 会在终端提示输入验证码，并把 OAuth token 缓存到 ~/.garmin-mcp/，之后 MCP 服务直接复用，token 过期再跑一次即可。这里也埋着最大的风险：密码与 token 都落在本地磁盘上，且依赖的是私有接口，佳明一次风控调整就可能让整套认证失效。

争议与局限

1. 私有 API 的本质脆弱性。整个项目建立在佳明未公开的接口上，认证流程是逆向分析的结果。作者在代码里反复硬编码端点与 UA，一旦佳明加签名校验或改 SSO 流程，客户端会直接失效。这是这类项目共有的天花板，而非实现质量问题。
2. 明文凭据。密码通过环境变量传入，token 以明文 JSON 存在 ~/.garmin-mcp/。多用户或共享机器场景下需要自行加权限管控。
3. 账号风险。模拟移动端 UA 的登录方式在佳明风控眼里未必友善，频繁调用可能触发验证码或限流。
4. 无许可证文件。GitHub API 返回 license: null，仓库根目录也没有 LICENSE 文件，只有 package.json 里写着 MIT，README 末尾也标了 MIT。法律层面的授权声明偏弱，商用前建议确认。
5. 测试是单元级而非集成级。仓库有 vitest 覆盖 client、sso 解析、health 工具、setup 流程，但真实接口联调依然依赖用户的佳明账号，社区无法在 CI 里端到端验证。
6. npm 版本滞后。GitHub 上 package.json 已是 1.2.0，npm registry 的 latest 仍是 1.1.1（1.1.1 发布于 2026-02-15），npx 拉到的并非最新版。

工程实现：值得学习的几点

• 分层清晰：src/tools/（13 个工具注册模块）、src/client/（GarminClient 与认证）、src/dtos/（Zod schema）、src/constants/（端点常量）四层解耦，工具层只做参数校验与结果序列化
• 统一注册模式：每个工具都用 server.registerTool(name, {description, inputSchema}, handler)，输出统一为 content: [{type:'text', text: JSON.stringify(data, null, 2)}]
• CI 三件套：npm ci → build（tsup）→ test（vitest）→ typecheck（tsc --noEmit），PR 与 main push 均触发
• 参数 Schema 复用：dateParamSchema、dateRangeOptionalEndSchema 统一日期语义，工具描述写得相当细致，AI 选工具的准确率会明显受益
• 代码规模克制：主逻辑集中在 garmin.client.ts（25KB）与 garmin-auth.ts（16KB），没有过度抽象

行业意义：垂直领域 MCP 的黄金样本

这个项目是"MCP 化"浪潮的一个标准切片：不是通用工具，而是把一个封闭生态的私有数据，用开放协议暴露给 AI。它证明了两件事——第一，AI 助手的上下文来源正在从"文档/RAG"扩展到"个人实时数据"；第二，长尾垂直生态（运动手环、大疆无人机、智能家居）都存在同样的接入缺口。

从 MCP 生态看，一个 187 stars 的个人项目能覆盖 61 个工具、4 种客户端接入、完整 CI 与单元测试，说明"个人开发者的垂直 MCP 服务"已经成为一种可复制的产品形态。对想给自己的设备做 AI 接入的人，这个仓库是极好的参考模板。

一句话总结

如果你有佳明手表、又天天用 AI 助手，garmin-connect-mcp 是目前把运动健康数据喂给大模型最完整的一条路，61 个工具、5 分钟接入；代价是必须接受私有 API 的脆弱性和明文凭据的信任假设。

数据来源：GitHub API（2026-10-31 采集）、npm registry、仓库源码与 README。