OwnMetrics

ownmetrics-mcp

询问 Claude、ChatGPT 或任何支持 MCP 的 AI 应用，了解你自己的 Garmin 数据：睡眠、HRV、压力、Body Battery、心率、活动等。它使用 Garmin 官方的 Personal API，在你自己的电脑上运行，并且仅提供只读访问。

非官方项目。 与 Garmin 无关联，也未获其认可或支持。 “Garmin”和“Garmin Connect”是 Garmin Ltd. 或其子公司的商标。 结果仅供参考，不能作为医疗建议。

**状态：v0.2（预览版）。**包含九个数据工具和四个洞察工具（训练摘要、 时段对比、趋势、训练与睡眠）。FIT 文件分析即将推出。

你可以这样询问

• “我这周睡得怎么样？哪晚睡得最差，为什么？”
• “显示我最近 30 天的 HRV。趋势是否在下降？”
• “我昨天的压力和 Body Battery 情况如何？”
• “列出我本月的跑步记录，包括距离和平均配速。”
• “分析我最近的一次长距离骑行：功率、心率、训练效果。”
• “自 9 月以来，我的静息心率有什么变化？”
• “今年我哪个月睡得最好？那个⽉我训练了多少？”
• “对比我今年 10 月和去年 10 月的睡眠与训练情况。”
• “我晚上的网球活动是否会导致睡眠变差？”
• “我的 Garmin 连接正常吗？”

最简单的方式：一键安装到 Claude Desktop

1. 创建 Garmin Personal API 密钥：在网页上登录 Garmin Connect，打开 设置 → Personal API， 选择 Create Key，接受 Garmin 的条款，选择密钥有效期，然后复制密钥。
2. 从最新版本下载 ownmetrics-mcp-<version>.mcpb。
3. 双击该文件。Claude Desktop 会打开并询问是否安装；按提示粘贴密钥。 Claude Desktop 会将密钥隐藏。（如果你已经用 ownmetrics-mcp auth 保存了密钥，请将此字段留空。）
4. 询问 Claude：“我的 Garmin 连接正常吗？”

该安装包尚未签名，因此 Claude Desktop 在安装前可能会显示警告。首次启动时会下载一些 Python 软件包，因此需要联网，可能需要等待片刻。

为其他应用设置（约 10 分钟）

适用于 Claude Code、ChatGPT 桌面应用、Cursor 和其他支持 MCP 服务的应用；如果你更喜欢使用 Claude Desktop 的配置文件，也可以按此方式设置：

1. 安装 uv（仅需一次）

uv 无需手动设置即可运行 Python 工具。

• **macOS / Linux：**打开终端并运行 curl -LsSf https://astral.sh/uv/install.sh | sh
• **Windows：**打开 PowerShell 并运行 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 创建 Garmin Personal API 密钥

1. 在网页上登录 Garmin Connect，然后打开 设置 → Personal API。
2. 选择 Create Key，阅读并接受 Garmin 的条款，然后选择密钥有效期 （30 天到一年，由你选择）。
3. 复制密钥。Garmin 只会显示一次。

3. 保存密钥

uvx ownmetrics-mcp auth

按提示粘贴密钥（输入时会隐藏）。系统会使用 Garmin 验证密钥，然后将其保存到你的主文件夹中的 ~/.config/garmin/connect-personal-api-key。在 macOS 和 Linux 上，该文件只有你可以读取；在 Windows 上，该文件位于你的用户配置文件夹中，并由你的 Windows 帐户保护。

4. 添加到你的 AI 应用

**Claude Desktop：**依次打开 Settings → Developer → Edit Config，然后添加：

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

重启 Claude Desktop。

Claude Code：

claude mcp add ownmetrics -- uvx ownmetrics-mcp

**其他应用：**使用命令 uvx，并将 ownmetrics-mcp 作为参数。

更新

uvx 会保留首次下载的版本。若要升级到最新版本，请运行 uvx ownmetrics-mcp@latest --version，然后重启你的 AI 应用。

然后询问：“检查我的 Garmin 连接，然后总结我最近一周的睡眠和 HRV。”

