garmin-mcp

garmin-mcp

使用你自己的 Garmin 数据，向 AI 助手询问训练、睡眠和恢复情况。这是一个 MCP 服务，可让 Claude、ChatGPT 和其他助手通过 Garmin 官方的 Personal API 只读访问你的 Garmin Connect 数据。

你可以选择适合自己的运行方式。两种方式提供的工具完全相同：

• 本地。 在你的电脑上运行，由 AI 应用启动。大约 1 分钟即可完成设置，只需要 Garmin 密钥。在 Claude Desktop 中，只需单击一次即可安装。
• 云端。 在你自己的 Cloudflare 账户上运行（免费套餐绰绰有余），并通过 GitHub 登录。大约 20 分钟即可完成设置，之后可在所有设备上使用：网页、桌面和手机。

它适用于 Claude、ChatGPT、Claude Code、Codex、Gemini CLI、Cursor、VS Code 和其他 MCP 客户端。查看本地还是云端？，了解每种方式支持哪些应用。

无论选择哪种方式，你都可以：

• 获取洞察，而非又一张图表。 提出问题，即可获得基于你自身数据的回答。
• 无需密码。 它使用 Garmin 官方 API 密钥，你可以随时撤销，而非使用你的 Garmin 登录凭据。
• 没有中间环节。 数据直接从 Garmin 传输到你的电脑或你自己的 Cloudflare 账户。没有第三方服务会存储数据。
• 始终保持最新。 每次提问时都会从 Garmin 获取数据，无需记得同步。
• 无需额外付费。 它使用你已有的 AI 订阅，云端选项也适用于 Cloudflare 免费套餐。

可以这样提问：

• “我今天适合进行高强度训练吗？”
• “从 5 月以来，我的静息心率和 HRV 有什么变化？”
• “今年每个月的跑步总里程和平均配速是多少？”
• “我的跑步中，轻松跑和高强度跑各占多少？”
• “我在哪个星期几睡得最差？”
• “比较我最近两次长跑。”
• “给我周日比赛的每公里分段成绩。我后半程跑得更快吗？”

下面展示的是手机上的 Claude（云端版本），根据近期跑步记录预测 10 公里成绩：

与 Garmin 没有关联，也未获得 Garmin 的认可。“Garmin”和“Garmin Connect”是 Garmin Ltd. 或其子公司的商标。

本地还是云端？

	本地	云端
Claude Desktop（单击安装）、Claude Code	✅	✅
Codex（CLI，以及 ChatGPT 桌面应用中的 Codex）	✅	✅
Gemini CLI、Cursor、VS Code	✅	✅
ChatGPT 应用：网页、桌面聊天和手机		✅
网页版 Claude		✅
手机或平板上的 AI 应用		✅
电脑关机时仍可使用		✅
大约 1 分钟即可完成设置	✅
无需 Cloudflare 或 GitHub 账户	✅
Garmin 密钥仅存储在你的电脑上	✅
不会有任何程序监听网络	✅
会话之间保留缓存		✅
免费运行	✅	✅
全部 26 个工具和 5 个提示词	✅	✅

还在犹豫？

我在一台电脑上使用 Claude Desktop 或 Claude Code

选本地。大约一分钟即可获得全部功能。在 Claude Desktop 中，只需下载一次：不需要 Node，也不需要配置文件。

我想在跑步后马上用手机提问

选云端。手机应用无法启动本地进程，因此需要一台能通过互联网访问的服务。

我使用 ChatGPT

选云端。ChatGPT 应用本身（网页、桌面聊天和手机应用）只能连接远程 MCP 服务。Codex 是个例外：Codex CLI 和 ChatGPT 桌面应用中的 Codex 可以在本地运行它。

我使用多台电脑

选云端。本地运行意味着要在每台电脑上安装；云端只需设置一次，再将 URL 添加到每个应用中。

我还不确定

