Withings

Withings MCP 服务

在 Patreon 上帮助我支付服务费用

一个 Model Context Protocol（MCP）服务，可将你的 Withings 健康数据接入 Claude。通过自然对话查看睡眠模式、身体测量数据、锻炼、心脏数据等。

🔒 隐私至上：这是我的个人项目，仓库有意公开，以展示透明度。代码表明，不会恶意记录或存储任何个人信息。所有敏感数据（令牌、用户 ID）均经过静态加密，并会自动从日志中删除。你可以审查整个代码库，以确认我们对隐私的承诺。

⚠️ 免责声明：本服务按原样提供，不作任何保证或担保。尽管我已尽力确保安全和隐私，但不保证服务可用性、数据完整性或安全性。使用风险由你自行承担。对于生产环境用例，请考虑自托管自己的实例。

快速设置

1. 打开 Claude Desktop → 自定义 → 连接器
2. 点击 + → 添加自定义连接器
3. 将 URL 设置为 https://withings-mcp.com/mcp → 点击 添加
4. 点击 连接，并使用你的 Withings 账户授权

就这样！向 Claude 询问你的睡眠、体重、锻炼或心脏数据。

演示

目录

• 快速设置
• 演示
• 你可以用它做什么？
• 最终用户：使用托管服务
  • 前提条件
  • 设置说明
  • 可用工具
  • 对话示例
  • 隐私与安全
• 开发者：自行托管
  • 前提条件
  • 步骤 1：创建 Withings 应用
  • 步骤 2：克隆并设置
  • 步骤 3：本地开发
  • 步骤 4：部署到生产环境
  • 步骤 5：更新 Withings 应用设置
  • 步骤 6：配置 MCP 客户端
  • 环境变量参考
  • 开发命令
  • 项目结构
• 安全功能
  • 令牌加密
  • OAuth 加固
  • 传输安全
  • 隐私保护日志
• 贡献
• 许可证
• 支持
• 致谢

你可以用它做什么？

此 MCP 服务可让 Claude 访问你的 Withings 健康数据，帮助你：

• 分析睡眠：询问睡眠质量、时长、深睡眠阶段以及睡眠期间的心率
• 追踪身体指标：了解体重趋势、身体成分、血压和心率随时间的变化
• 回顾锻炼情况：分析运动模式、消耗的卡路里和心率区间
• 监测心脏健康：访问心电图记录和详细的心脏数据
• 设定并追踪目标：查看你的健身和健康目标
• 发现规律：查找睡眠、活动与其他指标之间的关联
• 生成洞察：获取由 AI 提供支持的健康趋势分析

所有操作都可以通过与 Claude 或任何其他兼容 MCP 的客户端进行自然对话来完成。

最终用户：使用托管服务

如果你只想将此 MCP 服务与 Claude Desktop 搭配使用，而不想自行托管，请按以下步骤操作：

前提条件

1. 一个已连接设备的 Withings 账户
2. 电脑上已安装 Claude Desktop 或任何其他兼容 MCP 的客户端

设置说明

步骤 1：在 Claude Desktop 中添加连接器

1. 打开 Claude Desktop
2. 前往自定义（位于侧边栏或菜单中）
3. 进入连接器部分
4. 点击 + 按钮以添加新的连接器
5. 选择添加自定义连接器
6. 填写以下信息：
   • 名称：Withings（或你喜欢的名称）
   • 远程 MCP 服务 URL：https://withings-mcp.com/mcp
7. 点击添加

注意：如果你的 MCP 客户端不支持通过 UI 配置连接器，也可以手动编辑配置文件。请参阅下方的手动配置指南。

步骤 2：连接并授权

1. 在连接器设置中，找到刚添加的 Withings 连接器
2. 点击连接器旁边的连接
3. 网页浏览器将打开 Withings 授权页面
4. 登录你的 Withings 账户
5. 查看并批准请求的权限
6. 系统会将你重定向回来，连接即告完成

授权后，Claude 就能访问你的 Withings 数据了！

可用工具

连接后，Claude 可以使用以下工具访问你的数据：

睡眠与活动

• get_hrv - 睡眠期间采集的分钟级 RMSSD、SDNN 和质量评分
• get_sleep_summary - 睡眠时长、睡眠阶段（浅睡、深睡、REM）、心率、呼吸和睡眠评分
• get_activity - 每日步数、距离、卡路里、海拔和活动时长
• get_intraday_activity - 全天高频活动数据
• get_workouts - 详细的锻炼摘要，包含心率区间和各项指标

身体测量

• get_measures - 体重、身体成分、血压、心率、体温、VO2 max 等

设备与目标

• get_user_devices - 已连接的 Withings 设备列表
• get_user_goals - 您的健康和健身目标（步数、睡眠、体重）

心脏健康

• list_heart_records - 心电图记录列表
• get_heart_signal - 详细的心电图波形数据

