Garmin Local MCP

garmin-local-mcp

本地优先的 Garmin 数据仓库，配备分析级 MCP 服务。 同步一次，永久分析，即使 API 宕机也不受影响。

无需 Garmin 账户即可试用

如果你没有 Garmin 设备，或者只想在提供凭据前看看工具会返回什么，可以填充一个合成数据存储：

pip install garmin-local-mcp
garmin-local-mcp --data-dir ~/.garmin-mcp-demo demo
garmin-local-mcp --data-dir ~/.garmin-mcp-demo serve

这会为每张表生成 180 天的数据，然后通过 MCP 提供这些数据。无需 登录、无需网络，也无需账户。

这些数据是生成的，并非记录所得，但也不是随机数据。一个潜在的 恢复因子会推动 HRV 上升，同时使静息心率下降；训练负荷会提高 次日 的静息心率；范围中间设有一个为期六天的疾病窗口，并特意 缺失了几晚睡眠数据。睡眠时间体现了植入的昼夜类型（MCTQ MSFsc 03:45，其中工作日早晨受闹钟限制，而自由日夜间入睡更晚、睡眠时间更长），睡眠评分则会随着自然醒来时间偏移而下降。因此，分析工具能够找到真实规律。在完整的 180 天范围内（具体数值会随结束日期略有变化，因为训练日取决于星期几）：

提问	返回结果
correlate(hrv, resting_hr)	−0.4 至 −0.6，呈现真实的负相关关系
correlate(training_load, resting_hr, scan_lags=True)	滞后 0 时接近 0，滞后 1 时为 +0.4 至 +0.65（90 至 100 个训练日，经 15 个已扫描滞后的校正后仍显著）：影响发生在次日
anomalies()	疾病窗口，会同时在静息心率、HRV、皮肤温度、睡眠评分和压力指标上标记出来
gaps()	缺失的睡眠夜晚
circadian()	MSFsc 与植入的 03:45 相差不超过 10 分钟，昼夜节律醒来时间约为 07:45，证据为 supportive（两个留出折所允许的最高等级）

分析工具默认使用最近 30 天的数据，因此不会涵盖疾病窗口；应查询整个范围（demo 会打印该范围）。在较短的时间窗口内，滞后扫描可用数据有限；如果最强滞后在计入全部 15 个滞后后不显著，correlate 会在其 note 中说明这一点。

这些存储中的 sync_status 会报告 demo_store: true，因此助手不会将生成的数值说成真实测量结果。生成器具有确定性——--seed 可精确复现存储，--days 可更改范围。demo 不会覆盖它未生成的数据库。

为什么还要做一个 Garmin MCP？

大多数 Garmin MCP 服务都是对 Garmin 非官方 API 的轻量实时封装。AI 助手提出的每个问题都会变成一个或多个实时 API 调用，并返回大量原始 JSON 数据（单个原始睡眠响应约为 230 KB），因此像“我的睡眠与训练负荷有什么关联？”这样涉及数月数据的问题，查询成本很高。

这种设计如今已不再是唯一选择。Garmin 于 2026 年 3 月更改认证方式，导致生态系统瘫痪数周，此后不少项目增加了本地存储，规模最大的服务还会在服务端计算训练负荷和 HRV 趋势。如今，数据所有权和服务端分析都已是竞争激烈的领域。但以下三点仍未被满足：

