Withings Server

Contributors Forks Stargazers Issues MIT License

Table of Contents

1. About The Project
2. Built With
3. Getting Started
4. Usage
5. Available Tools
6. Roadmap
7. Contributing
8. License
9. Acknowledgments

About The Project

A self-hosted MCP server that gives Claude access to your Withings health data. Uses MCP OAuth 2.0 with third-party delegation — when Claude connects, you're redirected to Withings to authorize. No manual token management needed.

11 read-only tools covering body measurements, activity, sleep, heart rate/ECG, and device information from Withings scales, watches, blood pressure monitors, thermometers, and sleep trackers.

(back to top)

Built With

Python Docker Cloudflare

(back to top)

Getting Started

Prerequisites

• Docker and Docker Compose
• A Withings developer account with a registered app
• A Cloudflare Tunnel token

Withings App Setup

1. Go to developer.withings.com and log in to the Partner Hub
2. Create a new application
3. Set Redirect URL to https://<your-tunnel-url>/withings-callback
4. Note your Client ID and Client Secret

Installation

1. Clone the repo

   git clone https://github.com/npab19/withings-mcp.git
   cd withings-mcp
   

2. Copy the environment template

   cp .env.example .env
   

3. Fill in your credentials in .env:

   WITHINGS_CLIENT_ID=your_client_id
   WITHINGS_CLIENT_SECRET=your_client_secret
   SERVER_URL=https://your-tunnel-url.example.com
   Cloudflare_Token=your_cloudflare_tunnel_token
   

4. Start the services

   docker compose up -d
   

(back to top)

Usage

Claude.ai Web Connectors

Set the connector URL to:

https://<your-tunnel-url>/mcp

OAuth authentication will be handled automatically when you first connect.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "withings": {
      "type": "http",
      "url": "https://<your-tunnel-url>/mcp"
    }
  }
}

(back to top)

Available Tools

Category	Tools	Description
Body Measurements	1	Weight, fat mass, muscle mass, bone mass, blood pressure, temperature, SpO2, hydration, and more
Activity	1	Daily steps, distance, calories, elevation, heart rate zones
Intraday Activity	1	Minute-level heart rate, steps, SpO2, HRV, calories, elevation
Workouts	1	Exercise sessions with duration, calories, HR zones, swimming metrics
Sleep	1	Minute-level sleep states, heart rate, respiration rate, snoring
Sleep Summary	1	Nightly aggregates: sleep score, duration, phases, breathing disturbances
Heart Recordings	1	ECG recording list with AFib classification
Heart Signal	1	Raw ECG waveform data in microvolts
Devices	1	Device type, model, battery, firmware, last sync
Goals	1	Steps, sleep, and weight targets

(back to top)

Roadmap

• Core Withings API read endpoints
• MCP OAuth 2.0 with Withings delegation
• Docker + Cloudflare Tunnel deployment
• Token persistence across restarts
• Subscription/webhook support for real-time data
• Write endpoints (log measurements, set goals)

(back to top)

Contributing

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Acknowledgments

• Withings Health API Documentation
• Model Context Protocol
• Cloudflare Tunnels
• Best-README-Template

(back to top)