听诊器（如果您有 BPM Core）

• list_stetho_records - 听诊器录音列表
• get_stetho_signal - 详细的音频信号数据

示例对话

试着问 Claude：

• “过去一周我的睡眠质量如何？”
• “显示我上个月的体重趋势”
• “我的平均静息心率是多少？”
• “我这周达到步数目标了吗？”
• “比较我这个月和上个月的锻炼强度”
• “我这个月什么时候睡得最好？”

隐私与安全

• 加密令牌：所有身份验证令牌和授权码在存储前均使用 AES-256-GCM 加密
• 不记录个人数据：代码是公开的，您可以确认不会记录任何敏感信息
• 自动脱敏：所有用户 ID、令牌和凭据都会自动从系统日志中脱敏
• OAuth 2.0：符合行业标准的安全身份验证，支持 PKCE 和重定向 URI 验证
• 会话安全：MCP 会话与已通过身份验证的用户绑定，防止跨用户访问
• 由您掌控：您可以随时在 Withings 账户设置中撤销访问权限

---

面向开发者：自托管

想运行自己的实例？以下是自行部署此 MCP 服务的方法。

前置条件

1. 已安装 Bun 1.1+
2. 拥有 Withings Developer Account

步骤 1：创建 Withings 应用程序

1. 前往 Withings Developer Portal
2. 创建一个新应用程序
3. 记下您的 Client ID 和 Client Secret
4. 将您的 Redirect URI 设置为：https://your-domain.com/callback
   • 这必须是可公开访问的 URL（Withings 不支持 localhost）
   • 可以是您托管服务的任意域名（例如，Fly.io、Railway、自有服务器等）

重要：移除 Google Analytics

托管版本在 public/ 下的静态页面中包含 Google Analytics 跟踪代码（G-ZMGF9WXL3W）。如果您要复刻此仓库，请移除或替换 public/index.html 和 public/health.html 中的 GA 代码片段，并相应更新 src/server/app.ts 中的 CSP 标头。

步骤 2：克隆并设置

# Clone the repository
git clone https://github.com/your-username/withings-mcp.git
cd withings-mcp

# Install dependencies
bun install

# Generate encryption secret
bun run generate-secret
# Copy the output - you'll need it for environment variables

步骤 2.5：设置 Supabase 数据库

1. 在 Supabase 创建一个免费项目
2. 安装 Supabase CLI：bun install -g supabase（或使用 brew install supabase/tap/supabase）
3. 链接您的项目：supabase link --project-ref <your-project-ref>
4. 应用数据库迁移：supabase db push
5. 在 Dashboard → Settings → API 中获取凭据：
   • Project URL → SUPABASE_URL
   • Service role key → SUPABASE_SECRET_KEY

步骤 3：本地开发

注意：Withings 要求 OAuth 回调使用可公开访问的 URL。进行本地开发时，请使用隧道服务公开您的本地服务器，或部署到暂存环境进行测试。

# Copy environment template
cp .env.example .env

# Edit .env with your values
# WITHINGS_CLIENT_ID=your_client_id
# WITHINGS_CLIENT_SECRET=your_client_secret
# WITHINGS_REDIRECT_URI=https://your-tunnel-url.com/callback
# ENCRYPTION_SECRET=paste_generated_secret_here
# SUPABASE_URL=https://your-project.supabase.co
# SUPABASE_SECRET_KEY=your_service_role_key
# PORT=3000

# Run locally (Bun executes TypeScript directly — no build step)
bun run dev

请确保 .env 文件中的重定向 URI 与指向本地服务器的可公开访问 URL 一致。

第 4 步：部署到生产环境

# The project runs TypeScript directly with Bun — no build step required.
bun run start

部署到 DigitalOcean App Platform（其 Bun buildpack 会自动检测 package.json 并运行 bun run start），也可以部署到任何支持 Bun 的主机。

在托管平台上设置以下环境变量：

变量	必需	示例
WITHINGS_CLIENT_ID	是	your_client_id
WITHINGS_CLIENT_SECRET	是	your_client_secret
WITHINGS_REDIRECT_URI	是	https://your-domain.com/callback
ENCRYPTION_SECRET	是	根据第 2 步生成
SUPABASE_URL	是	https://your-project.supabase.co
SUPABASE_SECRET_KEY	是	你的 Supabase 服务角色密钥
PORT	否	3000（或平台默认值）
LOG_LEVEL	否	info
ALLOWED_ORIGINS	否	https://example.com,https://app.example.com

第 5 步：更新 Withings 应用设置

返回 Withings 开发者应用，并将重定向 URI 更新为与你部署的 URL 一致： https://your-domain.com/callback

第 6 步：配置 MCP 客户端

对于 Claude Desktop：