• 给出睡眠时间建议前先进行验证。 circadian 根据手表记录的睡眠时间（经过睡眠债校正的慕尼黑型时问卷中点睡眠时间）估算你的生物钟类型，以及适合你的起床时间；它会为两者分别给出 80% 区间，并检查在其他合理设置下答案会有多大变化。随后，它会检验：在模型未见过的夜晚，接近该时间起床是否确实与更高的 Garmin 分数相关，以及这种关联是否超出了睡眠时长和作息规律性所能解释的范围；若并非如此，也会明确说明。单独报告生物钟类型并非新鲜事：包括至少一个 MCP 服务在内的其他工具，也会根据可穿戴设备的睡眠数据报告 MCTQ 风格的生物钟类型。我尚未发现其他工具会为答案给出不确定性范围，或在样本外进行验证。参见睡眠时间与生物钟类型。
• 无需登录即可导入。 一个独立解码器可读取手动导出的 Garmin 未公开 wellness FIT 消息包（睡眠评分、HRV、皮肤温度、睡眠阶段、小睡），完全不需要凭据。其他服务会解析 FIT 活动文件；我尚未发现其他服务能解码 wellness 导出文件。这是这里唯一一种在 Garmin 认证失效时仍能继续工作的导入方式。
• 考虑时滞的相关性分析。 可计算任意两项指标之间的 Pearson 和 Spearman 相关系数，并扫描 -7 到 +7 天的时滞，因此“训练负荷会在次日提高我的静息心率吗？”这样的问题也能得到答案。

其余设计都源于保留自己的数据副本：

• 同步一次，永久分析。 增量同步到本地数据仓库：不可变的原始 JSON 快照加 SQLite 数据库，存放在你拥有的目录中。
• 精简的响应。 趋势、相关性、基线和异常检测均在本地计算，并以小型列式表格返回。典型响应小于 2 KB（内容最丰富的 circadian 也小于 3 KB），不会让模型的上下文被数据淹没。
• 离线韧性。 API 故障只会暂停新的同步。所有针对已同步历史数据的查询仍可正常运行，FIT 导入也能继续补齐数据缺口。
• 精选工具。 13 个可组合的工具，而非 110 个。

	garmin-local-mcp	其他大多数 Garmin MCP
无需认证的导入方式	有（导入 wellness FIT 包）	无
考虑时滞的相关性分析（-7 到 +7 天）	有	无
生物钟类型与起床时间建议，并在未见过的夜晚数据上验证	有（区间、稳定性检查、滚动留出验证）	少数会报告生物钟类型；未发现有验证功能的
响应大小控制	精简的列式表格，通常小于 2 KB	原始数据；规模最大的服务文档建议跳过其 50–500 KB 的详情端点
API 故障后仍可离线运行	可以，支持分析和 FIT 导入	各不相同；部分服务会保留本地缓存
由你拥有的本地数据存储	有（原始 JSON + SQLite）	现在也有好几个支持
工具数量	13 个精选工具	18 到 148 个

快速入门

需要 Python 3.12+。

pip install garmin-local-mcp

也可以通过 uv 运行，无需安装：

uvx garmin-local-mcp --help

1. 登录一次（支持 MFA；令牌会保存在本地，因此之后运行时无需输入密码）：

garmin-local-mcp login

**2. 回填历史数据。**同步支持续传，可安全中断，并会限制请求频率，以免给 Garmin 的服务造成负担。一年的历史数据大约需要 1,800 次请求；回填较长时间范围的数据时，请启动同步并让它持续运行（适合在夜间运行）。如果遇到速率限制或中断，请重新运行相同的命令，它会从上次停止的位置继续。

garmin-local-mcp sync --from 2026-01-01

3. 将 MCP 服务注册到客户端（Claude Desktop、Cursor 和其他客户端的设置请参阅客户端设置）：

claude mcp add --scope user garmin -- garmin-local-mcp serve

**4. 提出问题。**以下是 Claude 现在可以通过一两次工具调用，从本地数据仓库中回答的问题示例：

• “我的睡眠评分与次日静息心率有怎样的相关性？”
• “本季度有哪些异常的 HRV 日期？”
• “显示过去 3 个月每周的训练负荷与睡眠情况。”

客户端设置

该服务使用 stdio 通信，因此可与任何 MCP 客户端配合使用。请先执行 pip install garmin-local-mcp（或使用下方的 uvx 变体，除 uv 外无需安装任何内容）。

Claude Code

claude mcp add --scope user garmin -- garmin-local-mcp serve

**Claude Desktop，一键安装：**从最新版本下载 garmin-local-mcp-x.y.z.mcpb，然后在 Claude Desktop 中打开 Settings > Extensions > Advanced settings，点击 "Install Extension…"，并选择该文件。PATH 中需要有 uv；该扩展会通过 uvx 从 PyPI 安装并运行服务，因此无需手动设置 Python。如果安装对话框提示缺少 Python >=3.12，可以忽略：uv 会自行配置解释器。

