Garmin Personal MCP

将 Garmin Connect 连接到 Claude 或任何 MCP 客户端。询问昨晚的睡眠情况、HRV 趋势、Body Battery、训练负荷或某次具体跑步的数据，所有信息都来自你的真实 Garmin 账户。

已在 PyPI 上发布，包名为 garmin-personal-mcp。

非官方项目，使用官方 API。 本项目并非由 Garmin 制作，但只会通过 Garmin 自家的 Python 客户端调用 Garmin 文档中说明的 Personal API。

为什么选择它？

大多数 Garmin MCP 服务会通过非官方的 garminconnect 库使用你的 Garmin 密码登录；每当 Garmin 更改登录方式时，这类服务就会失效。2026 年 10 月，Garmin 为个人用户开放了 Personal API。本服务使用该 API：

• 无需密码，不抓取数据：使用你在 Garmin Connect 中创建的可撤销 Personal API 密钥，并将其兑换为短期令牌
• 完整的 Personal API：参考文档中每个可用的端点都有对应工具，并支持所有文档所述的筛选条件
• 任意日期范围：如果日期范围超过端点允许的长度（步数为 28 天、睡眠为 31 天等），会自动拆分为多个请求
• 适合模型处理的响应：默认省略全天采样数组，除非你明确请求
• 只读：Personal API 无法更改你的账户，本服务也不能

快速入门

1. 保存你的 Personal API 密钥（仅需一次；参见身份验证）：

   uvx garmin-personal-mcp auth
   

2. 将服务添加到客户端。顶部的安装按钮可一键完成此操作，适用于 Cursor 和 VS Code。

   Claude Code

   claude mcp add garmin -- uvx garmin-personal-mcp
   

   也可以将其安装为插件；此方式会要求你输入密钥，无需执行第 1 步：

   /plugin install garmin-personal-mcp --marketplace Mason-Levyy/garmin-personal-mcp
   

   Claude Desktop（claude_desktop_config.json）、Cursor （~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json） 和 Cline（cline_mcp_settings.json）使用相同的配置项：

   {
     "mcpServers": {
       "garmin": {
         "command": "uvx",
         "args": ["garmin-personal-mcp"]
       }
     }
   }
   

   VS Code、Codex CLI、Gemini CLI

   VS Code（也可以使用上方的按钮）：

   code --add-mcp '{"name":"garmin","command":"uvx","args":["garmin-personal-mcp"]}'
   

   Codex CLI：

   codex mcp add garmin -- uvx garmin-personal-mcp
   

   Gemini CLI：

   gemini mcp add garmin uvx garmin-personal-mcp
   

3. 向它提问，例如：“我昨晚睡得怎么样？”、“我这个月的 HRV 是否呈下降趋势？”、“比较一下我最近三次长跑”。

需要 uv。任何支持 stdio 或可流式传输 HTTP 的 MCP 客户端都可以使用，不限于 Claude。

觉得这个工具有用吗？ 在 GitHub 上点个 ⭐，能帮助其他 Garmin 用户找到它。

身份验证

1. 在网页上登录 Garmin Connect，然后打开 Settings → Personal API。
2. 创建密钥并选择有效期（30 天至一年）。Garmin 只会显示一次密钥。
3. 运行 garmin-personal-mcp auth，并在隐藏输入提示中粘贴密钥。服务会先向 Garmin 验证密钥，然后将其保存到 ~/.config/garmin/connect-personal-api-key，并设置仅所有者可访问的权限。

如果运行环境没有可供提示输入的终端（例如脚本，或由 Agent 运行的 shell），可以改为通过管道传入密钥，例如 pbpaste | garmin-personal-mcp auth。

garmin-personal-mcp auth --check 会报告已保存的密钥是否仍然有效，不会提示输入。密钥即将过期前约一周，Garmin 会发送邮件通知：创建新密钥并再次运行 auth 即可。无需重启；服务每次调用时都会读取密钥。

也可以设置 GARMIN_PERSONAL_API_KEY 来代替密钥文件；此环境变量的优先级更高。密钥文件和 bearer-token 缓存与 Garmin 的 gc-personal CLI 使用的是同一份，因此通过其中任一方式保存的密钥都可供两者使用。

工具

所有工具都接受格式为 YYYY-MM-DD 的日期。范围工具默认返回截至今天的 7 天数据。返回列表的工具会将结果包装为 {"results": [...]}。