1. 打开 Claude Desktop
2. 前往 Customize → Connectors 部分
3. 点击 + 按钮，然后选择 Add Custom Connector
4. 填写以下信息：
   • 名称：Withings（或你喜欢的任意名称）
   • 远程 MCP 服务 URL：https://your-domain.com/mcp
5. 点击 Add
6. 点击连接器旁的 Connect 进行授权

对于其他 MCP 客户端：

使用以下连接信息配置 MCP 客户端：

• 服务 URL：https://your-domain.com
• 传输方式：Streamable HTTP
• 端点：/mcp
• 身份验证：OAuth 2.0
• 发现 URL：/.well-known/oauth-authorization-server

环境变量参考

变量	必需	说明
WITHINGS_CLIENT_ID	是	你的 Withings 应用客户端 ID
WITHINGS_CLIENT_SECRET	是	你的 Withings 应用客户端密钥
WITHINGS_REDIRECT_URI	是	OAuth 回调 URL（必须与 Withings 应用设置一致）
ENCRYPTION_SECRET	是	用于令牌加密的 32 个字符以上的密钥（使用 bun run generate-secret 生成）
SUPABASE_URL	是	你的 Supabase 项目 URL（在 Dashboard → Settings → API 中获取）
SUPABASE_SECRET_KEY	是	你的 Supabase 服务角色密钥（在 Dashboard → Settings → API 中获取）
PORT	否	服务端口（默认值：3000）
LOG_LEVEL	否	日志级别：trace、debug、info、warn、error（默认值：info）
ALLOWED_ORIGINS	否	浏览器客户端允许的 CORS 来源列表，以逗号分隔

开发命令

bun run start            # Run the server
bun run dev              # Hot-reload mode
bun run typecheck        # Type-check with tsc (no emit)
bun run build            # Bundle for production (outputs to ./build)
bun run generate-secret  # Generate encryption secret for ENCRYPTION_SECRET env variable

项目结构

src/
├── auth/              # OAuth 2.0 authentication & token storage
├── db/                # Supabase client & cleanup scheduler
├── server/            # Hono app, MCP endpoints, middleware
├── tools/             # MCP tools for Withings API (sleep, measure, user, heart, stetho)
├── types/             # TypeScript type definitions (Hono, Withings API)
├── withings/          # Withings API client
├── utils/             # Logger and encryption utilities
└── index.ts           # Main entry point

supabase/
└── migrations/        # Database schema migrations

详细的架构文档请参阅 CLAUDE.md。

安全功能

令牌加密

所有 Withings 访问令牌、刷新令牌和授权码在静态存储时均使用 AES-256-GCM 加密：

• 算法：AES-256-GCM（认证加密）
• 密钥派生：PBKDF2，迭代 100,000 次
• 纵深防御：即使数据库遭到入侵，令牌仍会受到保护

重要：请确保你的 ENCRYPTION_SECRET：

• 至少有 32 个字符
• 随机生成（使用 bun run generate-secret）
• 妥善保管，绝不提交到版本控制中
• 在服务器重启后保持一致

OAuth 安全强化

• 重定向 URI 验证：/authorize 端点会根据已注册客户端允许的 URI 验证 redirect_uri，防止开放重定向攻击
• 一次性授权码：授权码会以原子方式消费，以防止重放攻击（符合 RFC 6749）
• PKCE 支持：使用 SHA-256 代码质询方法增强安全性
• 启动时验证：如果缺少必需的环境变量，服务将拒绝启动

传输安全

• 会话令牌绑定：MCP 会话绑定到创建会话的持有者令牌，防止跨用户劫持会话
• JSON-RPC 验证：处理前，会根据 JSON-RPC 2.0 规范验证所有传入消息
• 请求正文大小限制：全局限制为 1MB，以防止内存耗尽
• HTTPS 重定向：在生产环境中，HTTP 请求会自动重定向到 HTTPS
• 严格的 CSP：内容安全策略中不包含 unsafe-inline 指令
• 原子速率限制：使用带行级锁定的 PostgreSQL 函数来防止竞态条件

保护隐私的日志记录

自定义日志记录器会自动对所有敏感信息进行脱敏：

• ✅ 记录操作事件和错误
• ❌ 不记录令牌、凭据或身份验证代码
• ❌ 不记录用户 ID 或个人信息
• ❌ 不记录包含敏感数据的 API 请求／响应负载

你可以在 src/utils/logger.ts 中查看日志记录实现。

贡献

这是一个个人项目，但欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 提交拉取请求

许可证

MIT 许可证，详情请参阅 LICENSE 文件。

支持

• 问题：在 GitHub Issues 上报告错误或请求新功能
• Withings API：请参阅 Withings API 文档
• MCP 协议：请参阅 模型上下文协议文档

致谢

本项目基于以下技术构建：

• Anthropic 的模型上下文协议
• Withings API
• Hono Web 框架
• 使用 Supabase 作为数据库
• Bun 运行时