Claude Desktop，手动安装（依次打开 Settings、Developer、Edit Config；将以下内容添加到 claude_desktop_config.json）：

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-local-mcp",
      "args": ["serve"]
    }
  }
}

Cursor（~/.cursor/mcp.json，或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-local-mcp",
      "args": ["serve"]
    }
  }
}

任何其他 stdio 客户端／无需本地安装（需要 uv）：

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

注意：login 和初始回填 sync 是命令行步骤（请参阅快速入门）；MCP 服务本身不会提示输入凭据。

13 个工具

工具	功能
auth_status	检查是否存在已存储的 Garmin Connect 令牌（同步前或发生身份验证错误后使用）。
sync	从 Garmin Connect 获取最多 60 天的数据并存入本地存储（默认：截至昨天的最近 30 天；大型历史数据补录应使用 CLI）。
sync_status	按表查看本地数据覆盖范围、上次同步时间和待处理的同步错误。
get_day	查看单日合并数据：健康状况、睡眠、HRV、训练状态、表现评分、活动和数据质量标记。
query_metrics	查询两个日期之间一个或多个指标的列式时间序列，支持按日／周／月聚合和可选统计信息。
correlate	计算两个指标之间的 Pearson／Spearman 相关性，支持按天滞后，并可选择扫描 -7..+7 的滞后值。
baselines	计算指标在滚动时间窗口（默认 28 天）内的个人均值 +/- 标准差区间，用于判断该用户的正常水平。
anomalies	查找异常日（z 分数偏差）和持续连串异常（连续 5 天或以上位于均值同一侧）。
list_activities	以紧凑表格按时间倒序列出近期活动，可按类型、日期范围和最小距离筛选。
get_activity	获取某项活动存储的完整摘要行（仅摘要字段，不含 GPS 或采样数据流）。
gaps	按表列出缺失日期和未解决的同步错误，以便在得出结论前找出值得重新同步的数据缺口。
import_fit	无需身份验证，离线导入手动导出的 Garmin 健康状况 FIT 数据包。
circadian	昼夜类型（MCTQ）、睡眠需求和推断出的起床时间窗口，均附带 80% 区间；另提供样本外证据，说明该时间窗口是否与较高的 Garmin 评分相关。参见 睡眠时间与昼夜类型。

只有 sync 和 import_fit 会写入数据，且写入范围仅限数据目录。 服务不会发出提示：身份验证问题会以结构化错误的形式返回，并附上指向登录 CLI 的提示。

可用的指标名称包括 resting_hr、sleep_score、hrv、steps、 stress_avg、body_battery_high、skin_temp_dev_c、vo2max、fitness_age、 achievable_fitness_age、training_load、endurance_score、hill_score、 readiness_score、race_5k_s，以及睡眠时间相关指标 sleep_onset_min、 wake_time_min 和 mid_sleep_min（以起床日期午夜起算的分钟数，因此 23:00 就寝时间为 −60），还有约 35 个其他指标；如果工具收到未知名称， 会返回完整列表。

表现评分

Garmin 定期更新的体能评分存储在独立的 performance 表中： 耐力评分、爬坡评分（含耐力和力量子评分）、 训练准备度（评分、等级、恢复时间），以及 5 公里、 10 公里、半程马拉松和全程马拉松的成绩预测（均以秒为单位）。

这些数据按 Garmin 自身的更新节奏变化，而非每日更新，因此 performance 会有意排除在 gaps 之外——某天没有新的耐力评分 属于正常情况，并非数据缺口。只有符合条件的跑步活动结束后，比赛成绩预测和爬坡评分才会更新；因此，如果某人的训练主要包括徒步、骑行或力量训练，出现长时间的空值是意料之中的。

睡眠时间与生物钟型

circadian 根据存储中已有的睡眠开始和结束时间，回答“我的生物钟希望我什么时候醒来？”。它会返回三个不同的数值，每个数值都附带通过按周分块自助法得出的 80% 区间：

