项目状态（已退役）
fitbit-mcp 已停止维护（Retired），官方建议改用 google-health-mcp。原因是 Fitbit Web API 将于 2026 年 9 月 30 日关停，Fitbit 也已停止接受新的应用注册，因此该包无法从头开始设置——注册个人应用这一步骤已无法完成。已安装的实例在关停日期前仍可继续使用。
google-health-mcp 通过 Google Health API 覆盖相同的测量数据，并新增 ECG 和心律不齐通知。它从 Google 读取历史数据，而不是从本包的缓存读取，因此无需迁移：安装后执行一次回填即可。
并非所有数据都能迁移。Fitbit 的活动目标和服务器端终身总计在 google-health-mcp 中没有对应项；Google 不提供的字段还包括心率区间、活跃分钟数细分、以范围而非单一数值表示的 VO2 max、睡眠效率、SpO2 高/低值以及 BMI。2026 年 9 月 30 日之后，本包也无法再获取这些数据，若想保留请在截止日期前备份 fitbit.db。
用途与定位
fitbit-mcp 是一个用于 Fitbit Web API 的 MCP 服务器，具备 OAuth PKCE 授权、本地 SQLite 缓存和趋势分析功能。它专为 Claude Code 及其他 MCP 客户端设计，将 Fitbit 数据同步到本地数据库，实现快速、离线查询——首次同步后无需再调用 API。
主要能力
- OAuth 2.0 PKCE：安全授权流程，无需 client secret。
- 本地 SQLite 缓存：同步一次，即时查询。
- 增量同步：仅获取上次同步以来的新数据。
- MCP 工具：同步、查询（缓存数据类型以及仅实时可用的 devices/lifetime/goals）和趋势分析。
- 实时模式：绕过缓存，直接查询 API。
- CLI：从命令行进行授权设置、同步和 JSON 导入。
- 速率限制处理：活动和食物日志同步在遇到 429 时会休眠并重试；其他数据类型会报告 rate_limited，并在下次同步时恢复。
环境要求
- Python 3.13+（CI 中已在 3.13 和 3.14 上测试）
- 拥有已注册个人应用的 Fitbit 开发者账号
使用方式
安装
可直接运行而无需安装，也可从克隆仓库进行开发安装。
2. 注册 Fitbit 应用
前往 dev.fitbit.com/apps 创建新应用，将 OAuth 2.0 Application Type 设为 Personal，Redirect URL 设为 http://localhost:8080，记录 Client ID（无需 client secret——PKCE 不使用它）。
3. 授权
该步骤会打开浏览器进行 Fitbit 登录，通过 PKCE 交换授权码，并将令牌保存在本地。令牌存放于 ~/.config/fitbit-mcp/fitbit_tokens.json，权限为 0600。访问令牌 8 小时后过期并自动刷新；刷新令牌在 90 天不活动后过期。
4. 注册到 Claude Code
5. 首次同步（可选）
查询工具在首次使用时会自动同步，可跳过此步骤。若要预填充缓存或同步更长的历史，可手动运行。
MCP 工具参考
查询工具会在每天每种数据类型的首次查询时自动同步。使用 live=True 可完全绕过缓存，直接从 API 获取。
所有查询工具接受以下通用参数：
- start_date：起始日期，格式为 YYYY-MM-DD、YYYY-MM 或 30d（相对）。默认：最近 30 天。
- end_date：结束日期，格式为 YYYY-MM-DD。默认：今天。
- live：若为 true，则从 Fitbit API 获取而非缓存（绕过自动同步）。
fitbit_get_exercises 还接受：
- exercise_type：按活动名称过滤（不区分大小写的子串匹配），如 "cycling"、"walk"、"run"。默认：所有类型。
同步工具将数据从 Fitbit API 同步到本地 SQLite 缓存。查询工具会在每天首次使用时自动调用，因此仅在需要更长历史或强制刷新时才需显式调用。
- data_types：要同步的类型：all、heart_rate、activity、exercises、sleep、weight、spo2、hrv、azm、breathing_rate、skin_temperature、core_temperature、cardio_fitness、food_log。逗号分隔。默认：all。
- days：首次同步的历史天数（默认：30）。后续同步为增量。
- since：可选 YYYY-MM-DD。从该日期起回填，忽略已缓存内容，覆盖增量恢复和 days 参数。
- until：可选 YYYY-MM-DD（含当日）结束日期；需与 since 一起使用。二者会重新获取并 upsert 恰好为 since..until 窗口的数据——用于修复缓存中间的缺口而无需重新拉取到今天的全部数据。
趋势分析工具基于缓存数据进行聚合趋势分析。
- data_type：分析类型：heart_rate、activity、exercises、sleep、weight、spo2、hrv、azm、breathing_rate、skin_temperature、core_temperature、cardio_fitness、food_log。默认：activity。
- period：聚合粒度：weekly、monthly、quarterly。默认：monthly。
- start_date：起始日期。默认：最近 12 个月（365 天）。
- end_date：结束日期。默认：今天。
- compare：比较两个时期：last_30d vs previous_30d、2026-03 vs 2026-02、2026-Q1 vs 2025-Q4。设置后，period/start_date/end_date 将被忽略。
授权范围
设置过程中会请求以下 Fitbit API 范围。这些是所有工具所需的范围。如果只需要子集，可在 setup 前编辑 config.py 中的 FITBIT_SCOPES。从更小范围集升级后，请重新运行 fitbit-mcp auth 以重新授权。
环境变量
路径可通过环境变量覆盖。
离线 / 仅缓存模式
默认情况下，服务器按需自动同步，查询工具无需 cron 任务即可获取最新数据。设置 FITBIT_MCP_OFFLINE=1 可将其作为纯缓存读取器运行：
- 无需 Fitbit 凭据——服务器从不接触令牌文件。
- 不进行实时 API 调用。自动同步禁用，live=True、仅实时工具（fitbit_get_devices、fitbit_get_lifetime_stats、fitbit_get_goals）和 fitbit_sync 会返回明确的“离线模式”消息，而不是调用 API。
- 查询工具提供本地 SQLite 缓存中的内容。响应会标记 "offline_mode": true。
多设备场景：一台主机通过 cron/systemd 运行 fitbit-mcp sync 写入共享数据库；其他主机设置 FITBIT_MCP_OFFLINE=1 并将 FITBIT_MCP_DB_PATH 指向同一缓存，仅做读取。这样 Fitbit OAuth 令牌（一次性、轮换）只由一台主机持有，避免刷新冲突。
CI 和隐私：在无网络访问、无凭据的情况下运行查询。
保持缓存新鲜此后由同步主机负责。取消设置 FITBIT_MCP_OFFLINE 可恢复按需自动同步。
速率限制
Fitbit API 允许每小时 150 次请求。活动和食物日志同步在遇到 429 时会休眠并自动重试；日期范围类数据类型则将该次同步标记为 rate_limited，并在下次运行时继续。需注意：
- 活动和食物日志同步每天使用 1 次 API 调用（没有日期范围端点）
- 首次 30 天的同步会各消耗约 30 次/小时的配额
- 心率、睡眠、体重、SpO2、HRV、AZM、呼吸率、皮肤温度、核心温度和心肺健康使用日期范围端点，效率高得多
- 使用 live=False（默认）从缓存查询，完全避免 API 调用
数据保护
项目包含预提交钩子（scripts/check-no-data.sh），防止意外提交：
- 数据库文件（.db、.db-journal、*.db-wal）
- 配置/凭据（config/*.json）
- 大文件（>100KB）
克隆后安装该钩子。
导入已有数据
如果已有 JSON 格式的 Fitbit 数据（例如来自之前的导出或脚本），可批量导入。预期文件名：heart_rate.json、activity.json、exercises.json、sleep.json、weight.json、spo2.json、hrv.json。JSON 格式参见 src/fitbit_mcp/importer.py。导入目前仅覆盖这七种类型；较新的类型（AZM、呼吸率、皮肤/核心温度、心肺健康、食物日志）通过 sync 而非 import 填充。
开发
开发设置、测试工作流和预提交钩子参见 CONTRIBUTING.md。变更记录在 CHANGELOG.md 中。许可证：GPL-3.0-or-later。
限制与注意事项
- 该项目已退役，Fitbit Web API 将于 2026 年 9 月 30 日关停，且无法新注册应用。
- 部分数据（活动目标、终身总计、心率区间、活跃分钟数细分、VO2 max 范围、睡眠效率、SpO2 高/低、BMI）在替代方案中也没有对应项。
- 授权范围、环境变量名称、CLI 子命令等具体细节需参考官方文档，本介绍未逐一列出。
