# partymola/withings-mcp [Health: Active]

**Category:** 🏃 Sports  
**Repository:** https://github.com/partymola/withings-mcp  
**GitHub Stars:** 0  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/partymola-withings-mcp

## Description
MCP server for the Withings Health API: OAuth, local SQLite cache, and trend analysis for body composition, sleep, activity, workouts, and ECG.

## Tools
Capabilities this server exposes over MCP:

- **withings_sync** — Sync Withings health data to the local cache.

Fetches data from the Withings API and stores it in SQLite for fast
offline queries. Run this before using other withings_get_* tools.

Syncs incrementally: only fetches data newer than the last sync.
First sync fetches the specified number of days of history.

Args:
    data_types: What to sync. Options: "all", "body", "sleep",
        "activity", "workouts". Comma-separated for multiple,
        e.g. "body,sleep". Default: "all".
    days: Days of history for first sync (default: 30). Ignored
        on subsequent syncs (uses last sync timestamp).

Returns summary of records synced per data type.
Not for querying data - use withings_get_body, withings_get_sleep,
withings_get_activity, or withings_get_workouts instead.

- **withings_get_activity** — Get daily activity summaries (steps, distance, calories, active time).

Returns one entry per day from the local cache by default.
Run withings_sync first to populate the cache.

Args:
    start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "30d".
        Default: last 30 days.
    end_date: End date as "YYYY-MM-DD". Default: today.
    live: If true, fetch from Withings API instead of cache.

Returns daily activity data sorted by date, with steps, distance
in km, calories, and active minutes by intensity level.
Not for workout sessions -- use withings_get_workouts instead.

- **withings_get_workouts** — Get workout sessions (type, duration, HR, calories).

Returns individual workout sessions from the local cache by default.
Run withings_sync first to populate the cache.

Args:
    start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "90d".
        Default: last 90 days.
    end_date: End date as "YYYY-MM-DD". Default: today.
    category: Filter by workout type, e.g. "cycling", "walk", "run".
        Case-insensitive partial match.
    live: If true, fetch from Withings API instead of cache.

Returns workout sessions sorted by date with type, duration,
calories, distance, and heart rate data.
Not for daily step/activity totals -- use withings_get_activity.

- **withings_trends** — Analyse trends in cached health data.

Computes averages, min/max, and changes over time from the local
cache. Auto-syncs if the cache is stale (no sync today).

Args:
    data_type: What to analyse. Options: "body", "sleep", "activity".
    period: Aggregation period. Options: "weekly", "monthly",
        "quarterly". Default: "monthly".
    start_date: Start date as "YYYY-MM-DD" or "12m" for relative.
        Default: last 12 months.
    end_date: End date as "YYYY-MM-DD". Default: today.
    compare: Compare two periods. Format: "last_30d vs previous_30d",
        "2026-03 vs 2026-02", "2026-Q1 vs 2025-Q4".
        When set, period/start_date/end_date are ignored.

Returns aggregated averages with change indicators. For body data:
weight, fat%, muscle trends. For sleep: duration, score, HR trends.
For activity: steps, distance, calorie trends.
Not for raw data -- use withings_get_body/sleep/activity instead.

- **withings_get_body** — Get body composition measurements (weight, fat, muscle, etc.).

Returns measurements from the local cache by default. Use live=True
to fetch directly from Withings API. Run withings_sync first to
populate the cache.

Args:
    start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "30d" for
        relative days. Default: last 30 days.
    end_date: End date as "YYYY-MM-DD". Default: today.
    metrics: Comma-separated metric filter, e.g. "weight_kg,fat_pct".
        Default: all available metrics. Options: weight_kg, fat_pct,
        fat_mass_kg, muscle_mass_kg, hydration_kg, bone_mass_kg,
        heart_rate, systolic_bp, diastolic_bp, spo2_pct.
    live: If true, fetch from Withings API instead of cache.

Returns measurements sorted by date, one entry per measurement group.
Not for sleep or activity data -- use withings_get_sleep or
withings_get_activity instead.

- **withings_get_devices** — Get connected Withings devices with battery and firmware info.

Always fetched live from the Withings API.

Returns device type, model name, battery level (high/medium/low),
and last session date for each connected device.

- **withings_get_heart** — Get ECG recordings and atrial fibrillation detection results.

Always fetched live from the Withings API (not cached due to large
signal data). Requires a Withings device with ECG capability
(ScanWatch, BPM Core).

Args:
    start_date: Start date as "YYYY-MM-DD" or "30d". Default: last 30 days.
    end_date: End date as "YYYY-MM-DD". Default: today.

Returns ECG recording list with timestamps, AFib classification
(negative/positive/inconclusive), and heart rate. Does not include
raw signal waveforms.
For resting heart rate trends, use withings_get_body or
withings_get_sleep instead.

- **withings_get_sleep** — Get sleep data (summaries or detailed phases).

Summary mode (default): nightly totals with duration, sleep score,
HR, respiratory rate, and snoring. From local cache unless live=True.

Detail mode (detail=True): minute-by-minute sleep phases (awake,
light, deep, REM) with HR and respiratory rate. Always fetched live.
Maximum 7 days per request (Withings API limit).

Args:
    start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "7d".
        Default: last 7 days (detail) or last 30 days (summary).
    end_date: End date as "YYYY-MM-DD". Default: today.
    detail: If true, return minute-by-minute sleep phases instead
        of nightly summaries. Always live, max 7 days.
    live: If true, fetch summaries from API instead of cache.
        Ignored when detail=True (always live).

Returns nightly sleep data sorted by date.
Not for body composition -- use withings_get_body instead.


## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "withings-mcp": {
    "command": "uvx",
    "args": ["withings-mcp"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/partymola-withings-mcp/readme_