Withings MCP Client
MCP (Model Context Protocol) client for retrieving data from Withings smart scale, including weight and body composition measurements.
Prerequisites
- Create a Withings Developer account at https://developer.withings.com/
- Create an application to get your Client ID and Client Secret
- Set up your redirect URI (default:
http://localhost:3000/callback) - Bun runtime (recommended) or Node.js
Installation
Install from GitHub
With Bun (recommended):
bun install git+https://github.com/gchallen/withings-mcp.git
Or with npm:
npm install git+https://github.com/gchallen/withings-mcp.git
Or run directly from GitHub
With Bun (recommended):
bunx --bun gchallen/withings-mcp
Or with npm/npx:
npx gchallen/withings-mcp
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:
- Start a temporary local server on port 3000
- Open your browser to the Withings authorization page
- Handle the OAuth callback automatically
- Save your access and refresh tokens to the
.envfile - 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 IDsstartDate(optional): Start date in ISO formatendDate(optional): End date in ISO formatuserAttrib(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 usersuserAttrib: 2- Manual entriesuserAttrib: 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 kgunitSystem: "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/cmWITHINGS_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.
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
