Withings MCP Client

MCP (Model Context Protocol) client for retrieving data from Withings smart scale, including weight and body composition measurements.

Prerequisites

1. Create a Withings Developer account at https://developer.withings.com/

2. Create an application to get your Client ID and Client Secret

3. Set up your redirect URI (default: http://localhost:3000/callback)

4. Bun runtime (recommended) or Node.js

Installation

Install from GitHub

With Bun (recommended):

Or with npm:

Or run directly from GitHub

With Bun (recommended):

Or with npm/npx:

Setup

1. Configuration

Create a .env file with your Withings credentials:

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:

Or directly from GitHub:

Or after cloning:

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:

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):

Or with npm:

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.

Development

Clone the Repository

For local development:

Build

Run in development mode

Run tests

Lint and format

License

ISC