garmin-mcp

与你的 Garmin 数据对话。 一个只读的 MCP 服务器，让 Claude 和 ChatGPT 能够回答关于你训练数据的问题：活动、睡眠、HRV、Body Battery、训练状态、挑战排行榜——而且，与其他 Garmin MCP 服务器不同，还包括你的手表写入的原始 FIT 文件，其中包含 Connect-IQ 传感器通道（Stryd、Moxy/SmO2、CORE）。

You:  How did my last long run compare to the same route in June?
You:  Why is my training readiness so low this morning?
You:  Where do I stand in the running challenge, and who is ahead of me?
You:  Did my Stryd actually record power on Tuesday's session?

它从不写入 Garmin Connect。每个工具都是只读的。

三种使用方式

1. 访客访问——唯一完全不需要基础设施的途径：打开邀请链接、创建账户、连接你的 Garmin，完成。与方式 3 一样，它适用于浏览器中的 claude.ai 和 ChatGPT——方式 2 不行，因为这两者都无法在你的电脑上启动程序。

访客访问尚未开放。 目前仅通过个人邀请向一小群测试者开放。计划提供公开的邀请申请方式——在那之前，方式 2 和 3 今天就可以使用。

2. 本地——没有任何数据离开你的机器，无需账户，无需服务器。你的 AI 客户端在需要时启动该进程。如果你本来就在使用 Claude Desktop 或 Claude Code，并且希望一切保持本地化，这是最佳选择。

3. 你自己的服务器——与访客访问背后相同的软件。为你自己运行，邀请任何你想邀请的人，拥有数据。参见 docs/self-hosting.md。

快速开始（本地）

uv tool install git+https://github.com/mskerwiderski/mcp-garmin

garmin-mcp login

登录时要求输入你的 Garmin 邮箱、密码，以及——如果你启用了——多因素验证码。它只存储 Garmin 的 OAuth 令牌，存放在 ~/.garmin-mcp/tokens.json 中，权限为 0600。你的密码永远不会被写入任何地方。

然后向你的客户端注册服务器：

claude mcp add garmin -- garmin-mcp serve

开启一个新会话并提问。完整的分步指南，包括 Claude Desktop：docs/install-claude.md。

文档

它能回答什么

活动——按运动和日期列出和筛选，Garmin 对单个活动的摘要，以及设备记录的同一活动，直接来自 FIT 文件。文件中任何通道的时间序列、池泳详情精确到单趟长度，以及哪些 Connect-IQ 传感器实际提供了数据。

健康——每天一次调用即可获得步数、静息心率、压力、Body Battery、带评分的睡眠阶段、HRV 状态和训练准备度。此外还有带负荷重点和 VO2max 的训练状态、身体成分和血压（按日期范围）。

趋势与计划——一次调用获取整整一个月的步数、Body Battery 和 VO2max，而不是每天一次；Garmin 的计划侧，包括训练计划锻炼和比赛，因此可以比较"计划了什么"和"实际发生了什么"。

你的位置——5 公里到马拉松的比赛预测、体能年龄、耐力和爬坡得分、终身总计，以及你的个人纪录和创造每项纪录的活动。

背景信息——你的阈值和心率区间、你的装备及其背后的活动、公里数、小时数和天数，以及你与朋友比拼的社交挑战，包括当前正在进行的挑战。

完整列表及参数参见 docs/tools.md。

为什么登录发生在你的机器上

Garmin 的 SSO 位于 Cloudflare 之后，自 2026 年 3 月起，Cloudflare 对来自数据中心 IP 的新登录以 429 或 403 响应。因此 garmin-mcp login 在你所在的位置运行。生成的 OAuth1 令牌有效期约为一年，并针对 connectapi.garmin.com 铸造访问令牌，因此登录之后不会再触及 sso.garmin.com。

托管服务器提供两种方式：登录表单（密码只使用一次，从不存储）以及粘贴来自 garmin-mcp export 的令牌块——当 Garmin 阻止服务器地址时，这是进入的方式。

须知

这使用 Garmin 的内部 Connect API——所有社区工具使用的同一个 API。没有面向个人的官方 API；Garmin 的 Health API 是合作伙伴计划。请仅将此用于你自己的账户，并将托管实例限制在你真正认识的人范围内：一台服务器上的所有账户对 Garmin 共享同一个地址。

响应刻意保持精简。Garmin 对每个活动返回数百个字段，时间序列有数千个点；所有内容都被投影到模型实际能使用的程度，流数据按通道以最小值/最大值/平均值重新采样。这不是装饰性的——原始负载会吞噬对话所需的上下文窗口。

开发

python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"

.venv/bin/pytest

103 个测试，无需网络访问——Garmin API 和 FIT 文件均被桩替换或合成。各部分的组合方式参见 docs/architecture.md。

许可证

MIT。参见 LICENSE。