工具

工具	返回内容
get_daily_overview	一天的数据：步数、距离、楼层、心率、压力、Body Battery、卡路里、强度分钟数、睡眠
get_sleep	每晚的数据：时长、深睡／浅睡／REM／清醒时间、评分、Garmin 的反馈、心率、呼吸
get_hrv	每晚的数据：前一晚和每周平均 HRV、5 分钟最高值、状态、基线
get_stress_and_body_battery	每天的数据：压力水平、处于各压力区间的时间、Body Battery 最高值／最低值／充能值／消耗值
get_heart_rate	一天的数据：静息、最低、最高心率；7 天静息心率平均值；你的心率区间
list_activities	日期范围内的活动，可按类型筛选，包含时长、距离、心率
get_activity	一项活动的数据：配速、速度、功率、步频、训练效果和负荷、分段
get_body_metrics	称重记录、BMI、体脂率、水合情况；Pulse Ox 和体能年龄
get_account_status	密钥是否有效、最后一天是否有警告、上述哪些数据类别可用

洞察工具会在一次调用中完成数据获取和计算，时间范围最长可达一年：

工具	回答的问题
training_summary	按周或按月汇总训练：训练次数、小时数、每周训练小时数、晚间训练次数、按运动类别细分
compare_periods	并排比较两个时段：睡眠、HRV、静息心率、压力、Body Battery、步数、训练数据，并显示变化值和变化百分比
recovery_correlations	训练与次晚睡眠和 HRV 变好或变差是否相关，并显示样本量和相关强度。相关不代表因果。
trend	按天、周或月查看一项指标，并显示趋势方向（上升、下降或持平）以及每 30 天的变化量

睡眠和 HRV 的日期按夜间结束的早晨计算（woke_up_on），与 Garmin 的处理方式一致。 跑步、步行和徒步显示配速；其他运动显示速度；力量训练或普拉提等运动的距离则显示 “不适用”。

每个字段名都包含单位（resting_hr_bpm、distance_km、sleep_score_0_100）。 Garmin 没有记录的值会显示为 “not recorded”，而不是零。

Garmin Personal API 不提供的内容

• 只读： 无法向手表发送任何内容，也无法向 Garmin Connect 写入数据。
• 不可用： 训练准备度、训练状态、急性／慢性负荷、VO2 max、 装备和设备信息。工具会注明“Garmin Personal API 未提供”，不会猜测。
• 数据工具每次查询最多覆盖 90 天，洞察工具最多覆盖 366 天；服务会拆分请求，以符合 Garmin 自身的限制。

隐私和安全

• 在你的电脑上运行。只与 Garmin 通信。没有数据库，也没有遥测数据。
• 你的 AI 应用会根据其服务提供商的条款，将工具结果发送给其 AI 模型。
• 你的密钥绝不会出现在工具结果、日志或错误信息中。
• 你可以随时在 Garmin Connect 中删除密钥，立即切断访问权限。

详情：PRIVACY.md · THREAT_MODEL.md · 报告漏洞：SECURITY.md

使用 Garmin API 受 Garmin 条款约束：密钥仅供你个人使用，不得分享。

故障排除

• **“Garmin rejected your Personal API key”：**密钥已过期或已删除。请创建新密钥， 然后重新执行步骤 3。Garmin 会在密钥到期前约一周发送提醒邮件。
• **AI 应用看不到工具：**完全重启应用。在 macOS 上，如果找不到 uvx，请使用其完整路径（在终端中运行 which uvx），并将其设为 command。
• 自行检查连接： uvx ownmetrics-mcp status

构建方式

本项目采用规范驱动开发。SPEC.md 列出了带编号的需求和不可妥协的规则；每项需求都对应 TRACEABILITY.md 中的测试，CI 会在每次更改时重新生成并检查该文件。 贡献也遵循相同流程：请参阅 CONTRIBUTING.md。

本项目基于 Garmin 官方的 connect-personal-api-python 客户端和 Model Context Protocol Python SDK 构建。

许可证

MIT