Withings MCP Server
The Withings MCP Server provides comprehensive access to Withings Health API data through Claude Desktop, enabling natural language queries of your fitness and wellness metrics.
Health Data Access:
Body Measurements: Weight, BMI, body fat percentage, muscle mass, bone mass, fat-free mass, blood pressure, heart rate, SpO2, body temperature, pulse wave velocity, and height
Activity Tracking: Daily steps, calories burned, distance traveled, and elevation gained
Sleep Analysis: Duration, sleep phases (deep, REM, light), wake-up counts, breathing disturbances, apnea events, snoring, and respiratory rate—available as both summaries and granular phase-by-phase details
Workout Sessions: Training and workout session data
Heart Rate Monitoring: Intraday heart rate measurements over specific time periods
User Information: Basic profile data for the authenticated user
Key Features:
OAuth2 Authentication: Secure connection with automatic token generation, storage, and refresh
Flexible Queries: Filter by date ranges (YYYY-MM-DD or Unix timestamps), measurement types, and categories (real measurements vs. user objectives)
Automatic Timezone Conversion: All timestamps converted from UTC to local time
Incremental Updates: Use
lastupdateparameter for efficient data retrievalMultiple Installation Options: Docker (recommended) or local Python installation with automatic credential management from .env file
Claude Desktop Integration: Configure as an MCP server for seamless natural language health data queries
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Withings MCP Server show my weight and heart rate from the past week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Withings MCP Server
An MCP (Model Context Protocol) server for integration with the Withings Health API. This server provides access to health data including body measurements, activities, sleep, and more.
Features
OAuth2 Authentication with the Withings API
Body Measurements: Weight, body fat, muscle mass, blood pressure, heart rate, SpO2, etc.
Activity Data: Steps, calories, distance, elevation
Sleep Data: Sleep duration, deep sleep, REM sleep, wake-up counts
Workout Data: Training sessions and details
Heart Rate: Intraday heart rate measurements
Automatic Timezone Conversion: All timestamps are automatically converted from UTC to your local timezone
Related MCP server: Withings MCP Client
Requirements
Python 3.10, 3.11, or 3.12 (Python 3.13+ is not yet supported by the MCP SDK)
Withings API credentials (Client ID and Client Secret)
Installation
Option 1: Docker (Recommended)
Create Withings API Credentials:
Create a new application
Note your
Client IDandClient SecretSet the Redirect URI to
http://localhost:8080/callback
Configure environment variables:
# Copy the example file
cp .env.example .env
# Edit .env and add your credentials
WITHINGS_CLIENT_ID=your_client_id_here
WITHINGS_CLIENT_SECRET=your_client_secret_here
WITHINGS_REDIRECT_URI=http://localhost:8080/callbackGenerate OAuth tokens:
# First, install locally to run token generation
python -m venv .venv
source .venv/bin/activate
pip install -e .
python generate_tokens.pyBuild and run with Docker:
# Build the image
docker build -t withings-mcp-server .
# Run with docker-compose
docker-compose up -dOption 2: Local Python Installation
Clone repository and install dependencies:
# IMPORTANT: Use Python 3.12 or lower (3.13+ not yet supported)
python3.12 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -e .Create Withings API Credentials:
Create a new application
Note your
Client IDandClient SecretSet the Redirect URI to
http://localhost:8080/callback
Configure environment variables:
# Copy the example file
cp .env.example .env
# Edit .env and add your credentials
WITHINGS_CLIENT_ID=your_client_id_here
WITHINGS_CLIENT_SECRET=your_client_secret_here
WITHINGS_REDIRECT_URI=http://localhost:8080/callbackProject Structure
withings-mcp-server/
├── src/
│ └── withings_mcp_server/
│ ├── __init__.py
│ ├── auth.py # OAuth2 authentication
│ └── server.py # MCP server implementation
├── tests/
│ ├── __init__.py
│ └── test_withings.py # Manual test script
├── generate_tokens.py # Token generation script
├── .env.example # Example environment variables
├── .gitignore
├── pyproject.toml
└── README.mdTesting the Installation
Before using the MCP server, you can verify the connection with the test script:
# Activate virtual environment if not already done
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Run the test script
python tests/test_withings.pyThe test script will guide you through the OAuth flow and test various API endpoints:
✓ OAuth authentication
✓ User information
✓ Body measurements (last 30 days)
✓ Activity data (last 7 days)
✓ Sleep data (last 7 days)
Authentication
Before first use, you need to generate OAuth2 tokens. Tokens are automatically saved to the .env file and refreshed when needed.
Quick Start: Token Generation
Use the dedicated token generation script:
python generate_tokens.pyThe script will guide you through all steps:
✓ Check your API credentials
✓ Generate the authorization URL
✓ Exchange the code for tokens
✓ Save tokens automatically to
.env✓ Verify tokens with a test API call
Alternative: Using Test Script
You can also use the test script which combines OAuth flow and API tests:
python tests/test_withings.pyManual Authentication
Get authorization URL:
Use the
get_authorization_urltool to generate an OAuth URLAuthenticate in browser:
Open the URL in your browser and authorize access
Receive authorization code:
After successful authorization, you'll be redirected to your Redirect URI with a
codeparameterToken management:
Access and Refresh Tokens are automatically:
Saved to the
.envfileRefreshed when expired
Updated after each refresh
Available Tools
get_authorization_url
Generates an OAuth2 authorization URL.
Parameters:
scope(optional): OAuth scopes (default: "user.info,user.metrics,user.activity")
get_user_info
Retrieves user information.
get_measurements
Retrieves body measurements.
Parameters:
meastype(optional): Measurement type1: Weight (kg)4: Height (m)5: Fat-free mass (kg)6: Body fat percentage (%)8: Fat mass (kg)9: Diastolic blood pressure (mmHg)10: Systolic blood pressure (mmHg)11: Heart rate (bpm)12: Temperature (°C)54: SpO2 (%)71: Body temperature (°C)76: Muscle mass (kg)88: Bone mass (kg)91: Pulse wave velocity (m/s)
category(optional): Category (1=real, 2=user_objective)startdate(optional): Start date (YYYY-MM-DD or Unix timestamp)enddate(optional): End date (YYYY-MM-DD or Unix timestamp)lastupdate(optional): Only measurements since this timestamp
get_activity
Retrieves daily activity data.
Parameters:
startdateymd(optional): Start date (YYYY-MM-DD)enddateymd(optional): End date (YYYY-MM-DD)lastupdate(optional): Only activities since this timestamp
get_sleep_summary
Retrieves sleep summary.
Parameters:
startdateymd(optional): Start date (YYYY-MM-DD)enddateymd(optional): End date (YYYY-MM-DD)lastupdate(optional): Only sleep data since this timestamp
get_sleep_details
Retrieves detailed sleep data with all sleep phases.
Parameters:
startdate(optional): Start date (YYYY-MM-DD or Unix timestamp)enddate(optional): End date (YYYY-MM-DD or Unix timestamp)
get_workouts
Retrieves workout/training sessions.
Parameters:
startdateymd(optional): Start date (YYYY-MM-DD)enddateymd(optional): End date (YYYY-MM-DD)
get_heart_rate
Retrieves heart rate measurements over a time period.
Parameters:
startdate(optional): Start date (YYYY-MM-DD or Unix timestamp)enddate(optional): End date (YYYY-MM-DD or Unix timestamp)
MCP Configuration
To use the server with Claude Desktop, add the following to your MCP configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Docker Configuration
{
"mcpServers": {
"withings": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "WITHINGS_CLIENT_ID=your_client_id",
"-e", "WITHINGS_CLIENT_SECRET=your_client_secret",
"-e", "WITHINGS_ACCESS_TOKEN=your_access_token",
"-e", "WITHINGS_REFRESH_TOKEN=your_refresh_token",
"withings-mcp-server"
]
}
}
}Local Python Configuration
Note: The server automatically loads credentials from .env file in the project root. You don't need to specify tokens in the config.
{
"mcpServers": {
"withings": {
"command": "/path/to/withings-mcp-server/.venv/bin/python",
"args": ["-m", "withings_mcp_server"]
}
}
}The server will automatically:
Load credentials from
.envfileRefresh expired tokens
Save refreshed tokens back to
.env
Example Usage
After configuration, you can make the following requests in Claude Desktop:
"Show me my weight measurements from the last 7 days"
"How many steps did I walk today?"
"How was my sleep quality last night?"
"Show me my heart rate data from today"API Documentation
For more details about the Withings API:
License
MIT
Troubleshooting
Server times out on initialization
If Claude Desktop shows "Request timed out" when connecting:
Check Python version: The MCP SDK requires Python 3.10-3.12 (3.13+ not supported)
/path/to/.venv/bin/python --versionRecreate virtual environment with correct Python version:
rm -rf .venv python3.12 -m venv .venv source .venv/bin/activate pip install -e .Update Claude Desktop config to use the correct Python path
Token expired errors
If you get invalid_token or 401 errors:
The server now auto-refreshes tokens, but if that fails:
cd /path/to/withings-mcp-server source .venv/bin/activate python generate_tokens.pyRestart Claude Desktop to pick up the new tokens
Note: Tokens are stored in .env and automatically refreshed. Don't put tokens in claude_desktop_config.json - the server loads them from .env automatically.
Notes
Python 3.13+ is not yet supported by the MCP SDK (use 3.10-3.12)
Tokens are automatically refreshed when they expire
All dates can be specified as YYYY-MM-DD or Unix timestamp
The API is subject to Withings rate limits (see API documentation)
Timestamps are converted to local timezone: All date/time fields in responses are automatically converted from UTC to your local timezone in ISO 8601 format (e.g.,
2025-12-25T14:30:00+01:00)
Maintainer
Schimmi — https://schimmilab.de Issues und Pull Requests willkommen.
Available Tools
8 toolsget_activityB
Get daily activity data (steps, calories, distance, elevation)
Inputs: startdateymd, enddateymd, lastupdate.
get_authorization_urlA
Get OAuth2 authorization URL to authenticate with Withings
Inputs: scope.
get_heart_rateC
Get heart rate measurements over a time period
Inputs: startdate, enddate.
get_measurementsB
Get body measurements (weight, fat mass, muscle mass, etc.)
Inputs: meastype, category, startdate, enddate, +1 more.
get_sleep_detailsB
Get detailed sleep data with all sleep phases
Inputs: startdate, enddate.
get_sleep_summaryC
Get sleep summary data (duration, deep sleep, REM, wake up count, breathing disturbances, apnea, etc.)
Inputs: startdateymd, enddateymd, lastupdate, data_fields.
get_user_infoA
Get user information from Withings account
Inputs: no named parameters.
get_workoutsC
Get workout/training sessions data
Inputs: startdateymd, enddateymd.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
All tools have clearly distinct purposes: activity, heart rate, body measurements, sleep details vs summary, workouts, user info, and authorization. Even the two sleep tools are well-differentiated by detail level.
All tools follow a perfect 'get_<resource>' pattern with snake_case, making it predictable and easy for an agent to infer tool purposes.
With 8 tools, the server covers a comprehensive but focused set of health data endpoints without being overwhelming or too sparse.
The server covers all major Withings health metrics (activity, heart, sleep, workouts, body measurements, user info). Missing write operations and some niche metrics like blood pressure, but core read functionality is complete.
Maintenance
Related MCP Connectors
Read your Aidlab sleep, heart rate, HRV, steps and workouts through OAuth. Read-only access.
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Read wearables and lab health data — sleep, activity, workouts, timeseries, lab tests and orders.
Connect your Oura Ring account securely in minutes. Enable authorized access to your sleep, activi…
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables access to WHOOP fitness and health data through all WHOOP v2 API endpoints. Supports OAuth 2.0 authentication and provides comprehensive access to user profiles, physiological cycles, recovery metrics, sleep analysis, and workout data.1616MIT
- AlicenseNot gradedqualityDmaintenanceEnables retrieval of health data from Withings smart scales including weight measurements and comprehensive body composition metrics like fat mass, muscle mass, and hydration levels. Supports multiple users, unit preferences, and OAuth authentication for secure access to personal health data.2ISC
- AlicenseAqualityBmaintenanceProvides read-only access to Withings health metrics including body composition, sleep, workouts, and ECG data with local SQLite caching and trend analysis. Features incremental synchronization, automatic OAuth token refresh, and supports all 200+ Withings measurement types for comprehensive health tracking.8100 PyPI1GPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables reading Withings smart-scale data (weight, body composition, etc.) through MCP tools, with OAuth2 authentication and automatic token refresh.MIT