# 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](https://developer.withings.com/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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**

```bash
# 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](https://developer.withings.com/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:**

```bash
# 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:

```bash
# 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:

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

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

```json
{
  "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.

```json
{
  "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](https://developer.withings.com/api-reference/)
- [Developer Dashboard](https://developer.withings.com/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)
   ```bash
   /path/to/.venv/bin/python --version
   ```

2. **Recreate virtual environment with correct Python version**:
   ```bash
   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:
   ```bash
   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`)

## Maintainer

Schimmi — https://schimmilab.de
Issues und Pull Requests willkommen.