Withings MCP

What partymola/withings-mcp MCP server does

The partymola/withings-mcp MCP server exposes Withings health information through MCP tools. It covers body composition measurements such as weight, fat, muscle, hydration, bone mass, blood pressure, heart rate, and oxygen saturation. Other tools return nightly sleep summaries, detailed sleep phases, daily activity totals, workout sessions, connected-device status, and ECG results with atrial-fibrillation classifications.

Most historical data is stored in a local SQLite database. This supports queries without contacting the API for every request and provides the data source used by trend calculations. The server is read-only with respect to Withings data: its tools retrieve and analyze information but do not modify records on Withings servers.

How it works

Run withings_sync to populate or update the cache. The first sync can retrieve a selected number of days, while later syncs request only data newer than the previous synchronization. Cache-backed query tools can also synchronize automatically when the cache is stale, or bypass it with live=True where supported.

withings_trends calculates averages, minimums, maximums, changes, and comparisons for body, sleep, and activity data. It supports weekly, monthly, and quarterly aggregation, as well as comparisons such as one month against the previous month. Raw measurements and sessions are returned by the corresponding body, sleep, activity, and workout tools instead.

The heart and device tools always call the live API. Detailed sleep mode also uses a live request and is limited to seven days per request. The server communicates over stdio when started with its command-line entry point.

Setup and configuration

Using the partymola/withings-mcp MCP server requires Python 3.13 or newer, plus a Withings developer account and registered application. Register the application at the Withings developer dashboard and set its callback URL to http://localhost:8585. The interactive auth command opens a browser for authorization and saves the resulting tokens locally.

Install the package with pip install withings-mcp, or run it without a local package installation using uvx withings-mcp. The server can then be registered with an MCP client using its stdio command. A first sync is recommended before asking for cached historical data.

Two optional environment variables control local storage:

• WITHINGS_MCP_CONFIG_DIR selects the directory for credentials and tokens; the default is ./config/.
• WITHINGS_MCP_DB_PATH selects the SQLite database path; the default is ./withings.db.

The CLI also provides sync for manual synchronization and doctor for checking paths, credentials, and setup without making an API request.

Tools and capabilities

The partymola/withings-mcp MCP server provides these tool functions:

• withings_sync synchronizes all supported data or selected types such as body, sleep, activity, and workouts.
• withings_get_body returns date-filtered body measurements and can limit results to selected metrics.
• withings_get_sleep returns nightly summaries or minute-level awake, light, deep, and REM phases.
• withings_get_activity returns daily steps, distance, calories, and active minutes.
• withings_get_workouts returns workout type, duration, calories, distance, and heart-rate information, with optional type filtering.
• withings_trends aggregates body, sleep, or activity data and compares periods.
• withings_get_devices reports connected device models, battery status, firmware-related device information, and last session dates.
• withings_get_heart returns ECG recordings, timestamps, heart rate, and AFib classifications without raw signal waveforms.

Limitations and notes

The server requires an authenticated Withings account and access to the relevant Withings data. ECG results require a compatible ECG-capable device such as a ScanWatch or BPM Core. Detailed sleep requests are limited to seven days, and heart data is not cached because of its larger signal-related payload. Queries for daily activity totals and workout sessions use different tools, so choosing the appropriate function matters.

The package is licensed under GPL-3.0-or-later. Health data remains in the configured local SQLite database, while OAuth tokens are stored in the configured credentials directory.