Local-first Garmin 数据仓库，搭配分析级 MCP 服务器。同步一次，即可永久分析，即使在 API 中断时也能正常工作。
用途
本工具旨在解决多数 Garmin MCP 服务器仅作为非官方 API 的实时薄封装所导致的问题：每次问询都会产生大量实时 API 调用返回原始 JSON（单次原始睡眠响应约 230 KB），使得多个月份的问题（如“我的睡眠如何与训练负荷相关？”）查询成本高昂。本工具将数据存入本地仓库，分析在本地完成，返回紧凑的列式表格，避免占用模型上下文。
主要能力
· 增量同步到本地数据仓库：不可变的原始 JSON 快照加 SQLite 数据库，存放于用户自有目录。 · 紧凑响应：趋势、相关性、基线和异常检测均在本地计算，典型响应小于 2 KB（最丰富的 circadian 也小于 3 KB）。 · 离线韧性：API 中断仅暂停新同步，已同步历史的所有查询继续工作，FIT 导入可填补空缺。 · 精选工具：13 个可组合工具。 · 睡眠时间与生物钟类型分析：基于手表睡眠时间估算生物钟类型（MCTQ MSFsc）、睡眠需求及符合昼夜节律的唤醒窗口，并检验该推断是否与实际 Garmin 评分相关。 · 无需登录的 FIT 导入：独立解码 Garmin 未公开的 wellness FIT 消息（睡眠评分、HRV、皮肤温度、睡眠阶段、小睡），无凭证要求，在 Garmin 认证中断时仍可用。 · 滞后相关性分析：计算任意两个指标之间的 Pearson 和 Spearman 相关性，并扫描 -7 到 +7 天的滞后，回答问题如“训练负荷是否使次日静息心率升高”。
使用方式
需 Python 3.12+。可通过 pip 安装（pip install garmin-local-mcp），也可使用 uvx 直接运行。
- 首次登录（支持 MFA，令牌本地持久化，后续运行无需密码）。
- 回填历史：同步可恢复，安全中断，对 Garmin 服务器限流。一年历史约 1800 次请求，长时间回填可隔夜运行，若被限速或中断，重新运行同一命令即可恢复。
- 向客户端注册 MCP 服务器（支持 Claude Desktop、Cursor 等，服务器使用 stdio，任何 MCP 客户端均可）。
- 提问：例如“我的睡眠评分如何与次日静息心率相关？”“本季度我的异常 HRV 日期有哪些？”“展示过去 3 个月每周训练负荷与睡眠对比”。
FIT 导入步骤：登录 Garmin Connect，前往账户信息页面底部“Export Wellness Data”，选择日期导出每日 zip 包，解压后运行 garmin-local-mcp import-fit "路径"，可重复填补缺失日期。
适用场景
· 希望长期保留并分析个人 Garmin 数据，不愿受 API 不稳定影响的用户。 · 需要跨数月进行趋势、相关性分析，且对模型上下文消耗敏感的场景。 · 在 Garmin API 中断时，仍希望通过手动导出 FIT 文件继续导入数据的用户。 · 不带 Garmin 账户也可通过合成数据（demo 命令）体验工具功能，合成数据非随机，包含可分析的潜在模式。
限制
· 需要 Python 3.12+ 或 uv。 · 登录和初始回填是 CLI 步骤，MCP 服务器本身从不提示凭证。 · 仅 sync 和 import_fit 会写入数据目录。 · 生物钟分析中的“证据”级别反映模式在未见夜晚的一致性，非统计显著性，且需要至少 180 天历史。 · Garmin 手表可能报告临时静息心率，与最终值差异大，本工具会标记并保留该字段供 API 回填。 · 性能评分（耐力、爬坡、准备度、比赛预测）按 Garmin 自身节奏更新，不参与空缺检测。 · 昼夜节律兼容唤醒窗口为推断，非 MCTQ 输出；不显示唤醒时间改变生理。 · 倒班工作者（白天主睡眠）仅获得节律和生物钟类型，无唤醒窗口。 · 本项目与 Garmin 无关联、未获认可。
