Withings MCP Server
Withings MCP Server lets AI clients query Withings health data through MCP tools, with OAuth setup and automatic token refresh.
Authenticate via a one-time browser OAuth helper and persist/auto-refresh rotated tokens.
Query scale and spot measurements: weight, body composition, blood pressure, spot SpO2, spot heart rate/temperature, and measurement type catalog.
Query watch/tracker intraday vitals: continuous heart rate, core body temperature, SpO2, steps, HRV, and related series, with >24h ranges auto-split.
Fetch daily activity summaries, workouts, sleep summaries, and high-frequency sleep series.
List ECG/heart records and retrieve a single ECG waveform by signal ID.
Inspect paired devices and configured health goals.
Filter by date ranges, measurement types, data fields, and pagination; rate-limit errors are surfaced and logs stay on stderr.
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 What was my sleep score last night?"
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
Model Context Protocol (MCP) server for the Withings Public API. Query weight, body composition, heart rate, core body temperature, SpO2, activity, sleep, workouts, and ECG recordings from AI clients (Cursor, Claude Desktop, MCPHub, etc.).
Python / stdio / run via uvx — no Docker image required.
Features
stdio MCP server — works with Cursor, Claude Desktop, MCPHub, and other MCP clients
One-shot
authhelper — browser OAuth, prints tokens (no always-on auth service)Broad tool set — scale measurements, watch/intraday vitals, sleep, heart/ECG, devices & goals
Token refresh — automatic access-token refresh with atomic persistence of rotated refresh tokens
Structured stderr logging — JSON lines, safe for MCP (stdout stays protocol-only)
Related MCP server: Oura Ring MCP Server
Scale vs watch (important)
Withings splits data by how it was recorded. Empty tool results usually mean you queried the wrong path for that device.
Device | Typical data | Prefer these tools |
Scale | Weight, body composition, occasional spot pulse |
|
Watch / activity tracker | Continuous HR, core body temperature, SpO2, steps |
|
Sleep mat / analyzer (if you have one) | Night summaries & series |
|
BPM (if you have one) | Spot blood pressure |
|
Spot vs intraday
Spot (
getmeas/ tools withoutinclude_intraday) — discrete measurements when you step on the scale or take a reading. Often empty for watch-only vitals.Intraday (
getintradayactivity, max 24h per API call) — time series from the watch while you wear it. This is where continuous HR andcore_body_temperaturelive. Ranges longer than 24h are split into consecutive windows automatically.
Example: “body temp last 24h” from a ScanWatch → use withings_get_body_temperature with include_intraday: true (or withings_get_intraday_activity with data_fields=core_body_temperature), not spot-only temperature types.
Quick start
1. Create a Withings developer app
Create an application
Note Client ID and Client Secret
Register this redirect URI exactly:
http://localhost:8765/callback2. Obtain a refresh token (one time)
uvx --from git+https://github.com/YpsilonTM/withings-mcp withings-mcp auth \
--write ./tokens.jsonOr from a local checkout:
uv sync
uv run withings-mcp auth --write ./tokens.jsonSet WITHINGS_CLIENT_ID and WITHINGS_CLIENT_SECRET in the environment (or a .env your shell loads) before running auth.
Open the printed authorize URL in your browser
Log in to Withings and accept
Tokens are printed as JSON on stdout; with
--write, also saved to the given path
3. Run the MCP server
export WITHINGS_CLIENT_ID=...
export WITHINGS_CLIENT_SECRET=...
export WITHINGS_TOKEN_FILE=./tokens.json # or WITHINGS_REFRESH_TOKEN=...
uvx --from git+https://github.com/YpsilonTM/withings-mcp withings-mcpMCPHub / Cursor
MCPHub mcp_settings.json
{
"mcpServers": {
"withings": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/YpsilonTM/withings-mcp",
"withings-mcp"
],
"env": {
"WITHINGS_CLIENT_ID": "",
"WITHINGS_CLIENT_SECRET": "",
"WITHINGS_REFRESH_TOKEN": "",
"WITHINGS_TOKEN_FILE": "/data/withings/tokens.json",
"WITHINGS_LOG_LEVEL": "info"
}
}
}
}Bind secrets via MCPHub per-user credentials rather than hard-coding them. The token file path must be mounted into the MCPHub container (Withings rotates the refresh token on every refresh; without a writable mount, auth breaks after the first refresh).
See also examples/mcp_settings.json.
Cursor / Claude Desktop
{
"mcpServers": {
"withings": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/YpsilonTM/withings-mcp",
"withings-mcp"
],
"env": {
"WITHINGS_CLIENT_ID": "your_client_id",
"WITHINGS_CLIENT_SECRET": "your_client_secret",
"WITHINGS_TOKEN_FILE": "/absolute/path/to/tokens.json"
}
}
}
}Environment variables
Variable | Required | Description |
| Yes | OAuth client ID |
| Yes | OAuth client secret |
| Yes (MCP)* | Refresh token from |
| No | Path to persist tokens (default |
| No | Auth callback port (default |
| No |
|
OAuth scopes requested: user.info, user.metrics, user.activity, user.sleepevents.
Tools
Tool | Best for | Notes |
| Reference | Static meastype catalog |
| Scale / spot metrics | Filter with |
| Scale | Weight (type 1) |
| Scale | Fat, muscle, bone, hydration |
| BPM / scale spot | Systolic / diastolic / pulse |
| Watch (intraday) or spot | Use |
| Watch (intraday) or spot | Use |
| Spot SpO2 | Continuous watch SpO2 → |
| Watch daily totals | Steps, calories, HR zones |
| Watch continuous vitals | HR, temp, SpO2, steps; ≤24h per API call (auto-split) |
| Watch workouts | Logged sessions |
| Sleep device / watch nights | Per-night summaries (default 7 days) |
| Sleep series | High-frequency stages / vitals (default 24h) |
| ECG devices | Often empty without ECG hardware |
| ECG devices | Single signal by |
| Account | Paired devices |
| Account | Goals |
Example prompts:
“What was my heart rate in the last 24 hours?” → watch intraday HR
“Show my core body temperature today.” → watch intraday temp
“What did I weigh this morning?” → scale weight
“How did I sleep the last 7 nights?” → sleep summary
Logging
All logs go to stderr as one JSON object per line so they never break the MCP session on stdout.
WITHINGS_LOG_LEVEL=debug uv run withings-mcpLogged at info: startup config (booleans only), tool name + date range, Withings status, durations.
Never logged: access/refresh tokens, client secret, Authorization headers.
Rate limits
Withings asks partners not to poll more often than about once every 10 minutes per user for sync-style usage. Prefer explicit date ranges when asking the model for historical data. API status=601 is surfaced as a rate-limit error.
Development
Requires Python ≥ 3.12 and uv.
uv sync
uv run withings-mcp --help
uv run withings-mcp auth --help
uv run ruff check src tests
uv run pytestMCP Inspector:
npx @modelcontextprotocol/inspector uv run withings-mcpTroubleshooting
Symptom | What to try |
Auth callback never completes | Confirm redirect URI is exactly |
| Refresh token expired or revoked — re-run |
| Rate limited — back off |
Empty weight/composition | No scale sync in range |
Empty HR/temp without intraday | Watch data is usually intraday — set |
Empty data ( | No measurements in range, or device never synced that metric |
MCP client hangs / protocol errors | Ensure nothing else writes to stdout; set |
Auth breaks after ~hours | Token file not writable / not mounted — set |
License
MIT — see LICENSE.
Disclaimer
This project is not affiliated with Withings. Use only with accounts and data you are authorized to access. Health data is sensitive — store secrets and token files securely.
Available Tools
17 toolswithings_get_activityA
Fetch daily activity summaries from the watch/tracker (steps, distance, calories, HR zones, etc.). Prefer this for day-level watch stats; use withings_get_intraday_activity for minute-level series.
Inputs: offset, enddateymd, data_fields, startdateymd.
withings_get_blood_pressureB
Fetch blood pressure and related spot pulse (diastolic 9, systolic 10, heart rate 11). Typical source: BPM or scale, not continuous watch HR.
Inputs: offset, enddate, startdate.
withings_get_body_compositionA
Fetch scale body composition: fat free mass, fat ratio, fat mass, muscle, hydration, bone (types 5,6,8,76,77,88). Typical source: Withings scale.
Inputs: offset, enddate, startdate.
withings_get_body_temperatureA
Fetch body temperature. Spot readings (meastypes 12/71/73 via getmeas) come from thermometers or occasional device measures. For Withings watches, set include_intraday=true to fetch continuous core_body_temperature (max 24h window) — that is usually where watch temp lives.
Inputs: offset, enddate, startdate, include_intraday.
withings_get_goalsA
Get health goals configured in the Withings account (e.g. steps, weight, sleep targets), if the user has set any.
Inputs: no named parameters.
withings_get_heart_ecgA
Fetch a single ECG waveform/signal by signalid from withings_list_heart_records. Only useful when withings_list_heart_records returned recordings (ECG-capable device). Not for continuous watch heart rate.
Inputs: signalid (required).
withings_get_heart_rateA
Fetch heart rate. Spot readings (meastype 11 via getmeas) come from scale/BPM when you take a measurement. For Withings watches, set include_intraday=true (or use withings_get_intraday_activity) for continuous HR — that is usually where watch HR lives (max 24h window).
Inputs: offset, enddate, startdate, include_intraday.
withings_get_intraday_activityA
Fetch high-resolution watch/tracker series for up to 24 hours: heart_rate, core_body_temperature, spo2_auto, steps, HRV, etc. This is the main source for continuous vitals from a Withings watch (not the scale). Withings returns at most 24 hours per call.
Inputs: enddate, startdate, data_fields.
withings_get_measurementsA
Fetch spot/scale health measurements via getmeas (weight, composition, BP, spot HR/temp/SpO2, etc.). Optionally filter by meastypes. Values are decoded (value * 10^unit). This is NOT the main source for continuous watch vitals — use withings_get_intraday_activity (or withings_get_heart_rate / withings_get_body_temperature with include_intraday=true) for those.
Inputs: offset, enddate, meastypes, startdate.
withings_get_measure_typesA
List known Withings measurement type IDs used by getmeas (weight, BP, SpO2, spot temperature, etc.). No API call. For continuous watch vitals (HR, core temp, SpO2), prefer withings_get_intraday_activity instead of these spot types.
Inputs: no named parameters.
withings_get_sleepA
Fetch high-frequency sleep stage and vital series for a time window (Sleep get): stages, HR, respiration, snoring, HRV, etc. Default range is the last 24 hours. Prefer withings_get_sleep_summary for multi-night overviews; use this for detailed series within a night. Typical sources: Sleep Analyzer / Sleep Mat, or watch sleep tracking.
Inputs: enddate, startdate, data_fields.
withings_get_sleep_summaryA
Fetch per-night sleep summaries (score, stages, HR/RR stats, snoring, etc.). Default range is the last 7 days. Typical sources: Sleep Analyzer / Sleep Mat, or watch sleep tracking. For minute-level detail within a night, use withings_get_sleep.
Inputs: enddateymd, lastupdate, data_fields, startdateymd.
withings_get_spo2A
Fetch spot SpO2 measurements (meastype 54) from getmeas. For continuous watch SpO2, prefer withings_get_intraday_activity with spo2_auto.
Inputs: offset, enddate, startdate.
withings_get_weightB
Fetch scale weight measurements (meastype 1). Typical source: Withings scale.
Inputs: offset, enddate, startdate.
withings_get_workoutsA
Fetch logged workouts from the watch/activity tracker for a date range (default last 7 days). Includes session type, duration, and optional metrics like calories, HR, distance, steps.
Inputs: offset, enddateymd, data_fields, startdateymd.
withings_list_devicesA
List Withings devices paired to the authorized account (e.g. Scale, Activity Tracker, Sleep Monitor). Useful to see which data sources exist before querying.
Inputs: no named parameters.
withings_list_heart_recordsA
List ECG / heart recordings (Heart v2 list), including AFib classification metadata. Requires an ECG-capable device (e.g. ScanWatch ECG / BeamO). Often empty if the user only has a scale + non-ECG tracker. Default range: last 30 days. Use withings_get_heart_rate with include_intraday for continuous watch HR instead.
Inputs: offset, enddate, startdate.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Several tools overlap: withings_get_measurements overlaps with the weight, body composition, blood pressure, SpO2, temperature, and heart rate getters, and withings_get_intraday_activity overlaps with continuous HR/temperature retrieval. The descriptions do a good job of clarifying boundaries, but the sheer number of closely related data-query tools creates some selection ambiguity.
All tools follow the consistent withings_<verb>_<noun> pattern using snake_case, with list_ reserved for collection enumeration and get_ for data retrieval. Even if some object names vary in specificity, the pattern is predictable and easy to infer.
At 17 tools, the server is slightly above the ideal 3-15 range, but the count is reasonable for the breadth of Withings health data domains. A few redundant measurement-specific wrappers around withings_get_measurements add bulk, but each tool still maps to a meaningful API use case.
The server covers the major Withings data domains well: devices, daily activity, intraday vitals, workouts, sleep summaries and detailed sleep, scale measurements, ECG, and goals. Minor gaps exist—such as no explicit user/profile retrieval and no write/update capabilities—but those are largely outside the apparent read-only scope.
Maintenance
Related MCP Connectors
Read wearables and lab health data — sleep, activity, workouts, timeseries, lab tests and orders.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Connect your wearables, rings and training apps, then ask your AI about your own health data.
Ask Claude, ChatGPT or Cursor about your Apple Health data: workouts, sleep, food. Read-only.
Related MCP Servers
- 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
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI assistants to access and analyze Oura Ring health data including sleep, readiness, activity, and stress metrics. Supports customizable queries, correlation analysis, and visualization capabilities for comprehensive health insights.-
- AlicenseAqualityCmaintenanceEnables access to Withings Health API data including body measurements, activity tracking, sleep analysis, workouts, and heart rate monitoring through OAuth2 authentication.81MIT
- 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