durely insights MCP for Garmin

durely garmin-insights-mcp

向 AI 助手询问你自己的 Garmin 数据：全面分析你的训练历史、健康状况和恢复情况。

durely insights 是一个 MCP 服务，通过 Garmin 官方的 Personal API 将你的 Garmin Connect 帐户连接到 AI 助手（Claude、Cursor、GitHub Copilot、Gemini CLI、Codex 或其他任何 MCP 客户端）。它会在你的设备上保存一份历史数据副本，让你随时询问某次跑步或多年的训练情况，并立即获得答案。

早期开发阶段。 以下功能均可使用，但在 1.0 版发布前，工具和选项仍可能发生变化。

非官方项目：与 Garmin 无关联，也未获得 Garmin 的认可。

你可以询问什么

活动

• “我这周做了什么运动？”／“显示我最近 10 次跑步”
• “介绍一下我昨天的跑步”：分段、心率、训练效果、负荷
• “周二骑行的间歇过程中，我的功率和心率是如何变化的？”
• “逐圈比较我最近两场铁人三项的自行车赛段”
• “我每周二的常规跑步状态是否越来越好？”

训练

• “过去 3 个月，我的训练负荷和体能是如何发展的？”
• “分析周六的骑行：各区间用时、去耦、最佳表现”
• “我每年跑步、骑行和游泳多少公里？”

健康与恢复

• “我这周睡得怎么样？HRV 如何？”
• “高强度训练日会影响第二天早上的 HRV 吗？”
• “比较我今年每月的静息心率和睡眠分数”
• “显示我昨天的心率和 Body Battery 变化”

与众不同之处

• 官方 API，无需密码。 使用你在 Garmin Connect 中创建的 Personal API 密钥，你可以随时撤销。不会抓取数据，也不会因 Garmin 更改登录方式而失效。
• 完整历史，随时可查。 所有数据只需同步到本地数据库一次，之后会持续更新，因此查询数月或数年的趋势无需等待 Garmin 响应。
• 秒级详细数据。 每项活动的原始 FIT 文件都包含分段、游泳趟数、心率、功率、步频等数据；如果设备有记录，也会包含 VO2max、恢复时间和乳酸阈值。
• 内置分析功能。 包括各区间用时、训练负荷、体能／疲劳／状态、有氧去耦、最佳表现、恢复趋势和相似训练对比。其他问题则可由助手对你的数据运行只读 SQL。
• 默认保护隐私。 你的数据保存在自己的设备上。除非你询问路线，否则回答中不会包含你的姓名、帐户 ID 和 GPS 位置。
• 只读。 它无法更改 Garmin 帐户中的任何内容。

快速开始

你需要 Garmin Connect、一个 MCP 客户端（Claude Code、Claude Desktop、Cursor，……），以及 Node.js 24+ 或 Docker。

1. 创建你的 Personal API key

1. 在网页版 Garmin Connect 中，打开 Settings → Personal API Token。

2. 创建密钥，并选择有效期（30 天至 1 年）。Garmin 只会显示一次密钥，请复制保存。

3. 在你自己的终端中运行以下命令来保存密钥：

   npx -y @durely/garmin-insights-mcp auth
   

   系统会提示你输入密钥（输入内容不会显示），并向 Garmin 验证密钥，然后将其保存到 ~/.config/garmin/connect-personal-api-key，只有你本人可以读取。如果 Garmin 拒绝该密钥，则不会保存任何内容。服务会从此文件读取密钥，因此无需将密钥写入客户端配置。

   使用 Docker（无需 Node.js）时，请自行将密钥保存到该文件：

   mkdir -p ~/.config/garmin && chmod 700 ~/.config/garmin
   pbpaste > ~/.config/garmin/connect-personal-api-key    # macOS; elsewhere, paste it into this file with an editor
   chmod 600 ~/.config/garmin/connect-personal-api-key
   

不要在与 AI 助手的聊天中粘贴密钥。

2. 选择运行方式

使用 Node.js（npx）： 无需安装任何内容。服务命令如下：

npx -y @durely/garmin-insights-mcp

npx 会在首次使用时下载 npm package，并自动获取新版本。运行 npx -y @durely/garmin-insights-mcp auth --check 检查密钥。想要固定安装？运行 npm install -g @durely/garmin-insights-mcp，即可使用 garmin-insights 命令。

或使用 Docker（无需 Node.js；Docker 必须处于运行状态）。服务命令如下：

docker run -i --rm \
  -v ~/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro \
  -v garmin-mcp-data:/data \
  -e GARMIN_MCP_TIMEZONE=Europe/Brussels \
  ghcr.io/durely/garmin-insights-mcp

将 Europe/Brussels 替换为你自己的时区。要检查密钥，请在同一命令末尾加上 auth --check。该镜像支持 Intel 和 ARM（Apple silicon、Raspberry Pi）。更多 Docker 使用技巧请参阅工作原理。

