Withings MCP Server

An MCP (Model Context Protocol) server for integration with the Withings Health API. This server provides access to health data including body measurements, activities, sleep, and more.

Features

• OAuth2 Authentication with the Withings API

• Body Measurements: Weight, body fat, muscle mass, blood pressure, heart rate, SpO2, etc.

• Activity Data: Steps, calories, distance, elevation

• Sleep Data: Sleep duration, deep sleep, REM sleep, wake-up counts

• Workout Data: Training sessions and details

• Heart Rate: Intraday heart rate measurements

• Automatic Timezone Conversion: All timestamps are automatically converted from UTC to your local timezone

Requirements

• Python 3.10, 3.11, or 3.12 (Python 3.13+ is not yet supported by the MCP SDK)

• Withings API credentials (Client ID and Client Secret)

Installation

Option 1: Docker (Recommended)

1. Create Withings API Credentials:

   • Go to Withings Developer Dashboard

   • Create a new application

   • Note your Client ID and Client Secret

   • Set the Redirect URI to http://localhost:8080/callback

2. Configure environment variables:

# Copy the example file
cp .env.example .env

# Edit .env and add your credentials
WITHINGS_CLIENT_ID=your_client_id_here
WITHINGS_CLIENT_SECRET=your_client_secret_here
WITHINGS_REDIRECT_URI=http://localhost:8080/callback

3. Generate OAuth tokens:

# First, install locally to run token generation
python -m venv .venv
source .venv/bin/activate
pip install -e .
python generate_tokens.py

4. Build and run with Docker:

# Build the image
docker build -t withings-mcp-server .

# Run with docker-compose
docker-compose up -d

Option 2: Local Python Installation

1. Clone repository and install dependencies:

# IMPORTANT: Use Python 3.12 or lower (3.13+ not yet supported)
python3.12 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

2. Create Withings API Credentials:

   • Go to Withings Developer Dashboard

   • Create a new application

   • Note your Client ID and Client Secret

   • Set the Redirect URI to http://localhost:8080/callback

3. Configure environment variables:

# Copy the example file
cp .env.example .env

# Edit .env and add your credentials
WITHINGS_CLIENT_ID=your_client_id_here
WITHINGS_CLIENT_SECRET=your_client_secret_here
WITHINGS_REDIRECT_URI=http://localhost:8080/callback

Project Structure

withings-mcp-server/
├── src/
│   └── withings_mcp_server/
│       ├── __init__.py
│       ├── auth.py          # OAuth2 authentication
│       └── server.py        # MCP server implementation
├── tests/
│   ├── __init__.py
│   └── test_withings.py     # Manual test script
├── generate_tokens.py       # Token generation script
├── .env.example             # Example environment variables
├── .gitignore
├── pyproject.toml
└── README.md

Testing the Installation

Before using the MCP server, you can verify the connection with the test script:

# Activate virtual environment if not already done
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the test script
python tests/test_withings.py

The test script will guide you through the OAuth flow and test various API endpoints:

• ✓ OAuth authentication

• ✓ User information

• ✓ Body measurements (last 30 days)

• ✓ Activity data (last 7 days)

• ✓ Sleep data (last 7 days)

Authentication

Before first use, you need to generate OAuth2 tokens. Tokens are automatically saved to the .env file and refreshed when needed.

Quick Start: Token Generation

Use the dedicated token generation script:

python generate_tokens.py

The script will guide you through all steps:

1. ✓ Check your API credentials

2. ✓ Generate the authorization URL

3. ✓ Exchange the code for tokens

4. ✓ Save tokens automatically to .env

5. ✓ Verify tokens with a test API call

Alternative: Using Test Script

You can also use the test script which combines OAuth flow and API tests:

python tests/test_withings.py

Manual Authentication

1. Get authorization URL:

   Use the get_authorization_url tool to generate an OAuth URL

2. Authenticate in browser:

   Open the URL in your browser and authorize access

3. Receive authorization code:

   After successful authorization, you'll be redirected to your Redirect URI with a code parameter

4. Token management:

   Access and Refresh Tokens are automatically:

   • Saved to the .env file

   • Refreshed when expired

   • Updated after each refresh

Available Tools

get_authorization_url

Generates an OAuth2 authorization URL.

Parameters:

• scope (optional): OAuth scopes (default: "user.info,user.metrics,user.activity")

get_user_info

Retrieves user information.

get_measurements

Retrieves body measurements.

Parameters:

