Withings MCP

🚀 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

這將完成以下操作：

1. 在端口 3000 上啟動一個臨時本地服務器。
2. 在瀏覽器中打開 Withings 授權頁面。
3. 自動處理 OAuth 回調。
4. 將你的訪問令牌和刷新令牌保存到 .env 文件中。
5. 關閉臨時服務器。

授權只需要進行一次，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 許可證。