1. 生物钟型（msf_sc）。 慕尼黑生物钟问卷中的指标：自由日的睡眠中点，并针对偿还工作日睡眠债而额外补觉的时间进行修正。标记为 early（03:30 之前）、intermediate 或 late（04:30 之后）；这些区间是近似值，具体数值才是主要指标。
2. 睡眠需求。 你自由日夜间的平均睡眠时长，除非你传入 sleep_need_min。同时会报告 Garmin 分数趋于平稳时对应的范围，作为交叉核对。
3. 符合生物钟的醒来时间窗口。 msf_sc + sleep_need / 2。这是推断值，并非 MCTQ 的输出。没有补觉时，它就是你自由日平均醒来的时间；有补觉时，则是在该时间基础上提前半个补觉时长。

接下来，它会将推断结果与实际情况进行核对：

• 稳定性。 分别使用 90、180 和 365 天的数据、睡眠中点的平均值和中位数，以及三种旅行过滤范围重新计算估值。stability: low 通常意味着你的作息发生了变化；请传入变化之后的 start。
• 证据。 在滚动留出验证中（用 120 天训练，再测试接下来的 30 天），它会比较仅根据睡眠时长预测的模型与加入距离符合生物钟的醒来时间这一因素的模型，并使用另一组模型控制作息规律性。证据等级为 consistent、supportive、suggestive 或 unsupported。这些等级描述的是这种模式在未见过的夜晚中持续出现的程度，不代表统计显著性；证据至少需要 180 天的历史数据。
• 无法说明的内容。 准备度和睡眠分数是 Garmin 自有的综合分数，并非生理测量结果。最有力的结论是：在模型未见过的夜晚，醒来时间接近你的窗口与较高的 Garmin 分数相关，且这种关联无法仅由睡眠时长和规律性解释。这并不能证明醒来时间会改变生理状况。

如果公式得出的结果与你过去的分数相差超过 30 分钟，该工具会保留两者，并建议在二者之间进行为期 21 晚的实验，而不是将它们平均后消除差异。自由日默认是周六和周日早晨（free_days 可更改这一设置）；如果你在自由日设置了闹钟，计算出的生物钟型会比你的生物钟更早。结果范围内的夏令时变化会列出，并使用配置的 timezone 或主机的时区。轮班工作者（主要在白天睡觉）会获得作息节律和生物钟型结果，但不会获得醒来时间窗口。

数据布局与所有权

所有数据都存放在你拥有的一个目录中（默认是 ~/.garmin-mcp，可通过 GARMIN_MCP_DATA_DIR 环境变量或 --data-dir 覆盖）：

~/.garmin-mcp/
├── config.toml                                  # optional settings
├── tokens/                                      # Garmin Connect session tokens
├── raw/daily/YYYY/YYYY-MM-DD/<endpoint>.json    # immutable raw API snapshots
├── raw/activities/<activity_id>.json            # one snapshot per activity
└── garmin.db                                    # SQLite warehouse

原始 JSON 快照是事实来源，绝不会被覆盖。SQLite 数据库是派生出的、可重建的索引：garmin-local-mcp reparse 会完全离线地根据原始快照重建数据库，这是应对架构演进和解析器修复的通用后备方案。你的数据永远不会离开你的计算机。

数据质量说明

Garmin 手表会报告一个临时的设备端静息心率，在采样稀疏的夜晚，该数值可能与 Garmin Connect 最终确认的值相差很大。一个真实案例：手表设备端报告为 69 bpm，而 Garmin Connect 后来将同一晚的值确认为 56 bpm。

本项目通过以下两种方式处理：

• API 同步会保存 Garmin Connect 最终确认的值。
• FIT 导入器会将设备端临时值与夜间心率最低值交叉核对。若静息心率比夜间最低采样值高出 10 bpm 以上，说明手表实际上从未观测到这个数值；该数值会被标记（rhr_far_above_hr_floor）并暂不保存，将该字段留给 API 回填，避免存入误导性数值。

睡眠阶段记录稀疏也会以相同方式标记（sparse_sleep_stage_logging），并且标记会显示在 get_day 中，让分析层知道哪些数值值得信任。

