garmin-connect-workouts-mcp

Garmin Connect 训练 MCP

一个 MCP（Model Context Protocol）服务，可将自然语言训练描述转换为 Garmin Connect 中的结构化训练。用通俗英语描述训练计划，调用模型就会构建一个带类型的分步训练计划，由此服务将其编码为 Garmin 的训练 API 格式，并直接创建到你的账户中。

功能

• 配速、心率、功率和步频目标 - 配速范围、1-5 区心率区间、明确的 bpm 范围、骑行功率和步频，全部依据 Garmin 的真实 workoutTargetType 表进行编码。
• 真实重复组 - 5x1km 会变成一个重复组，而不是五个重复步骤，因此手表会显示实际的重复次数计数器。
• 游泳训练 - 每个步骤可设置泳姿（自由泳、仰泳、蛙泳、蝶泳、打腿练习、个人混合泳或任意泳姿）和装备（脚蹼、打水板、划水掌、浮漂、呼吸管），并可设置以米或码为单位的训练泳池长度。
• 完整的训练生命周期 - 创建、列出、获取、更新、删除训练，并将训练安排到 Garmin Connect 日历中。
• 结构化输入，而非文本解析 - 服务本身不会解析自由文本；每个时长和目标都是带有明确单位的字段，因此不会出现像“10 min”这样的字符串被误读的情况。

快速开始

Claude Code

claude mcp add garmin-workouts npx garmin-connect-workouts-mcp

Claude Desktop

将以下内容添加到配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "garmin-workouts": {
      "command": "npx",
      "args": ["-y", "garmin-connect-workouts-mcp"]
    }
  }
}

然后重启 Claude Desktop。

身份验证

Garmin Connect 的 Web 客户端使用会话 Cookie 和 CSRF 令牌进行身份验证，而非此服务可以保存的密码授权。因此，首次创建训练时（或会话过期时）：

1. 服务会通过一个轻量级的身份验证请求检查已存储的会话。
2. 如果会话缺失或被拒绝，请运行 authenticate_garmin 工具。它会在 connect.garmin.com 打开一个真实的浏览器窗口，供你正常登录。
3. 登录完成后，会话会被捕获并存储到 ~/.config/garmin-connect-workouts-mcp/auth.json，权限为 600（仅所有者可读写）。

服务绝不会存储密码，只保存由此产生的会话 Cookie 和 CSRF 令牌。Garmin 会话会过期，因此你可能需要在不同会话之间重新进行身份验证；服务会自动检测到这一点，并告知你再次运行 authenticate_garmin。登录浏览器使用位于 ~/.config/garmin-connect-workouts-mcp/browser-profile/ 下持久且隔离的配置文件，以便 Garmin 在多次登录之间记住设备；它绝不会接触你的个人浏览器配置文件。

工具

工具	描述
create_garmin_workout	创建包含步骤、目标和重复组的结构化训练。
list_garmin_workouts	列出 Garmin Connect 账户中的训练。
get_garmin_workout	获取一项训练的完整结构。
update_garmin_workout	替换现有训练的内容，同时保留其 ID。
delete_garmin_workout	删除一项训练。
schedule_garmin_workout	将一项训练安排到 Garmin Connect 日历的指定日期。
check_garmin_auth	检查已存储的 Garmin 会话是否仍然有效。
authenticate_garmin	使用 Garmin Connect 进行身份验证（会打开浏览器）。

使用示例

• “创建一场 30 分钟的轻松跑，保持在 2 区”
• “热身 10 分钟，保持在 3 区；然后进行 5 组 1 公里阈值间歇跑，配速为 4:00/km，组间休息 2 分钟；最后在 2 区冷身 10 分钟”
• “以 5 公里比赛配速跑 8 组 400 米，每组间恢复 60 秒；然后查看我本周已经安排的训练”
• “更新训练 123456，加入 5 分钟冷身，然后安排在下周一”
• “创建一场 25 米泳池游泳训练：任意泳姿热身 200 米；使用浮板进行 4 组 100 米自由泳，组间休息 30 秒；最后蛙泳冷身 100 米”

目标的工作方式

指定的配速会被视为范围的快侧：Garmin 将配速存储为一个范围，而非单个数值，因此单独指定 4:00/km 会转换为 4:00-4:10/km 的范围，放宽 10 秒。若要设置更窄或不同的范围，请明确指定 fast 和 slow。

开发

pnpm install
pnpm test          # vitest: encoders + golden-file tests against real captured payloads
pnpm run build      # compile TypeScript to dist/
pnpm run dev        # run the server directly with tsx

测试会根据从 Garmin 自有网页客户端捕获的样本，验证训练编码器（目标、时长、重复嵌套），以便在载荷格式回归问题影响真实账户之前发现它们。

免责声明

这是一个非官方的第三方项目，与 Garmin Ltd. 及其任何关联公司均无关联，也未获得其认可或赞助。本项目通过逆向工程官方网页客户端发出的相同请求，与 Garmin Connect 的 Web API 通信。如果 Garmin 更改该 API，本项目可能会停止工作。使用风险自负，并自行承担发送到自己账户的训练和数据所带来的责任。

致谢

感谢 Charles Frisbee 编写的 garmin-workouts-mcp，最初提出了通过 MCP 操作 Garmin Connect 训练的想法。

许可证

MIT