从本地开始。如果之后想在手机上使用，再设置云端即可。无需迁移任何内容，因为你的数据始终保留在 Garmin 中。

我可以两种方式都运行吗？

可以。它们可以共用一个 Garmin 密钥。

哪种方式更安全？

两种方式都采用了严格的安全保护，只是方式不同。本地运行无需登录，因为没有可供登录的服务：只有启动它的应用能与它通信，而密钥存放在电脑上该应用的配置中。云端服务可通过互联网访问，因此仅限你的 GitHub 账户使用，密钥则存放在 Cloudflare 机密中。请参阅安全模型。

我需要多熟悉终端操作？

本地运行：粘贴一条命令或一段配置即可。云端运行：大约需要运行十几条命令，并在 Cloudflare 和 GitHub 控制面板中更改几项设置。

本地运行

你的 AI 应用会将服务作为本地进程启动，并直接与之通信。无需设置 Cloudflare 或 GitHub。

你只需要一个 Garmin Personal API 密钥（参见 创建 Garmin Personal API 密钥）。

Claude Desktop：一键安装

1. 下载 garmin-mcp.mcpb。
2. 双击该文件，按提示粘贴 Garmin 密钥，完成。

Claude Desktop 会自行运行扩展，因此你无需安装 Node，也不需要配置文件；密钥会存储在系统钥匙串中。

Claude Code、Cursor、VS Code 和其他应用

这些应用需要 Node 22 或更高版本。无需单独安装任何内容：你的应用会通过 npx 运行 garmin-mcp 软件包。

Claude Code：

claude mcp add garmin --env GARMIN_API_KEY=<your key> -- npx -y garmin-mcp

Cursor、VS Code 和其他应用（或者，如果你不想使用扩展，也可以在 Claude Desktop 中操作）：将以下内容添加到应用的 MCP 配置中：

{
	"mcpServers": {
		"garmin": {
			"command": "npx",
			"args": ["-y", "garmin-mcp"],
			"env": {
				"GARMIN_API_KEY": "<your key>"
			}
		}
	}
}

VS Code 的 mcp.json 使用 "servers"，而不是 "mcpServers"。

Codex

Codex CLI 和 ChatGPT 桌面应用中的 Codex 共用同一份配置。将以下内容添加到 ~/.codex/config.toml（需要 Node 22 或更高版本）：

[mcp_servers.garmin]
command = "npx"
args = ["-y", "garmin-mcp"]
env = { GARMIN_API_KEY = "<your key>" }

Gemini CLI

在 ~/.gemini/settings.json 的 "mcpServers" 下添加以下内容（需要 Node 22 或更高版本）：

"garmin": {
	"command": "npx",
	"args": ["-y", "garmin-mcp"],
	"env": { "GARMIN_API_KEY": "<your key>" }
}

重启应用，然后试着问 “我今天适合训练吗？”。

云端运行

MCP client ──OAuth──▶ Worker (/mcp) ──Bearer JWT──▶ Garmin Personal API
                         │
                         └─ /authorize ──▶ GitHub sign-in ──▶ allowed user ID? ──▶ token

每个人都会将自己的副本部署到自己的 Cloudflare 账户。服务仅限单个 GitHub 账户使用，因此只有你能访问自己的 Garmin 数据。

所需条件

• Garmin Connect 账户和 Garmin 设备
• Cloudflare 账户（免费套餐）
• GitHub 账户
• Node 22 或更高版本
• 大约 20 分钟

所有命令都在仓库文件夹中运行。

1. 安装并登录 Cloudflare

git clone https://github.com/colincooperio/garmin-mcp.git
cd garmin-mcp
npm install
npx wrangler login
cp wrangler.example.jsonc wrangler.jsonc

wrangler.jsonc 已被 git 忽略，因此你的设置不会被提交。

2. 创建 KV 命名空间

npx wrangler kv namespace create OAUTH_KV

将显示的 id 粘贴到 wrangler.jsonc 中，替换 YOUR_KV_NAMESPACE_ID。

