fitbit-mcp

fitbit-mcp

已停止维护。请改用 google-health-mcp。

Fitbit Web API 将于 2026 年 9 月 30 日关闭。Fitbit 也已停止接受新的应用注册，因此无法再从头设置此软件包：下文的第 2 步需要已注册的个人应用，现在已无法创建新应用。现有安装在关闭日期之前仍可正常使用。

google-health-mcp 通过 Google Health API 提供相同的测量数据，并新增 ECG 和心律不齐通知。它从 Google 读取历史数据，而非读取此软件包的缓存，因此无需迁移：安装后运行一次完整回填即可。

并非所有数据都能迁移。Fitbit 的活动目标和服务器端终身累计数据在 Google Health API 中没有对应项；Google 不提供的字段还包括心率区间、活动分钟数明细、以范围而非单一数值表示的 VO2 max、睡眠效率、SpO2 最高值和最低值，以及 BMI。9 月 30 日之后，此软件包也将无法再获取这些数据；如果想保留它们，请提前复制 fitbit.db。

适用于 Fitbit Web API 的 MCP 服务，支持 OAuth PKCE、本地 SQLite 缓存和趋势分析。

专为 Claude Code 和其他 MCP 客户端设计。将 Fitbit 数据同步到本地数据库，以便快速离线查询——完成初始同步后无需调用 API。

功能

• OAuth 2.0 PKCE - 安全的身份验证流程，无需客户端密钥
• 本地 SQLite 缓存 - 同步一次，即可即时查询
• 增量同步 - 仅获取上次同步后新增的数据
• MCP 工具 - 同步、查询（缓存的数据类型，以及仅支持实时查询的设备／终身累计数据／目标）和趋势分析
• 实时模式 - 绕过缓存，直接查询 API
• CLI - 通过命令行进行身份验证设置、同步和 JSON 导入
• 速率限制处理 - 活动和饮食日志同步会在遇到 429 时等待并重试；其他数据类型会报告 rate_limited，并在下次同步时继续

数据类型

工具	数据
fitbit_get_heart_rate	静息心率、心率区间
fitbit_get_activity	步数、卡路里、活动分钟数、距离
fitbit_get_exercises	运动记录（名称、时长、心率、卡路里）
fitbit_get_sleep	时长、睡眠效率、睡眠阶段
fitbit_get_weight	体重、BMI、体脂率
fitbit_get_spo2	血氧饱和度（平均值／最小值／最大值）
fitbit_get_hrv	心率变异性（RMSSD）
fitbit_get_azm	活动区间分钟数及各区间明细
fitbit_get_breathing_rate	夜间每分钟呼吸次数
fitbit_get_skin_temperature	夜间皮肤温度变化（相对基线的摄氏度数）
fitbit_get_core_temperature	手动记录的核心（体内）温度读数（摄氏度）
fitbit_get_cardio_fitness	VO2 Max／心肺适能评分
fitbit_get_food_log	每日食物卡路里和饮水量
fitbit_get_devices	已配对设备、电池电量、上次同步时间（实时）
fitbit_get_lifetime_stats	累计总量和个人最佳记录（实时）
fitbit_get_goals	用户设置的每日／每周活动目标（实时）
fitbit_trends	汇总平均值（按周／月／季度）

要求

• Python 3.13+（已在 CI 中使用 3.13 和 3.14 测试）
• Fitbit 开发者账号，并注册个人应用

设置

1. 安装

pip install fitbit-mcp

也可以不安装，直接运行：

uvx fitbit-mcp

如需从克隆的仓库进行开发：

pip install -e ".[dev]"

2. 注册 Fitbit 应用

1. 前往 dev.fitbit.com/apps 并创建新应用
2. 将 OAuth 2.0 Application Type 设置为 Personal
3. 将 Redirect URL 设置为 http://localhost:8080
4. 记下你的 Client ID（无需客户端密钥，PKCE 不使用它）

3. 验证身份

fitbit-mcp auth

此操作会打开浏览器供你登录 Fitbit，通过 PKCE 交换授权码，并在本地保存令牌。

令牌存储在 ~/.config/fitbit-mcp/fitbit_tokens.json 中，权限为 0600。访问令牌会在 8 小时后过期，并自动刷新。刷新令牌在闲置 90 天后过期。

4. 注册到 Claude Code

claude mcp add -s user fitbit -- fitbit-mcp

5. 首次同步（可选）

查询工具会在首次使用时自动同步，因此你可以跳过此步骤。若要预先填充缓存，或同步更长时间范围的历史数据，请运行：

fitbit-mcp sync --days 30

CLI 用法