离线／回退操作指南

如果 Garmin 再次导致非官方 API 无法使用（之前发生过）：

1. 所有分析功能都能继续使用。 所有查询、相关性、基线、异常和缺失工具都会基于已同步到本地的历史数据运行。只有新的同步会暂停。
2. 无需身份验证，继续导入数据。 从 Garmin Connect 网站下载每日 FIT 数据包，并在本地导入（具体步骤见下文）。 garmin-local-mcp import-fit <folder> 可在无需身份验证的情况下解码数据包并补齐缺失日期。FIT 来源的行不会覆盖 API 来源的行（除非传入 --force）。
3. 社区找到解决办法后恢复同步。 关注 python-garminconnect 项目以获取修复方案，然后升级并再次运行 garmin-local-mcp sync。得益于可恢复的同步状态，它会从停止的位置准确接续。

逐步下载健康数据包

1. 在任意浏览器中登录 connect.garmin.com。

2. 直接前往 https://connect.garmin.com/app/settings/accountInformation （也可以点击右上角的头像，然后点击 Settings，再点击左侧边栏中的 Account Information）。

3. 滚动到页面底部的 Export Wellness Data 部分（“下载特定日期的健康 FIT 文件。这些文件包含步数、睡眠、压力、HRV 等数据。”）。

4. 在 Date 字段中选择日期，然后点击 Export。浏览器会下载该日期对应的一个小型 zip 文件，其中包含约 12 到 15 个二进制 .fit 文件（*_WELLNESS.fit、*_SLEEP_DATA.fit、*_HRV_STATUS.fit、*_SKIN_TEMP.fit、*_METRICS.fit 等）。

5. 将其解压到一个文件夹中并运行：

   garmin-local-mcp import-fit "path/to/unzipped/folder"
   

6. 对每个缺失日期重复此操作（每个日期下载一个数据包）。gaps 工具或 garmin-local-mcp status 会告诉你哪些日期需要补齐。

有两点值得注意：

• 夜间睡眠归属于醒来的日期。 若你睡到今天早上才醒来，要获取昨晚的睡眠数据，请导出昨天的日期，也就是你醒来的日期。
• 这种按日导出会立即完成，与 Garmin 的完整账户导出不同。完整账户导出是同一页面上的“Data Management”链接，提供批量归档，可能需要数天才能通过电子邮件收到，而且不是 import-fit 所需的格式。

配置

数据目录中的可选 config.toml：

键	默认值	含义
timezone	系统时区	用于计算同步范围中“昨天”的 IANA 名称（例如 America/Denver）
units	metric	metric 或 statute
request_delay_seconds	1.0	同步期间 API 请求之间的延迟
baseline_window_days	28	baselines 工具的默认回溯窗口

环境变量：

变量	含义
GARMIN_MCP_DATA_DIR	覆盖数据目录（默认 ~/.garmin-mcp）
GARMINTOKENS	覆盖令牌存储位置（默认 <data_dir>/tokens）
GARMIN_EMAIL / GARMIN_PASSWORD	可选，用于非交互式重新登录；设置后，garmin-local-mcp login 会跳过提示（如果你的账户要求多重身份验证，仍可能提示）

开发

python -m venv .venv
.venv/bin/pip install -e .[dev]     # Windows: .venv\Scripts\pip install -e .[dev]
pytest
ruff check .

测试套件完全离线运行，使用经过脱敏的 JSON 固定数据和小型 FIT 样本；CI 不会访问实时 API。

免责声明

本项目与 Garmin Ltd. 无关联，未获其认可或支持。 本项目使用社区提供的 python-garminconnect 库，通过你自己的凭据访问你自己的数据。Garmin 的 API 并非官方 API，可能随时变更或失效；发生这种情况时，已同步的 历史数据仍可正常使用，FIT 导入路径也会继续工作。

所有数据都保留在你的设备上。本项目不会向外发送任何数据：没有遥测、没有 第三方服务，也没有云端服务。请像对待个人健康记录一样妥善保管你的数据目录，并且永远不要将其提交到代码仓库。

许可证

MIT