3. 将其绑定到你的 GitHub 账号

打开 https://api.github.com/users/<your-github-username> 并复制数字 id。将其填入 wrangler.jsonc，作为 ALLOWED_GITHUB_USER_ID。

这里使用数字 ID 而非用户名，因为用户名可以更改，之后也可能被他人抢注。

4. 确定 Worker 的 URL

URL 格式为 https://garmin-cloud-mcp.<your-subdomain>.workers.dev。你可以在 Cloudflare 控制面板的 Workers & Pages 概览中找到自己的 workers.dev 子域名。

将 wrangler.jsonc 中的 MCP_RESOURCE 设置为该 URL，并在末尾加上 /mcp。

5. 创建 GitHub OAuth 应用

前往 GitHub → Settings → Developer settings → OAuth Apps → New OAuth App，然后填写：

• 主页 URL： https://garmin-cloud-mcp.<your-subdomain>.workers.dev
• 授权回调 URL： https://garmin-cloud-mcp.<your-subdomain>.workers.dev/callback

然后生成客户端密钥。

6. 创建 Garmin Personal API key

前往 Garmin Connect → Personal API Token → Create Key。选择 1 年并复制密钥；Garmin 只会显示一次。

7. 保存密钥

每条命令都会提示你粘贴相应的值。

npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY   # paste output of: openssl rand -hex 32
npx wrangler secret put GARMIN_API_KEY

如果 wrangler 询问是否要先创建 Worker，请选择是。

8. 部署

npm run deploy

部署前会进行类型检查并运行完整测试套件。若有任何失败，就不会发布。测试输出中会有几行带有 expected 标签的错误信息：这些来自用于检查 Worker 是否会拒绝错误请求的测试。

9. 连接你的 AI 应用

你的服务 URL 是 https://garmin-cloud-mcp.<your-subdomain>.workers.dev/mcp。 每个应用首次使用时都会打开 GitHub 登录页面；请登录并授权。

• Claude：前往 Settings → Connectors → Add custom connector，然后粘贴 URL。 该连接器会随你的 Claude 账号同步到所有设备。
• ChatGPT：将其添加为带 OAuth 身份验证的自定义连接器（MCP 服务）。 自定义连接器需要开发者模式，并且取决于你的套餐；当前操作步骤请参阅 OpenAI 的帮助页面。
• Claude Code：运行 claude mcp add --transport http garmin <url>，然后运行 /mcp 登录。
• Cursor、VS Code 和其他 MCP 应用：使用该 URL 添加远程（HTTP）MCP 服务。 支持 MCP OAuth 的应用会自行处理登录。

试试 “我今天适合训练吗？”。在显示 MCP 提示词的应用中，例如 Claude 的连接器菜单，你还可以选择现成的提示词。

为什么选择这个

与基于密码的 Garmin MCP 服务相比

大多数 Garmin MCP 服务都早于 Personal API。它们使用你的 Garmin 邮箱和密码登录，并调用 Garmin Connect 的私有 Web 端点，在你自己的机器上运行。

	基于密码	此服务，本地	此服务，云端
Garmin 访问权限	你的邮箱 + 密码，磁盘上的会话令牌	官方 Personal API 密钥：可撤销，有效期为 30 天至 1 年	与本地相同
Garmin 更改登录或 MFA 后是否会失效	会，经常发生	不会，它使用的是有文档说明的 API	不会
是否可在 Web 和手机应用中使用	否	否	是
如果凭据泄露	整个 Garmin 账户	只读健康数据，直到你删除密钥	与本地相同，而且密钥存放在 Cloudflare 密钥中，而非笔记本电脑上

权衡之处在于：Personal API 覆盖的内容较少。它不提供高尔夫记分卡、 训练计划、Garmin Training Status、比赛预测、装备、球场或写入权限。 MCP 服务会预先告知模型这些限制，因此模型会说明相关内容不可用，而不是四处寻找。

