本地 Garmin Coach MCP

面向 Codex/ChatGPT 桌面版和 Claude 的私有单用户 Garmin 教练工具。服务器仅通过本地 stdio 运行：无需 Cloudflare、Render、公共 URL、账户服务或托管费用。

该运行时基于 etweisberg/garmin-connect-mcp，提交版本为 87d0ea059fb67f1ce65ac05100df74c3c3777c84。它在 NOTICE 中保留上游 AGPL-3.0 许可证和 Taxuspt 署名。

先决条件

• Node.js 20 或更高版本

• pnpm 10.14.0

• 一个 Garmin Connect 账户和已同步的手表

Related MCP server: io.github.matisdsp/fartlek

安装

cd /home/talvak/Desktop/repos/garmin-coach-mcp
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm build
pnpm auth

pnpm auth 会打开一个专用的可见 Chrome 配置文件。请手动登录，完成 MFA，然后在终端中按 Enter。浏览器会话保存在 ~/.local/share/garmin-coach/browser-profile 下。运行时 CSRF 值从当前已认证页面读取，绝不持久化或打印。目录权限为 0700，文件权限为 0600，密码保存已禁用，且不会创建任何用户名/密码文件。

捕获 Garmin 的 profile 写入契约

Garmin 没有发布稳定的心率档案写入 API。该服务器拒绝猜测它。

pnpm capture:profile-contract

该命令会加载 Garmin 当前的应用程序模型，要求它保存未更改的当前默认区间，并在交付前阻止产生的 PUT 请求。它验证路由和完全未更改的请求体，然后仅在 ~/.local/state/garmin-coach/profile-write-contract.json 中以 0600 权限存储脱敏后的方法/路径/字段结构以及受支持的作用域。

如果无法证明 Garmin 的结构，则不会保存任何契约，并且 profile 写入将保持禁用。

连接 Codex 和 ChatGPT 桌面版

请先构建，然后将 config/codex.toml.example 复制到 ~/.codex/config.toml，或者通过 ChatGPT 桌面版的“设置 > MCP 服务器”添加等效服务器。Codex CLI、IDE 扩展和 ChatGPT 桌面版共享同一主机上的本地 MCP 配置。

该示例使用：

default_tools_approval_mode = "writes"

两个 apply 工具也都显式设置了 approval_mode = "prompt"。配置后请重启客户端，并使用 /mcp 验证连接。

ChatGPT 网页版无法启动此本地 stdio 进程。如需执行 Garmin 写入，请使用 ChatGPT 桌面版/Codex。

连接 Claude

将 config/claude.json.example 合并到 Claude 的 MCP 配置中，或运行：

claude mcp add garmin-coach -- /home/talvak/snap/code/current/.local/share/pnpm/node /home/talvak/Desktop/repos/garmin-coach-mcp/dist/index.js

文件系统锁允许同一时间只有一个本地客户端拥有 Garmin Chromium 配置文件。在使用另一个客户端之前，请先在当前客户端中停止服务器。

工具

安全工作流

1. 调用 get_coaching_snapshot 并将其与 Garmin Connect 进行比较。

2. 调用 preview_hr_profile_update。

3. 审查每个字段，并批准完全相同的规范提案/哈希。

4. 调用 apply_hr_profile_update；然后同步 Garmin 并目视验证手表区间。

5. 为一个从周日开始的训练周调用 preview_training_week。

6. 审查其恢复证据、完整载荷、警告和哈希。

7. 使用未更改的规范提案/哈希调用 apply_training_week。

8. 调用 verify_training_week，并确认周一/周五为 135-149 bpm；周五必须显示固定的 12% 说明。

9. 重试两个 apply 调用以证明幂等性。

疼痛/受伤或疾病会阻止训练写入。恢复可以保持、减少或跳过；它绝不会增加负荷。训练永远不会被自动删除。

Garmin 将跑步机（Treadmill）作为跑步（Running）之下的手表活动暴露，而不是作为结构化训练运动。因此，周五是一个与跑步兼容的训练，名为 Incline Walk 12%；请从手表的跑步机活动开始该训练。其 12% 坡度提示和 135-149 bpm 目标保持明确。

已批准的心率档案

这些值是临时性的：年龄 27，静息心率 55，预估最大心率 189，手动 LTHR 181。自动检测标志会被保留。未来的更改需要再次进行预览和批准。

验证

常规测试为离线运行，绝不会调用 Garmin：

pnpm test
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build
git diff --check

有关行为请参阅 spec.md，有关信任边界请参阅 docs/architecture.md。

许可证

AGPL-3.0。请参阅 LICENSE 和 NOTICE。