Withings MCP

🚀 Withings MCP Client

This is an MCP (Model Context Protocol) client designed to retrieve data from the Withings smart scale, including weight and body composition measurements.

🚀 Quick Start

The Withings MCP Client allows you to access data from your Withings smart scale. Before you start, make sure you meet the prerequisites and follow the installation and setup steps.

✨ Features

• Retrieve weight and body composition data from the Withings smart scale.
• Support for multiple units (metric and imperial).
• Filter data by user attribution.
• Integration with Claude Desktop.

📦 Installation

Install from GitHub

It is recommended to use Bun:

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

Or use npm:

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

Or run directly from GitHub

It is recommended to use Bun:

bunx --bun gchallen/withings-mcp

Or use npm/npx:

npx gchallen/withings-mcp

💻 Usage Examples

Setup

1. Configuration

Create a .env file with your Withings credentials:

WITHINGS_CLIENT_ID=your_client_id
WITHINGS_CLIENT_SECRET=your_client_secret
WITHINGS_REDIRECT_URI=http://localhost:3000/callback
WITHINGS_USER_ATTRIB=0  # Optional: Pin to specific user (0=device owner, 1+=other users)
WITHINGS_UNIT_SYSTEM=imperial  # Optional: Set default units (metric=kg, imperial=lb)

2. Authorization (One-time setup)

Before using the MCP server, you need to authorize access to your Withings data. Run the authorization tool:

With Bun:

bun tokens

Or directly from GitHub:

bunx --bun gchallen/withings-mcp tokens
# or
npx gchallen/withings-mcp tokens

Or after cloning:

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

This will:

1. Start a temporary local server on port 3000.
2. Open your browser to the Withings authorization page.
3. Handle the OAuth callback automatically.
4. Save your access and refresh tokens to the .env file.
5. Shut down the temporary server.

The authorization is only needed once. The MCP server will automatically refresh tokens as needed.

CLI Usage

The package provides a unified CLI with the following commands:

# Run OAuth authorization (one-time setup)
bunx --bun gchallen/withings-mcp tokens
# or
npx gchallen/withings-mcp tokens

# Start the MCP server (default command)
bunx --bun gchallen/withings-mcp
# or
npx gchallen/withings-mcp

Available Tools

The MCP server provides the following tools:

withings_get_weight

Get the latest weight measurement from your Withings scale.

withings_get_body_composition

Get complete body composition data including:

• Weight (kg)
• Fat mass (kg and percentage)
• Muscle mass (kg and percentage)
• Bone mass (kg and percentage)
• Hydration (kg and percentage)
• Visceral fat index
• Metabolic age

withings_get_measurements

Get raw measurement data with optional filters.

Parameters:

• measureTypes (optional): Array of measurement type IDs
• startDate (optional): Start date in ISO format
• endDate (optional): End date in ISO format
• userAttrib (optional): User attribution filter

withings_get_users

Get list of users who have measurements on the Withings scale.

Returns user statistics including measurement counts and latest measurement dates.

User Filtering

All tools support filtering by user attribution:

• userAttrib: 0 - Device owner (primary user)
• userAttrib: 1+ - Other users
• userAttrib: 2 - Manual entries
• userAttrib: 4 - Automatic detection

You can set WITHINGS_USER_ATTRIB environment variable to automatically filter all requests to a specific user. If not set, data from all users will be returned (unless explicitly filtered).

Unit System

All measurement tools support both metric and imperial units:

• unitSystem: "metric" - Returns weights in kg
• unitSystem: "imperial" - Returns weights in lb

You can set WITHINGS_UNIT_SYSTEM environment variable to automatically use your preferred units for all requests:

• WITHINGS_UNIT_SYSTEM=metric - Default, returns kg/cm
• WITHINGS_UNIT_SYSTEM=imperial - Returns lb/inches

If not set, defaults to metric. You can override on a per-request basis by passing the unitSystem parameter to individual tools.

Usage with Claude Desktop

Add the server to your Claude Desktop configuration:

With Bun (recommended):

{
  "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"
      }
    }
  }
}

Or with 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"
      }
    }
  }
}

Note: After running the auth command, the access and refresh tokens will be saved to your .env file. Copy these values to your Claude Desktop configuration.

🔧 Technical Details

Development

Clone the Repository

For local development:

git clone https://github.com/gchallen/withings-mcp.git
cd withings-mcp
bun install  # or npm install

Build

bun run build  # or npm run build

Run in development mode

bun dev        # or npm run dev

Run tests

bun test       # or npm test

Lint and format

bun lint       # or npm run lint
bun format     # or npm run format

📄 License

ISC