与基础 API 封装相比

每个端点封装成一个工具的方式虽然可行，但速度慢且耗费大量 token： Garmin 每项活动会返回 100 多个字段，心率数据则每两分钟记录一次。此服务会自行完成繁重的处理：

• 一次调用即可回答问题。 get_readiness、summarize_wellness 和 summarize_activities 会在服务中获取、关联并汇总数据。五个月的跑步数据 返回约 1,000 个字符，而不是约 190,000 个字符。
• 默认精简。 使用易读单位、扁平化数据行，并按小时提供心率，而非每次读数。每个工具都有 detail: "full" 选项，可获取原始数据。
• 处理 Garmin 的单次调用限制。 某些端点每次请求只允许查询 28 天或 31 天。更长的时间范围会拆分并并行获取，因此模型只需调用一次，而不必调用四次后再遇到失败。
• 按你的时区解析命名时间段。 last_30_days、this_week、last_month、 today、yesterday 会根据 Garmin 个人资料中的时区解析。
• 时间采用你的本地时间，包括夏令时切换当晚。 Garmin 提供的时间格式包括原始时间戳、GMT 字符串和“本地”值；时钟切换当晚，其本地值会相差一小时。所有时间都会根据准确时刻和个人资料中的时区，或旅行时根据手表的时区，转换为本地的 YYYY-MM-DD HH:MM。
• 支持部分结果。 如果某个数据源失败（例如某晚的 HRV），其余数据仍会返回，并附上一条简短说明，这样模型就不会重试所有内容。
• 缓存。 至少 3 天前的数据已稳定，因此会缓存 7 天；活动详情则缓存一天。活动分析不会变化，因此会无限期缓存（只缓存派生表，不缓存文件）。后续问题无需访问 Garmin。（在本地，缓存会一直保留，直到应用重启服务。）
• 提供 Garmin API 无法直接提供的数据： 每公里／英里分段和最佳成绩（由服务从活动的 FIT 文件中计算，因此两小时的跑步只会返回几 KB 的表格，而非 7,000 个采样点）、训练负荷（急性与慢性负荷比）、心率区间用时（针对单项活动，使用手表记录的当时区间数据，与 Garmin Connect 一致）、每周模式、按距离加权的配速、并排对比活动。
• 提示词模板，适用于支持 MCP 提示词的应用（例如 Claude 的连接器菜单）：今天适合训练吗？、睡眠报告、训练回顾、每周检查、比较近期训练。

工具

所有工具均为只读。时间范围最长可达 92 天（summarize_* 工具最长可达 366 天）。所有范围工具也接受 period 参数，单日工具则接受 today 或 yesterday。对于 summarize_* 工具，只提供 start_date 表示“从该日期起”：范围结束于今天。

从这里开始。 这些工具可通过一次调用和简短响应回答常见问题：

工具	可回答的问题
get_readiness	“我的恢复情况如何？”、“我昨晚睡得怎么样？”：当晚睡眠情况、HRV 与基线的对比、静息心率、Body Battery，各项数据均与此前 7 天对比；训练负荷；最近 3 天的训练情况
summarize_wellness	睡眠、静息心率、HRV、压力、步数和 Body Battery 趋势：按周、月、星期几或整体查看
summarize_activities	训练总计：距离、时长、配速、心率、训练负荷和心率区间时长；按周、月、星期几或整体查看
compare_activities	并排比较 2–5 项活动
get_activity_analysis	基于原始 FIT 文件分析单项活动：每公里或每英里分段、手表记录的圈数和训练重复组、最佳成绩（1 km 至马拉松）、手表记录的心率区间时长、前半程与后半程的漂移

详情。 默认使用精简模式；传入 detail: "full" 可查看 Garmin 的原始数据。

