Garmin Connect MCP server

一个用于 Garmin Connect 力量训练的 MCP 服务器。通过与 AI 助手对话设计训练课，推送到您的手表，并读回您实际举起的重量。

非官方。 与 Garmin 无关联，未获 Garmin 认可或支持。Garmin 和 Garmin Connect 是 Garmin Ltd. 的商标。本项目通过逆向工程的 python-garminconnect 客户端与 Garmin 的私有锻炼服务端点通信，因此 Garmin 可能随时更改或破坏它，恕不另行通知。使用风险自负，并请自行检查您对 Garmin 服务条款的遵守义务。

所有内容均在本地运行。您的凭据只保留在您的机器上，并且只会发送给 Garmin。

为什么存在

Garmin Connect 不会导入锻炼 .FIT 文件——FIT 导入仅适用于已完成的活动，不适用于计划中的锻炼。您的选择是手动使用 Connect 网页界面，或者使用 Web 应用本身调用的同一私有端点。本项目采用第二条路线，并在其上提供 MCP 接口，这样锻炼计划可以来自对话，而不是二十分钟的点击操作。

工具

delete_workout 是唯一具有破坏性的工具。

设置

需要 Python 3.12 或更高版本（garminconnect 0.3.x 需要它）。

git clone https://github.com/YOUR-USERNAME/garmin-mcp.git
cd garmin-mcp
./setup.sh

setup.sh 在项目目录中创建 .venv/，安装依赖项，并将 .env.example 复制为 .env。不会在系统范围内安装任何内容。如果您最新的 Python 还没有某个依赖的 wheel，请覆盖它：

PYTHON=python3.13 ./setup.sh

在 .env 中填写您的 Garmin 登录信息，然后进行一次身份验证：

./.venv/bin/python garmin_login.py

此步骤特意设计为交互式的。Garmin 可能会要求输入 MFA 代码，而 MCP 服务器没有终端可以询问——它会直接挂起。登录会将令牌缓存到 ~/.garminconnect，服务器之后会静默地重用它们。仅当服务器报告会话过期时才重新运行。

在不接触网络的情况下验证构建：

./.venv/bin/python garmin_mcp.py --self-test

连接到客户端

Claude Desktop

添加到 claude_desktop_config.json——在 macOS 上位于 ~/Library/Application Support/Claude/，在 Windows 上位于 %APPDATA%\Claude\：

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/garmin-mcp/garmin_mcp.py"]
    }
  }
}

使用绝对路径和 venv 的解释器，而不是裸的 python——应用不会继承您 shell 的 PATH。之后重启应用。

其他客户端

这是一个标准的 stdio MCP 服务器，因此任何客户端都可以使用。要在客户端之外调试：

npx @modelcontextprotocol/inspector ./.venv/bin/python garmin_mcp.py

程序

程序是 programs/ 中描述多日模板的 JSON 文件。sync_program 推送其中的每个锻炼，按名称匹配——现有锻炼原地更新，新锻炼创建。参见 programs/example.json 获取带注释的模板。

{
  "name": "Example Upper/Lower",
  "workouts": [
    {
      "name": "[EX] Upper A",
      "warmup": "Two or three ramp-up sets.",
      "blocks": [
        {
          "repeat": 4,
          "steps": [
            { "exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 60,
              "note": "4x5-7. Add 2.5kg once you hit 7 on every set." },
            { "rest_seconds": 180 }
          ]
        }
      ]
    }
  ]
}

块 是一个重复组，运行 repeat 次。步骤 要么是动作（exercise + reps，可选 weight_kg 和 note），要么是休息（rest_seconds）。超级组是一个块，包含两个动作，中间有短暂休息，末尾有长休息。自重训练省略 weight_kg。省略 warmup 使用默认热身步骤，或设置为 "" 表示无热身。

programs/*.json 除了示例外都被 gitignore 忽略，因此您自己的训练永远不会进入提交。

会坑到您的事情

Garmin 会静默地清空无法识别的动作名称。 上传返回 200，动作在手表上以无名形式出现在会话中途。这就是 search_exercises 存在的原因，也是每个名称在上传前都会对照目录解析的原因。显示名称的连字符方式没人会打——"Rope Press-down"、"Close-grip Chin-up"——因此搜索会规范化标点并理解简写，如 "db"、"bb"、"ohp"、"rdl"、"skullcrusher"。

API 的两半对重量单位意见不一。 锻炼服务接受以千克为单位的 weightValue，尽管 weightUnit 携带 "factor": 1000.0。活动负载——即您举起的重量——以克报告。两者都已处理；不要"修复"任何一个。

往返验证无法捕获单位错误。 它比较 Garmin 存储的内容与发送的内容，而 Garmin 会忠实地存储您发送的任何内容。当发送克时，检查通过，Connect 显示"75,000 kg"。请在 Connect 中目测您的第一次上传。

更新，而不是删除后重建。 保留锻炼 ID 意味着手表将更改视为编辑。重建会导致它丢弃旧锻炼并拉取新锻炼，这就是陈旧重复项的来源。

429 和 401 看起来一样。 Garmin 按 IP 对登录进行激进的速率限制。当第一个登录传输被限流时，garminconnect 的回退会报告误导性的 401。如果您刚才看到 429，那就是限流——等待 30–60 分钟，不要循环重试，这会延长封锁时间。要排除密码确实错误的情况：garmin_login.py --check-env。

布局

garmin_mcp.py       the server — tool definitions
garmin_core.py      auth, payload building, verification, set parsing
garmin_login.py     one-time interactive login (MFA lives here)
programs/           multi-day templates as JSON
setup.sh            creates .venv and installs dependencies

许可证

MIT——参见 LICENSE。

基于 python-garminconnect (MIT) 和 MCP Python SDK (MIT) 构建。