withings-mcp

withings-mcp

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

与其他 Withings MCP 服务相比，它的特点：

• 本地 SQLite 缓存，支持快速离线查询和历史趋势分析
• 增量同步——仅获取上次同步之后的新数据
• 广泛覆盖 Withings 数据：17 项身体成分指标，以及睡眠、每日活动、锻炼和 ECG/AFib
• 自动刷新 OAuth 令牌（访问令牌：3h，刷新令牌：1 年）
• 除 mcp 外零依赖（HTTP 使用标准库）
• Python 3.13+（已在 Linux、macOS 和 Windows 上通过 CI 测试 Python 3.13 和 3.14）

工具

工具	描述	数据来源
withings_sync	将 Withings API 的数据同步到本地缓存	实时 API -> SQLite
withings_get_body	身体成分（体重、脂肪率、肌肉、骨量、血压、SpO2）	本地缓存（过期时自动同步）
withings_get_sleep	睡眠摘要，或使用 detail=True 获取详细的睡眠阶段时间序列	缓存（摘要）/实时（详细数据）
withings_get_activity	每日步数、距离、卡路里、活动时长	本地缓存（过期时自动同步）
withings_get_workouts	锻炼记录，包含类型、时长、心率	本地缓存（过期时自动同步）
withings_get_heart	ECG 记录和 AFib 检测	实时 API（始终）
withings_get_devices	已连接设备及其电池状态	实时 API（始终）
withings_trends	周期平均值、每周/每月/每季度趋势及比较	本地缓存（过期时自动同步）

基于缓存的查询工具会在数据过期时自动同步，并接受 live=True 参数以绕过缓存，直接从 Withings API 获取数据。withings_get_heart 和 withings_get_devices 始终获取实时数据。withings_get_sleep(detail=True) 会返回逐分钟的睡眠阶段数据（实时获取，每次请求最多 7 天）。

前置条件

• Python 3.13+（已在 Linux、macOS 和 Windows 上通过 CI 测试 Python 3.13 和 3.14）
• uv（推荐）或 pip
• Withings 开发者账户和已注册的应用

安装

pip install withings-mcp

也可以使用 uvx withings-mcp 直接运行，无需安装。若要从克隆的代码库进行开发：

git clone https://github.com/partymola/withings-mcp.git
cd withings-mcp
uv venv --python 3.13 .venv
uv pip install -e .

设置

1. 注册 Withings 应用

1. 前往 https://developer.withings.com/dashboard
2. 创建新应用
3. 将回调 URL 设置为 http://localhost:8585
4. 记下 Client ID 和 Client Secret

2. 身份验证

.venv/bin/withings-mcp auth

这会打开浏览器以进行 Withings 授权。批准后，令牌会保存在本地的 config/ 中。

3. 在 Claude Code 中注册

claude mcp add -s user withings -- /path/to/withings-mcp/.venv/bin/withings-mcp

4. 首次同步

在 Claude Code 中说：“同步我的 Withings 数据”

这会运行 withings_sync 来填充本地缓存。之后的同步只会获取新数据。

如果遇到问题——例如没有出现预期的数据，或同步停止运行——请运行 withings-mcp doctor。它会报告实际使用的路径和凭据，以及需要修复的内容，且不会发出 API 请求。

你也可以在不使用 MCP 客户端的情况下，通过命令行同步：

.venv/bin/withings-mcp sync                      # all data types, last 30 days
.venv/bin/withings-mcp sync --types body,sleep   # a subset
.venv/bin/withings-mcp sync --days 90            # deeper history on first sync

命令行界面

withings-mcp              Start the MCP server (stdio transport)
withings-mcp auth         Interactive OAuth setup (opens the browser)
withings-mcp sync         Sync data to the local cache (--types, --days)
withings-mcp doctor       Check the setup and report what needs fixing
withings-mcp --version    Print the installed package version

配置

环境变量	默认值	描述
WITHINGS_MCP_CONFIG_DIR	./config/	凭据和令牌的目录
WITHINGS_MCP_DB_PATH	./withings.db	SQLite 数据库路径

示例提示词

• “同步我的 Withings 数据”
• “显示我过去 3 个月的体重”
• “我今年的睡眠情况有什么变化？”
• “比较我本月和上月的身体成分”
• “我 3 月做了哪些锻炼？”
• “我连接了哪些 Withings 设备？”
• “按季度显示我的睡眠趋势”

开发

# Install with dev dependencies
uv pip install -e . && uv pip install pytest

# Run tests (all use in-memory SQLite with fictional data)
.venv/bin/python -m pytest tests/ -v      # .venv\Scripts\python on Windows

安全

• 只读：没有任何工具会修改 Withings 服务上的数据
• 本地存储：健康数据保存在你的本地 SQLite 数据库中
• 令牌存储：OAuth 令牌存储在 config/ 中（已加入 gitignore；在 POSIX 系统上创建时权限为 0600；Windows 忽略该模式，并通过 ACL 控制访问权限）
• 错误消息：绝不包含健康数据值，只包含状态码
• 提交前钩子：可选钩子（scripts/check-no-data.sh）会阻止将数据库文件、config/ 下的文件和大型文件提交到代码库。它不会读取文件内容。可使用 CONTRIBUTING.md 中的单行命令安装

贡献

开发环境设置、测试工作流和提交前钩子请参阅 CONTRIBUTING.md。变更记录见 CHANGELOG.md。

许可证

GPL-3.0-or-later