garmin-mcp

面向 Garmin Connect 的远程 MCP 服务器，部署在 Cloudflare Workers（免费套餐）上。完整 TypeScript 移植自 taxuspt/garmin_mcp：全部 138 个工具，外加一个 garmin_get 透传工具（共 139 个），以及 5 个训练模板/参考 MCP 资源。

模块：活动管理（21）、健康与养生（29）、训练与表现（15）、 训练计划与构建器（19）、营养（14）、挑战/设备/装备（18）、体重/身体/女性 健康/路线（14）、FIT 文件分析（4）、用户资料（4）、透传（1）。

认证：该服务器是一个 OAuth 2.1 授权服务器（通过 @cloudflare/workers-oauth-provider）。 将其添加到 MCP 客户端后，会打开一个浏览器页面，你需要在其中输入你的 Garmin 邮箱和密码 （如果你的账户启用了 2FA，还需输入 MFA 验证码）。Worker 在服务端运行 Garmin 的 SSO 网页组件登录流程 ——这是唯一不会被数据中心 IP 触发机器人拦截的登录路径——获取一个长期有效（约 1 年）的 OAuth1 令牌，丢弃你的凭据，并且只将该令牌 加密存储在授权授权记录中。随后，它按需为 connectapi.garmin.com 铸造短期有效的 OAuth2 承载令牌。一个"粘贴令牌"的备用方案（通过下面的本地脚本）隐藏在 一个详情折叠面板后面，以防 Garmin 将来开始阻止服务端登录。

部署

1. npm install

2. npx wrangler kv namespace create OAUTH_KV — 将返回的 id 粘贴到 wrangler.jsonc 中

3. npx wrangler deploy

Related MCP server: Garmin Open MCP

连接客户端

claude mcp add garmin --transport http https://garmin-mcp.<your-subdomain>.workers.dev/mcp

Claude Code 会在你的浏览器中打开授权页面；按照其两个步骤操作。claude.ai 网页版： 设置 → 连接器 → 使用相同 URL 添加自定义连接器。Claude Desktop 和其他仅支持 stdio 的客户端：mcp-remote 同样处理 OAuth 流程。

访问仅限 OAuth——没有原始请求头路径。每个 /mcp 请求都以 提供商签发的访问令牌为门槛，而访问令牌只能通过完成登录流程来铸造。

锁定到自己的账户

在 wrangler.jsonc 中设置 OWNER_GARMIN_IDS 为你的 Garmin displayName（即 get_user_profile 返回的值）——一个逗号分隔的允许列表。任何不在列表中的 Garmin 账户登录 都会在授权步骤被拒绝，因此即使陌生人拥有自己有效的 Garmin 凭据，也无法使用你的部署。留空则允许任何 Garmin 账户。

与原版的差异（远程/无服务器适配）

• download_activity_file 直接返回文件内容（fit 为 base64，gpx/tcx/csv 为文本，有大小上限），而不是写入本地磁盘；set_fit_download_dir 是一个有文档说明的空操作。

• upload_course 接受 gpx_content（GPX XML 文本）而不是本地文件路径。

• get_activity_fit_data 涵盖 session/laps/records 以及功率分析（NP、VI、功率曲线、W/kg）；原版的 Di2 换挡、爬坡检测和 HRV 分析功能未移植。

• 免费套餐子请求预算（约 50 次/调用）：get_training_load_trend 上限为 45 天（原为 90），get_power_duration_curve 上限为 15 项活动（原为 20），get_hrv_trend 使用范围端点一次调用完成，目标/步数/经期分页循环设有上限。

• 工具返回 JSON 对象而非预序列化字符串；错误以 MCP 工具错误的形式呈现。

备注

• Garmin 令牌以加密形式存储在 Workers KV 的授权记录中；当它过期（约 1 年）时，工具调用开始失败——在客户端中重新认证服务器即可再次运行该流程。

• 访问令牌是承载凭据：任何持有有效令牌的人都可以访问你的数据，直到其过期，因此安全性取决于你的 MCP 客户端是否妥善保管其存储的令牌。

• 本地开发：运行 npm run dev，然后将客户端指向 http://localhost:8787/mcp。