Garmin Connect

@dynamicsninja/garminconnect-mcp

通过基于 garminconnect-js 构建的 MCP 服务，与 Claude 对话以创建 Garmin 训练，并读取或管理其他 Garmin Connect 数据。

“给我安排一组 6×400 m 的训练，配速为 5k 配速，间隔慢跑恢复 2 分钟，安排在周四，并发送到我的手表。”

Claude 会预览训练，等待你确认，然后将其保存到 Garmin 训练库、安排训练，并推送到你的设备。

非官方项目：并非由 Garmin 制作，也与 Garmin 无关。

无需安装即可使用

托管版本运行在 https://garmin.ficdev.xyz/mcp。你只需在浏览器窗口中登录一次 Garmin，即可使用相同的工具，无需安装任何内容。

• **claude.ai：**前往 Settings、Connectors、Add custom connector。粘贴 URL，并在打开的窗口中登录 Garmin。随后，它会在同一账户的 Claude Desktop 和移动端中显示。
• Claude Code：claude mcp add --transport http garmin https://garmin.ficdev.xyz/mcp
• **其他 MCP 客户端：**使用该 URL 添加一个 streamable-HTTP 服务。

与本地服务的区别：

• 没有 sign_in_to_garmin 工具。添加连接器时即可登录。
• 上传工具需要 filename 和 content；对于 .fit 文件，还需要 encoding: "base64"。上限为 10 MB。
• 下载内容会返回到聊天中，而不是保存到文件夹。上限为 5 MB。

如需断开连接，请移除连接器。下次登录时，也可以勾选 “Disconnect my other Garmin connections”。隐私详情请参阅 PRIVACY.md。

所需条件

• Node.js 18 或更高版本（运行 node --version 检查）。
• Garmin Connect 账户。
• Claude Desktop，或其他 MCP 客户端（请参阅 其他 MCP 客户端）。

设置

最简单的方法：Claude Desktop Extension

1. 从最新版本下载 garminconnect-mcp-<version>.mcpb。
2. 双击文件（或将其拖到 Claude Desktop 的 Settings → Extensions 中），然后选择 Install。
3. 向 Claude 询问 Garmin 数据相关的问题。首次使用时，Claude 会在浏览器中打开 Garmin 登录页面；请在此登录（如果你启用了 MFA，也需输入 MFA 验证码），然后告诉 Claude 你已完成。

可选设置（工具组、下载文件夹）位于 Settings → Extensions → Garmin Connect 下。

其他安装方式：npm

1. 安装

npm install -g @dynamicsninja/garminconnect-mcp

请只安装一次，不要通过 npx 运行：Claude Desktop 会同时启动同一服务的多个副本，而并行的 npx 安装可能互相影响同一个缓存文件夹，导致故障（ERR_MODULE_NOT_FOUND … ajv/dist/2020.js）。

2. 登录 Garmin

在终端中操作（你的密码不会经过 Claude）：

garminconnect-mcp login

系统会要求你提供 Garmin 邮箱（旧账户也可能使用用户名）、密码，以及 MFA 验证码（如果你启用了 MFA）。会话将保存到 ~/.garminconnect-mcp/tokens，只要每 30 天至少使用一次，就会自动续期。

3. 将其添加到 Claude Desktop

前往 Settings → Developer → Edit Config，并在 claude_desktop_config.json 中添加一个 garmin 条目。 将 node 指向已安装服务。要查找路径，请运行 npm root -g，然后追加 /@dynamicsninja/garminconnect-mcp/dist/cli.js。

Windows（使用正斜杠）：

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["C:/Users/<you>/AppData/Roaming/npm/node_modules/@dynamicsninja/garminconnect-mcp/dist/cli.js"]
    }
  }
}

macOS / Linux：

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/@dynamicsninja/garminconnect-mcp/dist/cli.js"]
    }
  }
}

如果找不到 node 本身（使用 nvm 时很常见），请将 which node 返回的完整路径用作 command。

4. 重启 Claude Desktop

彻底退出应用：点击系统托盘 / 菜单栏图标 → Quit。关闭窗口并不会退出应用，因此它不会读取新的配置。重新启动应用，打开新聊天，Garmin 工具就会显示在消息框的工具图标下方。

使用方法

直接提问即可。可以试试：

• “创建一组力量训练：做 3 轮，每轮包括 10 次 60 kg 杠铃深蹲、12 次俯卧撑和 1 分钟平板支撑，轮间休息 90 s。”
• “为 25 m 泳池制定一组游泳训练：400 m 轻松游，8×100 m 自由泳，每组间休息 15 s，最后 200 m 放松游。”
• “把这组训练安排在周四，并发送到我的手表。”
• “我昨晚睡得怎么样？我今天的训练准备度如何？”
• “总结一下我上次跑步的数据：距离、配速、平均心率和训练效果。”
• “我的比赛成绩预测是多少？这个月我的 HRV 趋势如何？”
• “找出我从 6 月以来距离超过 10 km 的跑步记录，按距离从长到短排列，并比较它们的平均心率。”

训练始终会先显示预览。 Claude 会以易读的形式显示训练内容（步骤、目标、以 /km 和 /mi 为单位的配速），只有在你确认后才会保存。系统会根据 Garmin 的目录检查运动名称；如果训练有误，Claude 会收到错误的具体位置，以便修正。