或从源代码运行： 克隆仓库，然后使用 npm 或 Docker 构建。请参阅工作原理。

更新： 使用 npx 时，重启客户端即可。使用 Docker 时，运行 docker pull ghcr.io/durely/garmin-insights-mcp。已同步的数据会保留。

3. 将其添加到你的 AI 客户端

Claude Code：

claude mcp add garmin --scope user -- npx -y @durely/garmin-insights-mcp

使用 Docker：

claude mcp add garmin --scope user -- docker run -i --rm \
  -v ~/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro \
  -v garmin-mcp-data:/data \
  -e GARMIN_MCP_TIMEZONE=Europe/Brussels \
  ghcr.io/durely/garmin-insights-mcp

--scope user 会让所有项目都可以使用它。

Claude Desktop： 打开 Settings → Developer → Edit Config，添加以下内容，然后重启 Claude Desktop：

{
  "mcpServers": {
    "garmin": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@durely/garmin-insights-mcp"]
    }
  }
}

桌面应用无法访问 shell 的 PATH，因此请使用 npx 的完整路径（运行 which npx 查找）。如果日志随后提示找不到 node，请添加 "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }，并将 which node 返回的目录放在最前面。

{
  "mcpServers": {
    "garmin": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/you/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro",
        "-v",
        "garmin-mcp-data:/data",
        "-e",
        "GARMIN_MCP_TIMEZONE=Europe/Brussels",
        "ghcr.io/durely/garmin-insights-mcp"
      ]
    }
  }
}

{
  "servers": {
    "garmin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@durely/garmin-insights-mcp"]
    }
  }
}

gemini mcp add garmin npx -- -y @durely/garmin-insights-mcp

codex mcp add garmin -- npx -y @durely/garmin-insights-mcp

4. 试用

开启新会话并询问：“检查我的 Garmin 连接。” 它应该会报告已连接。

第一个问题会在后台启动同步。几秒内即可看到你的活动记录；其余历史记录会在几分钟内同步完成。之后，当数据超过一小时未更新时，系统会自动刷新。

注意事项

• 请留意密钥的到期日期。 Garmin 的 API 不会告知服务端密钥何时到期。在客户端配置中设置 GARMIN_API_KEY_EXPIRES（例如 2027-10-24），garmin_status 会及时提醒你。使用 Docker 时，请改为将其传递给容器：在 docker run 参数中添加 -e GARMIN_API_KEY_EXPIRES=2027-10-24。替换密钥文件即可，无需重启。
• 至少每隔几个月同步一次。 Garmin 会在约 4–5 个月后删除日内详细数据（全天心率、夜间 HRV 读数）。服务端已同步的数据会保留在你的本地副本中。
• 目前仅支持桌面和命令行客户端。 服务运行在你自己的机器上，因此暂时无法在网页或移动版的 claude.ai 中使用。
• 你的数据会发送给 AI 客户端。 服务只与 Garmin 通信，但它提供的答案会发送给你使用的 MCP 客户端和模型。

故障排除

工具

你无需自行调用这些工具；助手会为你选择。仅供参考：

在支持提示词的客户端中（通常以斜杠命令的形式），weekly_review、activity_deep_dive 和 recovery_check 会启动引导式分析。

配置

所有配置项均为可选；在客户端配置中将它们设为环境变量。

在 Docker 中，密钥文件和数据目录分别为 /run/secrets/garmin_api_key 和 /data。

隐私与安全

• 密钥始终保留在你的设备上。 密钥会兑换为有效期为 24 小时的令牌，并以仅所有者可访问的权限缓存。服务不会写入密钥本身。若要撤销访问权限，请在 Garmin Connect 中删除密钥。
• 无遥测数据。 服务只与 Garmin 的 Personal API 通信。
• 同步的数据属于敏感信息。 本地数据库和 FIT 文件包含你的健康与活动历史记录，包括 GPS 轨迹。数据目录仅你本人可读取（在 Docker 中，数据存储于 garmin-mcp-data 卷）。
• 回答中不会包含身份和位置信息。 任何内容存储之前，你的姓名、头像和账户 ID 都会被移除。只有在你要求进行路线或位置分析时（或使用 SQL 查询某项活动的起点和终点），才会返回 GPS 坐标。

更多信息

• 工作原理：本地缓存与同步、FIT 文件、数值的计算方式、Docker 详情、开发

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。

数据由 Garmin 设备通过 Garmin Connect 提供；相关分析是部分基于 Garmin 设备采集的数据得出的洞察。Garmin 和 Garmin Connect 是 Garmin Ltd. 或其子公司的商标。本项目与 Garmin 无关联，也未获 Garmin 背书。