工具	返回内容
garmin_get_day	一天概览：摘要、睡眠、HRV、Body Battery、压力和活动
garmin_get_daily_summary	某个日期的所有全天健康数据汇总
garmin_get_daily_summaries	某个范围内的每日摘要（用于查看数周或数月的趋势）
garmin_get_steps	每日步数、距离和目标
garmin_get_stress	每日压力水平及各压力区间的时长
garmin_get_hydration	每日摄入量、目标和汗液流失量
garmin_get_body_battery	每日充电量／消耗量及相关事件；chunks 用于查看日内低点和高点
garmin_get_heart_rate	静息／最低／最高心率、7 天静息心率平均值、异常心率提醒；可按需获取样本
garmin_get_spo2	脉搏血氧平均值、每小时平均值、适应情况；可按需获取读数
garmin_get_wellness_activities	健康活动及摘要值和各心率区间的时长
garmin_get_sleep	一晚的完整数据：评分、睡眠阶段、时间和夜间生命体征
garmin_get_sleep_summaries	某个范围内的每晚睡眠记录
garmin_get_hrv	一晚的 HRV 及每条读数
garmin_get_hrv_summaries	某个范围内的每晚 HRV、每周平均值、基线和状态
garmin_get_weight	每日体重摘要、范围平均值和相邻称重记录；使用 include_all 可获取所有称重记录
garmin_get_weight_goals	当前生效的体重目标及其目标范围
garmin_get_food_log	Garmin Connect 营养日志：食物、营养素、目标和餐食
garmin_search_activities	活动及 Garmin 支持的所有筛选条件（类型、日期、距离、功率、区域、潜水等）
garmin_get_activity	一项活动的完整数据，含分段
garmin_get_activity_workouts	活动期间执行的结构化训练
garmin_download_activity	将活动的原始文件（包含 .fit 的 ZIP）保存到服务所在的计算机
garmin_get_profile	单位、格式、时区和训练日偏好
garmin_get_heart_rate_zones	各运动项目的心率区间下限及其依据的心率值
garmin_get_fitness_age	健康年龄、可达到的健康年龄及其组成部分
garmin_get_menstrual_cycle	周期阶段、周期日、易孕期和预测
garmin_get_menstrual_day	某一天记录的症状、经血量和周期详情

体重单位为克，距离单位为米，时长单位为秒，与 Garmin 返回的数据一致。

远程／HTTP 模式

默认传输方式为 stdio。对于网络客户端：

garmin-personal-mcp --http --host 127.0.0.1 --port 8491

此模式会在 /mcp 提供可流式传输的 HTTP。**没有内置身份验证。切勿将其暴露到互联网。**请绑定到 localhost，并通过可提供身份验证的方式访问，例如 VPN 或 tailnet（如 tailscale serve）、具有身份验证功能的反向代理，或支持 OAuth 的 MCP 网关。在代理后运行时，请传入 --allowed-host <proxy hostname>（可重复传入），以便 DNS 重绑定检查接受其 Host 标头。

配置

变量	用途	默认值
GARMIN_PERSONAL_API_KEY	Personal API key；覆盖已保存的密钥文件	–
GARMIN_MCP_DOWNLOAD_DIR	garmin_download_activity 保存文件的位置	~/Downloads/garmin（平台下载目录）

故障排除

• “Garmin 拒绝了 Personal API key”：密钥已过期或被删除。请创建新密钥并运行 garmin-personal-mcp auth。
• “未找到可用的 Garmin Personal API key”：请运行 garmin-personal-mcp auth，或在客户端配置中设置 GARMIN_PERSONAL_API_KEY。
• {"no_data": ...}：Garmin 尚无该日期的数据（例如，今天尚未睡觉，因此没有 HRV 数据），或者你的设备未记录该指标。
• 长时间范围出现 HTTP 400：某个未注明限制的端点拒绝了该范围。请缩短范围。

常见问题

这是 Garmin 官方 API 吗？ 是的。它使用 Garmin 的 Personal API，任何拥有 Garmin Connect 账户的人都可以通过 Garmin 采用 Apache 许可证的 Python 客户端启用，无需申请。本项目本身是独立的。

它能修改我的 Garmin 数据吗？ 不能。Personal API 仅支持读取。唯一会写入内容的工具 garmin_download_activity 会在你自己的设备上保存文件。

它适用于哪些 MCP 客户端？ 适用于任何运行 stdio 或 streamable HTTP 服务的客户端，包括 Claude Desktop、Claude Code、Cursor、Windsurf、Cline 和 VS Code。AI 编码 Agent 可以参考 llms-install.md。

我的数据会发送到哪里？ 此服务只会与 Garmin 通信。你的密钥和 bearer token 会保存在 ~/.config/garmin/ 中。工具结果会发送到你连接的 MCP 客户端和模型。

我可以用它访问其他人的账户吗？ 不可以。Garmin 的 Personal API 仅用于访问你自己的数据。为其他用户提供服务的应用需要加入 Garmin 的商业开发者计划。

工作原理

• garmin-personal-mcp auth 会保存密钥；每次调用都会通过 Garmin 的 PersonalApiAuthenticator 将其换成 bearer token，并缓存该 token，直到过期前一小时。若 token 提前遭拒，会使用新的交换结果重试一次。
• 每个工具对应 personal.connectapi.garmin.com 上的一个端点（garmin_get_day 会合并多个端点的数据）。对于超过端点文档所述最大范围的请求，会分段连续获取并合并结果。
• 为了让模型更容易阅读响应，默认会丢弃体积较大的每分钟样本数组；设置 include_samples 或 chunks 可将其包含在内。

开发

git clone https://github.com/Mason-Levyy/garmin-personal-mcp
cd garmin-personal-mcp
uv sync
uv run pytest

测试使用合成样例运行；无需账户。使用 ruff 检查代码风格和格式（uv run ruff check .、uv run ruff format .）。

贡献

欢迎提交问题和拉取请求，尤其是 Garmin 为 Personal API 新增端点时。设置说明、风格指南和 PR 检查清单见 CONTRIBUTING.md；有关如何私下报告漏洞的信息，请参阅 SECURITY.md。发布历史见 CHANGELOG.md。

支持本项目

如果此服务为你节省了时间，请 为仓库点星。星标能让其他 Garmin 用户在 GitHub 搜索和 MCP 目录中找到它。也欢迎在 issues 中提交错误报告和端点请求。

许可证

MIT。Garmin 和 Garmin Connect 是 Garmin Ltd. 或其子公司的商标；本项目与 Garmin 无关联，也未获其认可。