Claude Desktop 每次调用工具前都会征求许可。 你可以允许工具调用一次，也可以始终允许。删除或覆盖数据的工具（例如删除活动、训练、装备、称重记录等）会标记为有破坏性，Claude 会被要求在使用前先向你确认。

功能

• sign_in_to_garmin：通过在浏览器中打开的页面登录（包括 MFA），无需使用终端。参见上文最简单的方法：Claude Desktop Extension。
• 训练：preview_workout、create_workout、update_workout、search_exercises，适用于跑步、骑行、游泳、力量训练、HIIT、瑜伽、普拉提、灵活性训练、有氧运动、负重徒步和多项运动；还支持列出训练、安排训练、发送到手表和删除训练。
• garminconnect-js 中的其他所有功能：睡眠、HRV、压力、Body Battery、最长可一次获取一年内的全天摘要、训练准备度和状态、比赛成绩预测、活动（列表、按类型、距离、时长、功率、日期、文本或地点搜索，查看详情、已完成的训练、下载、上传文件、RPE 和体感）、装备、路线、比赛日历、设备、徽章、称重记录和体重目标、食物记录（需 Garmin Connect+）等。每个库方法对应一个工具。

未开放的功能： logout（会删除已保存的会话）、原始 JSON 训练上传（已由经过检查的 create_workout 取代），以及原始 GraphQL 透传功能（除非你选择启用）。

设置（环境变量）

变量	默认值	含义
GARMIN_MCP_TOKEN_DIR	~/.garminconnect-mcp/tokens	保存会话的位置
GARMIN_MCP_DOWNLOAD_DIR	~/Downloads/garmin	下载文件（FIT、GPX、…）的存放位置
GARMIN_MCP_GROUPS	all	以逗号分隔的工具组：wellness、activities、metrics、workouts、gear、courses、calendar-events、devices、badges-challenges、body-composition-weight、womens-health、golf、profile-and-misc。匹配时不区分大小写；未知名称会被忽略（如果你列出的名称均无效，则会加载所有工具）。训练构建工具始终启用。工具组越少，占用 Claude 的上下文就越少。
GARMIN_MCP_ENABLE_GRAPHQL	off	设置为 1 以开放 query_garmin_graphql

例如，在配置项的 "env" 下设置：

"garmin": {
  "command": "node",
  "args": ["…/dist/cli.js"],
  "env": { "GARMIN_MCP_GROUPS": "workouts,metrics,wellness,activities" }
}

如果同时设置了 GARMIN_EMAIL（邮箱地址，较早注册的账户可使用用户名）和 GARMIN_PASSWORD，其效果与扩展中的邮箱和密码设置相同：如果没有已保存的会话，服务会自动登录（不支持 MFA）。

如果更改了 GARMIN_MCP_TOKEN_DIR，请使用相同的值登录（GARMIN_MCP_TOKEN_DIR=/path/to/dir garminconnect-mcp login），否则服务将无法找到你的会话。

故障排除

• 工具没有显示。 确保 Claude Desktop 已完全退出并重新启动（步骤 4）。然后在“设置”→“开发者”→garmin 中查看服务状态和日志链接。
• “未登录 Garmin” 或 “会话已过期”：让 Claude 重新登录（它会调用 sign_in_to_garmin），或再次运行 garminconnect-mcp login。正在运行的服务会在下次请求时获取新会话；无需重启。
• 登录页面没有打开：Claude 的回复中会包含链接；在这台电脑上的任意浏览器中打开即可。链接会在 15 分钟后过期；让 Claude 重新登录即可。
• 尝试使用 npx 后出现 ERR_MODULE_NOT_FOUND：删除 npm 缓存中的 _npx 文件夹（运行 npm config get cache 可查看其位置），然后使用上方的全局安装方式。
• “Garmin 正在限制请求频率”：Garmin 会限制短时间内大量发出的调用。等待一分钟后再试。
• 保存任何内容时出现 HTTP 412（欧盟账户）：在 Garmin Connect 设置中授予上传同意；在此之前，Garmin 会拒绝所有写入操作。
• 非常详细的活动数据似乎被截断：单个工具结果上限为 100,000 个字符，而每秒活动数据（get_activity_details）通常会超出此上限。请改为请求摘要，或下载活动文件（download_activity）并在其他地方打开。

更新

npm install -g @dynamicsninja/garminconnect-mcp@latest

然后退出并重新启动 Claude Desktop。已保存的会话会保留。

其他 MCP 客户端

任何能够启动 stdio 服务的客户端都可以使用。命令是 garminconnect-mcp（或 node …/dist/cli.js）。例如，在 Claude Code 中：

claude mcp add garmin -- garminconnect-mcp

须知

• 日期为 UTC 日历日期（YYYY-MM-DD）。
• 所有操作都在你的电脑上运行。Garmin 会话保存在你的令牌文件夹中，且只会发送给 Garmin。详情请参阅 PRIVACY.md。
• Garmin Connect 的 API 并非官方 API，可能会发生变化。本服务与 garminconnect-js 同步发布，每个版本都会针对其包含的库版本进行测试。