JinDaGe - withings-mcp MCP Details

article

README

🚀 Withings MCP 客户端

Withings MCP（模型上下文协议）客户端用于从 Withings 智能秤中检索数据，包括体重和身体成分测量数据。

🚀 快速开始

本客户端可帮助你轻松获取 Withings 智能秤的数据。在使用前，你需要完成一些准备工作，然后进行安装和配置，最后就可以使用客户端提供的工具获取数据啦。

✨ 主要特性

数据获取全面：能够获取体重、身体成分等多种测量数据。
多工具支持：提供了多个工具，如获取体重、身体成分、原始测量数据、用户列表等。
用户过滤灵活：支持按用户属性进行数据过滤。
单位系统可选：支持公制和英制两种单位系统。

📦 安装指南

从 GitHub 安装

推荐使用 Bun 进行安装：

bun install git+https://github.com/gchallen/withings-mcp.git

或者使用 npm 安装：

npm install git+https://github.com/gchallen/withings-mcp.git

直接从 GitHub 运行

推荐使用 Bun：

bunx --bun gchallen/withings-mcp

或者使用 npm/npx：

npx gchallen/withings-mcp

💻 使用示例

配置

创建一个 .env 文件，并填写你的 Withings 凭证：

WITHINGS_CLIENT_ID=your_client_id
WITHINGS_CLIENT_SECRET=your_client_secret
WITHINGS_REDIRECT_URI=http://localhost:3000/callback
WITHINGS_USER_ATTRIB=0  # 可选：指定特定用户 (0=设备所有者, 1+=其他用户)
WITHINGS_UNIT_SYSTEM=imperial  # 可选：设置默认单位 (metric=千克, imperial=磅)

授权（一次性设置）

在使用 MCP 服务器之前，你需要授权访问你的 Withings 数据。运行授权工具：使用 Bun：

bun tokens

或者直接从 GitHub 运行：

bunx --bun gchallen/withings-mcp tokens
# 或者
npx gchallen/withings-mcp tokens

或者克隆仓库后运行：

git clone https://github.com/gchallen/withings-mcp.git
cd withings-mcp
bun tokens
# 或者
npm run tokens

这将完成以下操作：

在端口 3000 上启动一个临时本地服务器。
在浏览器中打开 Withings 授权页面。
自动处理 OAuth 回调。
将你的访问令牌和刷新令牌保存到 .env 文件中。
关闭临时服务器。

授权只需要进行一次，MCP 服务器将根据需要自动刷新令牌。

CLI 使用

该包提供了统一的 CLI，包含以下命令：

# 运行 OAuth 授权（一次性设置）
bunx --bun gchallen/withings-mcp tokens
# 或者
npx gchallen/withings-mcp tokens

# 启动 MCP 服务器（默认命令）
bunx --bun gchallen/withings-mcp
# 或者
npx gchallen/withings-mcp

可用工具

MCP 服务器提供了以下工具：

`withings_get_weight`

从你的 Withings 秤获取最新的体重测量值。

`withings_get_body_composition`

获取完整的身体成分数据，包括：

体重（千克）
脂肪质量（千克和百分比）
肌肉质量（千克和百分比）
骨骼质量（千克和百分比）
水分含量（千克和百分比）
内脏脂肪指数
代谢年龄

`withings_get_measurements`

获取原始测量数据，并可选择过滤条件。参数：

measureTypes（可选）：测量类型 ID 数组
startDate（可选）：ISO 格式的开始日期
endDate（可选）：ISO 格式的结束日期
userAttrib（可选）：用户属性过滤器

`withings_get_users`

获取在 Withings 秤上有测量数据的用户列表。返回用户统计信息，包括测量次数和最新测量日期。

用户过滤

所有工具都支持按用户属性进行过滤：

userAttrib: 0 - 设备所有者（主要用户）
userAttrib: 1+ - 其他用户
userAttrib: 2 - 手动输入
userAttrib: 4 - 自动检测

你可以设置 WITHINGS_USER_ATTRIB 环境变量，以自动将所有请求过滤到特定用户。如果未设置，将返回所有用户的数据（除非显式过滤）。

单位系统

所有测量工具都支持公制和英制单位：

unitSystem: "metric" - 以千克返回体重
unitSystem: "imperial" - 以磅返回体重

你可以设置 WITHINGS_UNIT_SYSTEM 环境变量，以自动为所有请求使用你首选的单位：

WITHINGS_UNIT_SYSTEM=metric - 默认，返回千克/厘米
WITHINGS_UNIT_SYSTEM=imperial - 返回磅/英寸

如果未设置，默认使用公制。你可以在每个请求中通过传递 unitSystem 参数来覆盖默认设置。

与 Claude Desktop 一起使用

将服务器添加到你的 Claude Desktop 配置中：使用 Bun（推荐）：

{
  "mcpServers": {
    "withings": {
      "command": "bunx",
      "args": ["--bun", "gchallen/withings-mcp"],
      "env": {
        "WITHINGS_CLIENT_ID": "your_client_id",
        "WITHINGS_CLIENT_SECRET": "your_client_secret",
        "WITHINGS_REDIRECT_URI": "http://localhost:3000/callback",
        "WITHINGS_ACCESS_TOKEN": "your_access_token",
        "WITHINGS_REFRESH_TOKEN": "your_refresh_token",
        "WITHINGS_USER_ATTRIB": "0",
        "WITHINGS_UNIT_SYSTEM": "imperial"
      }
    }
  }
}

或者使用 npm：

{
  "mcpServers": {
    "withings": {
      "command": "npx",
      "args": ["gchallen/withings-mcp"],
      "env": {
        "WITHINGS_CLIENT_ID": "your_client_id",
        "WITHINGS_CLIENT_SECRET": "your_client_secret",
        "WITHINGS_REDIRECT_URI": "http://localhost:3000/callback",
        "WITHINGS_ACCESS_TOKEN": "your_access_token",
        "WITHINGS_REFRESH_TOKEN": "your_refresh_token",
        "WITHINGS_USER_ATTRIB": "0",
        "WITHINGS_UNIT_SYSTEM": "imperial"
      }
    }
  }
}

注意：运行授权命令后，访问令牌和刷新令牌将保存到你的 .env 文件中。请将这些值复制到你的 Claude Desktop 配置中。

🔧 技术细节

本项目使用 Bun 或 Node.js 作为运行时，通过 OAuth 协议与 Withings 进行授权和数据交互。在授权过程中，会启动一个临时本地服务器来处理 OAuth 回调，并将获取到的访问令牌和刷新令牌保存到 .env 文件中。MCP 服务器会根据需要自动刷新令牌，以确保数据的正常获取。

📄 许可证

本项目采用 ISC 许可证。

withings-mcp