fitbit-mcp              Start the MCP server (stdio transport)
fitbit-mcp -V, --version  Print the installed package version
fitbit-mcp auth         Interactive OAuth setup
fitbit-mcp doctor       Check the setup and report what needs fixing
fitbit-mcp sync         Sync data to local cache
  --days N              Days of history for first sync (default: 30)
  --types TYPE,...      Data types to sync (default: all)
  --since YYYY-MM-DD    Backfill from this date, overriding the incremental
                        resume-from-last-sync cursor and --days
  --until YYYY-MM-DD    Inclusive end date for a --since backfill; together
                        they re-fetch exactly that window (e.g. to repair a
                        gap in the middle of the cache)
fitbit-mcp import       Import existing JSON data files
  --data-dir PATH       Directory containing JSON files

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_sync

将 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。两者一起使用时，会重新获取并写入恰好 since..until 的时间范围内的数据；可用于修复缓存中间的缺失数据，而无需重新获取截至今天的全部数据。

fitbit_trends

基于缓存数据进行汇总趋势分析。

• 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。

OAuth 权限范围

设置期间会请求以下 Fitbit API 权限范围：

权限范围	访问的数据
activity	步数、卡路里、活跃分钟数、距离、AZM、终身统计数据、目标
heartrate	静息心率、心率区间、HRV
sleep	睡眠时长和阶段
weight	体重、BMI、体脂率
oxygen_saturation	SpO2（血氧）
profile	用户资料（用户 ID、显示名称）
respiratory_rate	夜间呼吸频率
temperature	皮肤温度变化和手动记录的核心体温
cardio_fitness	VO2 Max / 有氧健身评分
nutrition	每日食物卡路里和饮水记录
location	已记录运动的 GPS 数据
settings	已配对设备（电池电量、上次同步时间）

所有工具都需要这些权限范围。如果只需要其中一部分，请在设置前编辑 config.py 中的 FITBIT_SCOPES。从较小的权限范围集升级后，请重新运行 fitbit-mcp auth 以重新授权。

配置

可通过环境变量覆盖路径：

变量	默认值	说明
FITBIT_MCP_CONFIG_DIR	~/.config/fitbit-mcp/	OAuth 凭据目录
FITBIT_MCP_DB_PATH	~/.local/share/fitbit-mcp/fitbit.db	SQLite 数据库路径
FITBIT_MCP_OFFLINE	未设置	若为真值（1、true、yes、on），则以仅读取缓存的模式运行：无需凭据，也不会进行实时 API 调用。见下文。

离线 / 仅读取缓存模式

默认情况下，服务会按需自动同步，因此查询工具无需 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 标记。

典型用途：

• 多设备设置——一台主机针对共享数据库运行 fitbit-mcp sync（通过 cron/systemd）；其他主机设置 FITBIT_MCP_OFFLINE=1，并将 FITBIT_MCP_DB_PATH 指向同一缓存，仅进行读取。这样，Fitbit OAuth 令牌（单次使用、轮换更新）由唯一一台主机持有，从而避免刷新冲突。
• CI 和隐私保护——在没有网络访问和凭据的情况下运行查询。

此时由负责同步的主机确保缓存保持最新。取消设置 FITBIT_MCP_OFFLINE 即可恢复按需自动同步。

速率限制

Fitbit API 每小时允许 150 次请求。活动和饮食记录同步遇到 429 时会自动休眠并重试；日期范围数据类型则会将该次同步标记为 rate_limited，并在下次运行时继续。请注意：

• 活动和饮食记录同步每天使用 1 次 API 调用（没有可用的日期范围端点）
• 对任一类型进行 30 天的初始同步，会占用约 30 次每小时 150 次的配额
• 心率、睡眠、体重、SpO2、HRV、AZM、呼吸频率、皮肤温度、核心体温和有氧健身使用日期范围端点，效率高得多

使用 live=False（默认值）从缓存查询，可完全避免 API 调用。

数据安全

此项目包含一个 pre-commit 钩子（scripts/check-no-data.sh），可防止意外提交以下内容：

• 数据库文件（*.db、*.db-journal、*.db-wal）
• 配置 / 凭据（config/*.json）
• 大型文件（>100KB）

克隆后安装：

ln -sf ../../scripts/check-no-data.sh .git/hooks/pre-commit

导入现有数据

如果你有 JSON 文件格式的现有 Fitbit 数据（例如来自之前的导出或脚本），可以批量导入：

fitbit-mcp import --data-dir /path/to/json/files/

预期文件名：heart_rate.json、activity.json、exercises.json、sleep.json、weight.json、spo2.json、hrv.json。有关预期的 JSON 格式，请参阅 src/fitbit_mcp/importer.py。目前导入仅涵盖这七种类型；较新的类型（AZM、呼吸频率、皮肤／核心温度、有氧适能、饮食记录）通过 sync 填充，而非导入。

贡献

有关开发环境设置、测试工作流和 pre-commit 钩子，请参阅 CONTRIBUTING.md。变更记录见 CHANGELOG.md。

许可证

GPL-3.0-or-later