工具	数据
get_daily_summaries	每天一行：步数、卡路里、心率、强度分钟数、压力、Body Battery
get_sleep_summaries / get_sleep	按阶段划分的睡眠时长、评分、心率、呼吸、SpO2、睡眠需求及其影响因素；支持查询一段时间或某一晚
get_hrv_summaries / get_hrv	一段时间内的 HRV，或某一晚的读数
get_body_battery、get_stress、get_steps	一段时间内的每日数据序列（Body Battery 包含当天的关键读数）
get_heart_rate	某一天的每小时心率最低值／平均值／最高值；如果提供了 from/to 时间窗口，还会返回其中的每次读数
get_spo2、get_fitness_age	某一天的详细数据
get_weight、get_weight_goals、get_hydration、get_wellness_activity_summaries	一段时间内的数据
search_activities	单项活动，可按类型、子类型、比赛、距离、时长、爬升、名称和区域筛选，并按距离或速度排序
get_activity、get_activity_workouts	某项活动的详细信息
get_nutrition、get_menstrual_cycle	某一天的详细数据
get_profile	单位、时区和心率区间

这些工具涵盖了 Garmin 的 Personal API 规范中的所有端点， 包括 get_activity_analysis 读取的活动文件下载端点。 我们特意没有提供“GET 任意路径”工具：使用这种工具时，模型会猜测并不存在的 端点，浪费调用次数。

训练负荷

急性负荷与慢性负荷比率，将最近 7 天与过去 28 天的平均每周数据进行比较。 Garmin 自带的 Training Status 不在 Personal API 中，因此 MCP 服务会根据时间窗口内 每项活动可用的最佳指标进行计算，并说明使用了哪项指标：

1. 对于会记录该数据的手表，使用 Garmin 的单项活动训练负荷
2. 对于任何配有心率功能的手表或心率带，使用心率区间负荷（各区间内的分钟数 × 区间编号）
3. 没有心率数据时，使用运动分钟数

整个时间窗口使用同一种指标，因为混用指标会使比率失去意义。请将其作为参考， 而非 Garmin 的官方数值。

维护

轮换 Garmin 密钥。 密钥到期前，Garmin 会给你发送邮件。创建新密钥，然后：

• 本地：在 AI 应用的 MCP 配置中替换 GARMIN_API_KEY，然后重启应用。对于 Claude Code，运行 claude mcp remove garmin 并重新添加。对于 Claude Desktop 扩展，将新密钥粘贴到 Claude Desktop 中该扩展的设置里。
• 云端：运行 npx wrangler secret put GARMIN_API_KEY。更改会立即生效，缓存数据与获取该数据时使用的密钥关联。

然后在 Garmin Connect 中删除旧密钥。

更新。

• Claude Desktop 扩展：从最新版本下载新的 garmin-mcp.mcpb 并双击。
• 本地使用 npx：每次 AI 应用启动服务时，npx 都会获取最新版本，因此只需重启应用。若要固定版本，请在配置中用 [email protected] 替换 garmin-mcp。
• 云端：运行 git pull，然后执行 npm install 和 npm run deploy。更新不会改动你的 wrangler.jsonc。如果 wrangler.example.jsonc 新增了设置，请将其复制过来。

日志。 在本地，服务会将日志记录到 AI 应用的 MCP 日志中。在云端，运行 npm run tail，或在 Cloudflare 控制面板中依次选择 Workers → garmin-cloud-mcp → Logs。日志会记录错误和被拒绝的登录，但不会记录你的 Garmin 数据。

一次性撤销所有访问权限。 在 Garmin Connect 中删除 Garmin 密钥，即可同时停止本地和云端访问。对于云端，你也可以将 ALLOWED_GITHUB_USER_ID 设为 "0"，然后运行 npx wrangler deploy：所有已连接的应用都会在下次请求时被拒绝。

回滚有问题的云端部署。 npx wrangler rollback。

某个值为空？ 某些字段取决于你的设备。再次请求并添加 detail: "full"，即可查看 Garmin 返回的所有内容。如果返回结果中包含该字段，但精简答复中缺少该字段，请提交问题。

