withings-mcp
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 compare this week's sleep with the previous one"
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
A small, local MCP server that lets Claude (Claude Code, Claude Desktop or any MCP client) read your own Withings health data through the official Withings Public API: body measurements from the scale and blood pressure monitor, daily activity from the watch, nightly sleep summaries from the sleep analyzer, plus the list of paired devices.
Everything runs on your machine: the server talks to wbsapi.withings.net with tokens stored locally and
hands the data to the MCP client. No third-party service in between.
Tool | Returns |
| connection state, granted scopes, access-token expiry |
| paired devices (model, type, battery, last sync) |
| measurement sessions: weight, fat/muscle/bone/water mass, blood pressure, heart rate, SpO2, temperature, PWV, ECG intervals, ... |
| daily steps, distance, elevation, active minutes, calories, heart-rate zones |
| nightly time in bed / asleep, light/REM/deep, efficiency, wake-ups, HR/RR, breathing disturbances, snoring, sleep score, HRV |
Ask things like "how did my blood pressure trend over the last month?", "compare this week's sleep with the previous one" or "plot my weight since January" and Claude picks the right tool, date range and filters.
Requirements
Python 3.13+ and uv
a Withings account with at least one device (or use the Withings demo user, see below)
a Withings developer application: free, no contract, takes two minutes (step 1)
Works on Windows, macOS and Linux.
Related MCP server: Withings MCP Server
Install
git clone https://github.com/stefanocaronia/withings-mcp.git
cd withings-mcp
uv sync1. Create the Withings application
API credentials are not on account.withings.com; they live on the developer dashboard:
open https://developer.withings.com/dashboard/ and pick Europe Cloud (the one open to everybody)
log in with your normal Withings account
Create an application with integration type Public API
set the callback / redirect URL to exactly
http://localhost:8765/callback(another port works too: pass the same value toauth --redirect-uri)keep the generated
client_idandclient_secret
2. Link your account
uv run withings-mcp auth --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRETThis opens the Withings consent page in your browser, listens on localhost:8765 for the redirect, exchanges the
authorization code (it is valid for 30 seconds) and stores the tokens. With a family account Withings first asks
which user's data to share. Re-running auth later reuses the saved credentials; add --demo to use the Withings
demo user instead of a real account.
Where things are stored: %LOCALAPPDATA%\withings-mcp\ on Windows, $XDG_CONFIG_HOME/withings-mcp or
~/.config/withings-mcp elsewhere (config.json with the app credentials, tokens.json with the OAuth tokens).
Override the directory with WITHINGS_MCP_DIR; WITHINGS_CLIENT_ID / WITHINGS_CLIENT_SECRET take precedence
over config.json. Access tokens (3 h) are refreshed automatically; refresh tokens (1 year) rotate on every refresh
and the newest one is always persisted. If a tool ever reports status 342/343, run auth again.
uv run withings-mcp status shows the current state.
3. Register the server with your MCP client
Claude Code
claude mcp add --scope user withings -- uv --directory /path/to/withings-mcp run withings-mcpClaude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"withings": {
"command": "uv",
"args": ["--directory", "/path/to/withings-mcp", "run", "withings-mcp"]
}
}
}Any other MCP client: it is a stdio server started with uv --directory /path/to/withings-mcp run withings-mcp.
Notes on the data
Dates are
YYYY-MM-DDin local time; without dates the last 30 days are returned.Measurement values are decoded into the unit carried by the key (
weight_kg,fat_ratio_pct,systolic_bp_mmHg, ...);typesaccepts names or Withings type ids (weight,fat_ratioor1,6), andinclude_manual=falsedrops entries typed by hand in the app.Durations are seconds unless the key says otherwise.
Withings asks partners not to poll more than once every 10 minutes per user; the server tells Claude so.
Development
uv run pytestThe tests run against tests/fake_withings.py, a stand-in for the Withings API (token exchange and rotation, a
one-off 343 to exercise the retry, two-page pagination, the OAuth callback with right and wrong state, the tools
in-process and the real server spawned over stdio). No credentials needed.
References: the one-file API summary at https://developer.withings.com/llms.md and the OpenAPI spec at https://developer.withings.com/openapi.yaml.
Disclaimer
Unofficial project, not affiliated with or endorsed by Withings. It only reads data you already own; nothing here is medical advice.
License
Available Tools
5 toolswithings_activityC
Daily activity summaries: steps, distance (m), elevation (floors), soft/moderate/intense/active durations (s), calories (active, kcal), totalcalories, heart rate average/min/max and hr_zone_0..3 durations (s).
Inputs: end_date, start_date. Returns: object
withings_devicesB
Devices paired to the account (model, type, battery, last sync).
Inputs: no named parameters. Returns: result
withings_measurementsA
Body measurements (scale, blood pressure monitor, thermometer, ECG) grouped by measurement session.
types filters by comma-separated names or Withings type ids, e.g. "weight,fat_ratio,muscle_mass" or "1,6,76";
omit it for everything. Names: weight, height, fat_free_mass, fat_ratio, fat_mass, diastolic_bp, systolic_bp,
heart_rate, temperature, spo2, body_temperature, skin_temperature, muscle_mass, hydration, bone_mass,
pulse_wave_velocity, vo2_max, afib_ecg, qrs_interval, pr_interval, qt_interval, qtc_interval, afib_ppg,
vascular_age, extracellular_water, intracellular_water, visceral_fat, basal_metabolic_rate, metabolic_age.
Values are already decoded into the unit in the key (weight_kg, fat_ratio_pct, systolic_bp_mmHg, ...).
include_manual=false keeps only device-captured groups (drops manual entries).
Inputs: types, end_date, start_date, include_manual. Returns: object
withings_sleepC
Nightly sleep summaries: time in bed / asleep, light/REM/deep durations (s), efficiency, latency, wake-ups,
heart and respiration rate, breathing disturbances, snoring, sleep_score, HRV (rmssd). date is the night's date.
Inputs: end_date, start_date. Returns: object
withings_statusB
Whether the Withings account is connected, which scopes were granted and when the access token expires.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool maps to a clearly distinct data domain: connection status, devices, body measurements, activity, and sleep. There is no overlap in purpose, and the descriptions anchor each to a specific resource. An agent can select the right tool unambiguously.
All five tools follow the same predictable withings_<noun> pattern (status, devices, measurements, activity, sleep). No verb-style mixing or case inconsistencies. The naming is uniform and readable.
Five tools is well-scoped and each earns its place by covering a major Withings data category. It is slightly thin in that related surfaces (e.g. workouts, user profile) are not exposed, but nothing feels redundant or padded.
The set provides solid read coverage across status, devices, measurements, activity, and sleep, covering the core lifecycle of a health-data reader. Minor gaps remain, such as workouts or intraday data, but core agent workflows are supported without dead ends.
Maintenance
Related MCP Connectors
MCP server for Withings health data — sleep, activity, heart, and body metrics.
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Hosted Apple Health MCP for Claude and ChatGPT, works outside the US. iPhone app, no local server.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Related MCP Servers
- AlicenseBqualityBmaintenanceLocal-first MCP server that connects AI agents to your Withings body, sleep, activity and heart data.23168 npm6MIT
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol (MCP) server that brings your Withings health data into Claude, allowing natural conversation access to sleep patterns, body measurements, workouts, heart data, and more.46MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects Claude to Withings health data using OAuth 2.0. Provides 11 read-only tools to access body measurements, activity, sleep, heart rate, and device information from Withings devices.MIT
- AlicenseNot gradedqualityDmaintenanceEnables reading Withings smart-scale data (weight, body composition, etc.) through MCP tools, with OAuth2 authentication and automatic token refresh.MIT