• meastype (optional): Measurement type

  • 1: Weight (kg)

  • 4: Height (m)

  • 5: Fat-free mass (kg)

  • 6: Body fat percentage (%)

  • 8: Fat mass (kg)

  • 9: Diastolic blood pressure (mmHg)

  • 10: Systolic blood pressure (mmHg)

  • 11: Heart rate (bpm)

  • 12: Temperature (°C)

  • 54: SpO2 (%)

  • 71: Body temperature (°C)

  • 76: Muscle mass (kg)

  • 88: Bone mass (kg)

  • 91: Pulse wave velocity (m/s)

• category (optional): Category (1=real, 2=user_objective)

• startdate (optional): Start date (YYYY-MM-DD or Unix timestamp)

• enddate (optional): End date (YYYY-MM-DD or Unix timestamp)

• lastupdate (optional): Only measurements since this timestamp

get_activity

Retrieves daily activity data.

Parameters:

• startdateymd (optional): Start date (YYYY-MM-DD)

• enddateymd (optional): End date (YYYY-MM-DD)

• lastupdate (optional): Only activities since this timestamp

get_sleep_summary

Retrieves sleep summary.

Parameters:

• startdateymd (optional): Start date (YYYY-MM-DD)

• enddateymd (optional): End date (YYYY-MM-DD)

• lastupdate (optional): Only sleep data since this timestamp

get_sleep_details

Retrieves detailed sleep data with all sleep phases.

Parameters:

• startdate (optional): Start date (YYYY-MM-DD or Unix timestamp)

• enddate (optional): End date (YYYY-MM-DD or Unix timestamp)

get_workouts

Retrieves workout/training sessions.

Parameters:

• startdateymd (optional): Start date (YYYY-MM-DD)

• enddateymd (optional): End date (YYYY-MM-DD)

get_heart_rate

Retrieves heart rate measurements over a time period.

Parameters:

• startdate (optional): Start date (YYYY-MM-DD or Unix timestamp)

• enddate (optional): End date (YYYY-MM-DD or Unix timestamp)

MCP Configuration

To use the server with Claude Desktop, add the following to your MCP configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Docker Configuration

{
  "mcpServers": {
    "withings": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "WITHINGS_CLIENT_ID=your_client_id",
        "-e", "WITHINGS_CLIENT_SECRET=your_client_secret",
        "-e", "WITHINGS_ACCESS_TOKEN=your_access_token",
        "-e", "WITHINGS_REFRESH_TOKEN=your_refresh_token",
        "withings-mcp-server"
      ]
    }
  }
}

Local Python Configuration

Note: The server automatically loads credentials from .env file in the project root. You don't need to specify tokens in the config.

{
  "mcpServers": {
    "withings": {
      "command": "/path/to/withings-mcp-server/.venv/bin/python",
      "args": ["-m", "withings_mcp_server"]
    }
  }
}

The server will automatically:

• Load credentials from .env file

• Refresh expired tokens

• Save refreshed tokens back to .env

Example Usage

After configuration, you can make the following requests in Claude Desktop:

"Show me my weight measurements from the last 7 days"
"How many steps did I walk today?"
"How was my sleep quality last night?"
"Show me my heart rate data from today"

API Documentation

For more details about the Withings API:

• Withings API Reference

• Developer Dashboard

License

MIT

Troubleshooting

Server times out on initialization

If Claude Desktop shows "Request timed out" when connecting:

1. Check Python version: The MCP SDK requires Python 3.10-3.12 (3.13+ not supported)

   /path/to/.venv/bin/python --version

2. Recreate virtual environment with correct Python version:

   rm -rf .venv
   python3.12 -m venv .venv
   source .venv/bin/activate
   pip install -e .

3. Update Claude Desktop config to use the correct Python path

Token expired errors

If you get invalid_token or 401 errors:

1. The server now auto-refreshes tokens, but if that fails:

   cd /path/to/withings-mcp-server
   source .venv/bin/activate
   python generate_tokens.py

2. Restart Claude Desktop to pick up the new tokens

Note: Tokens are stored in .env and automatically refreshed. Don't put tokens in claude_desktop_config.json - the server loads them from .env automatically.

Notes

• Python 3.13+ is not yet supported by the MCP SDK (use 3.10-3.12)

• Tokens are automatically refreshed when they expire

• All dates can be specified as YYYY-MM-DD or Unix timestamp

• The API is subject to Withings rate limits (see API documentation)

• Timestamps are converted to local timezone: All date/time fields in responses are automatically converted from UTC to your local timezone in ISO 8601 format (e.g., 2025-12-25T14:30:00+01:00)