安全模型

两种模式

• 只读，路径固定。 每个工具都会通过 GET 请求访问固定的 Garmin 路径。没有任何工具会向 Garmin 写入数据或获取任意 URL。
• 你的数据流向。 Garmin → 你的电脑或你的 Worker → 你的 AI 应用。数据最终会进入你使用这些工具的聊天中，并受相应服务提供商的数据政策约束。

本地

• 不监听网络。 服务通过 stdin 和 stdout 与启动它的应用通信，其他任何程序都无法连接。因此不需要登录。切勿将其包装在 HTTP 代理中或暴露到网络上；如需远程访问，请使用云端版本。
• Garmin 凭据。 密钥存储在电脑上的 AI 应用 MCP 配置中。Bearer token 和缓存的响应保存在内存中，并会在进程退出时清除。

云端

• 只有你能获取令牌。 通过 GitHub 登录后，回调会将 GitHub 的数字用户 ID 与 ALLOWED_GITHUB_USER_ID 进行比较。其他任何人都会在 MCP 令牌创建前收到 403。每个 /mcp 请求都会重新检查 ID，因此修改该值会撤销现有会话。
• 默认拒绝访问。 如果允许的 ID 未设置、为 "0" 或不是数字，则无人可以访问。
• 仅请求最低限度的 GitHub 访问权限。 请求 GitHub 令牌时不指定任何范围，仅使用一次来读取你的用户 ID，随后立即丢弃。
• 标准 OAuth。 通过 @cloudflare/workers-oauth-provider 实现 OAuth 2.1 和 PKCE（S256）、受 CSRF 保护的授权确认，以及绑定到 /mcp 资源的令牌。
• Garmin 凭据。 密钥仅存储在 Cloudflare Secrets 中。有效期为 24 小时的 bearer 令牌会以密钥的哈希值为键缓存在 KV 中，而不会存储密钥本身。过去日期的缓存响应保存在同一 KV 命名空间中，仅位于你的 Cloudflare 账户内，并在 7 天后过期。活动分析（分段和单圈表格，不包括 FIT 文件或 GPS 位置）会无限期保存在那里，因为活动文件不会发生变化。
• 不访问私有地址。 global_fetch_strictly_public 会阻止 Worker 获取私有地址。

发现安全问题？请通过此仓库 GitHub 上的 Security → Report a vulnerability 私下报告，而不要创建 issue。

参与贡献

欢迎提交错误报告和拉取请求；请参阅 CONTRIBUTING.md，了解如何报告问题、运行测试和 发布版本。

已知限制

• 每个云端部署或本地安装仅支持一个 Garmin 账户。 若要与家人共享，每个人都需要使用自己的 Garmin 密钥设置一份副本。
• 仅覆盖个人 API。 不支持高尔夫、训练计划、Garmin Training Status、比赛预测、VO2 max 历史、个人纪录、装备、路线、徽章或社交功能。
• 只读。 无法记录活动、体重、补水或饮食，也无法更改目标、设置或训练内容。Personal API 不提供写入权限，因此你的 AI 应用可以读取 Garmin 数据，但无法对其进行更改。
• 不提供原始活动文件或 GPS 轨迹。 get_activity_analysis 会在服务端读取 FIT 文件，并且仅返回衍生表格；文件、样本和位置数据不会传输到模型。手动录入和 GPX/TCX 导入没有 FIT 数据，因此该工具会说明这一点。
• 未公布速率限制。 Garmin 尚未公布 Personal API 的速率限制。出现 429 时会返回清晰的工具错误。

致谢

OAuth 流程改编自 Cloudflare 的 remote-mcp-github-oauth 演示项目。src/workers-oauth-utils.ts 是从该项目引入的，遵循其 MIT 许可证。

作者

由 Colin Cooper 构建。

许可证

MIT