Skip to main content
Glama
Withings MCP Server

Withings MCP Server

by YpsilonTM

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 auth helper — 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

withings_get_weight, withings_get_body_composition, withings_get_measurements

Watch / activity tracker

Continuous HR, core body temperature, SpO2, steps

withings_get_intraday_activity, or withings_get_heart_rate / withings_get_body_temperature with include_intraday: true; daily rollups via withings_get_activity

Sleep mat / analyzer (if you have one)

Night summaries & series

withings_get_sleep_summary, withings_get_sleep

BPM (if you have one)

Spot blood pressure

withings_get_blood_pressure

Spot vs intraday

  • Spot (getmeas / tools without include_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 and core_body_temperature live. 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

  1. Open developer.withings.com/dashboard

  2. Create an application

  3. Note Client ID and Client Secret

  4. Register this redirect URI exactly:

http://localhost:8765/callback

2. Obtain a refresh token (one time)

uvx --from git+https://github.com/YpsilonTM/withings-mcp withings-mcp auth \
  --write ./tokens.json

Or from a local checkout:

uv sync
uv run withings-mcp auth --write ./tokens.json

Set WITHINGS_CLIENT_ID and WITHINGS_CLIENT_SECRET in the environment (or a .env your shell loads) before running auth.

  1. Open the printed authorize URL in your browser

  2. Log in to Withings and accept

  3. 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-mcp

MCPHub / 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

WITHINGS_CLIENT_ID

Yes

OAuth client ID

WITHINGS_CLIENT_SECRET

Yes

OAuth client secret

WITHINGS_REFRESH_TOKEN

Yes (MCP)*

Refresh token from auth (*or provide via WITHINGS_TOKEN_FILE)

WITHINGS_TOKEN_FILE

No

Path to persist tokens (default /data/tokens.json if /data exists)

WITHINGS_REDIRECT_PORT

No

Auth callback port (default 8765)

WITHINGS_LOG_LEVEL

No

error | warn | info | debug (default info)

OAuth scopes requested: user.info, user.metrics, user.activity, user.sleepevents.

Tools

Tool

Best for

Notes

withings_get_measure_types

Reference

Static meastype catalog

withings_get_measurements

Scale / spot metrics

Filter with meastypes; not continuous watch vitals

withings_get_weight

Scale

Weight (type 1)

withings_get_body_composition

Scale

Fat, muscle, bone, hydration

withings_get_blood_pressure

BPM / scale spot

Systolic / diastolic / pulse

withings_get_heart_rate

Watch (intraday) or spot

Use include_intraday: true for continuous watch HR

withings_get_body_temperature

Watch (intraday) or spot

Use include_intraday: true for watch core_body_temperature

withings_get_spo2

Spot SpO2

Continuous watch SpO2 → withings_get_intraday_activity (spo2_auto)

withings_get_activity

Watch daily totals

Steps, calories, HR zones

withings_get_intraday_activity

Watch continuous vitals

HR, temp, SpO2, steps; ≤24h per API call (auto-split)

withings_get_workouts

Watch workouts

Logged sessions

withings_get_sleep_summary

Sleep device / watch nights

Per-night summaries (default 7 days)

withings_get_sleep

Sleep series

High-frequency stages / vitals (default 24h)

withings_list_heart_records

ECG devices

Often empty without ECG hardware

withings_get_heart_ecg

ECG devices

Single signal by signalid

withings_list_devices

Account

Paired devices

withings_get_goals

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-mcp

Logged 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 pytest

MCP Inspector:

npx @modelcontextprotocol/inspector uv run withings-mcp

Troubleshooting

Symptom

What to try

Auth callback never completes

Confirm redirect URI is exactly http://localhost:8765/callback; port 8765 free

status=343 / invalid token

Refresh token expired or revoked — re-run withings-mcp auth and update secrets / token file

status=601

Rate limited — back off

Empty weight/composition

No scale sync in range

Empty HR/temp without intraday

Watch data is usually intraday — set include_intraday: true or call withings_get_intraday_activity

Empty data (status=100)

No measurements in range, or device never synced that metric

MCP client hangs / protocol errors

Ensure nothing else writes to stdout; set WITHINGS_LOG_LEVEL=debug and inspect stderr

Auth breaks after ~hours

Token file not writable / not mounted — set WITHINGS_TOKEN_FILE on a persistent path

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 tools
withings_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

    A3.8/5.0

    Scored across 17 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      2
      ISC
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables access to Withings Health API data including body measurements, activity tracking, sleep analysis, workouts, and heart rate monitoring through OAuth2 authentication.
      8
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      8
      100 PyPI
      1
      GPL 3.0