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)

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

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

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

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 .

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

✓ Check your API credentials
✓ Generate the authorization URL
✓ Exchange the code for tokens
✓ Save tokens automatically to .env
✓ 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

Get authorization URL:

Use the get_authorization_url tool to generate an OAuth URL
Authenticate in browser:

Open the URL in your browser and authorize access
Receive authorization code:

After successful authorization, you'll be redirected to your Redirect URI with a code parameter
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:

License

MIT

Troubleshooting

Server times out on initialization

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

Check Python version: The MCP SDK requires Python 3.10-3.12 (3.13+ not supported)
```
/path/to/.venv/bin/python --version
```

Recreate virtual environment with correct Python version:

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

Update Claude Desktop config to use the correct Python path

Token expired errors

If you get invalid_token or 401 errors:

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

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

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)

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)

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

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

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

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 .

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

✓ Check your API credentials
✓ Generate the authorization URL
✓ Exchange the code for tokens
✓ Save tokens automatically to .env
✓ 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

Get authorization URL:

Use the get_authorization_url tool to generate an OAuth URL
Authenticate in browser:

Open the URL in your browser and authorize access
Receive authorization code:

After successful authorization, you'll be redirected to your Redirect URI with a code parameter
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:

License

MIT

Troubleshooting

Server times out on initialization

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

Check Python version: The MCP SDK requires Python 3.10-3.12 (3.13+ not supported)
```
/path/to/.venv/bin/python --version
```

Recreate virtual environment with correct Python version:

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

Update Claude Desktop config to use the correct Python path

Token expired errors

If you get invalid_token or 401 errors:

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

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

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)