Withings MCP Server

<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 --> <a id="readme-top"></a>

<!-- PROJECT SHIELDS --> [![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url]

<!-- PROJECT LOGO --> <br /> <div align="center"> <h3 align="center">Withings MCP Server</h3> <p align="center"> A Model Context Protocol server for the Withings Health API with OAuth 2.0 authentication <br /> <a href="https://github.com/npab19/withings-mcp/issues/new?labels=bug">Report Bug</a> · <a href="https://github.com/npab19/withings-mcp/issues/new?labels=enhancement">Request Feature</a> </p> </div>

<!-- TABLE OF CONTENTS --> <details> <summary>Table of Contents</summary> <ol> <li><a href="#about-the-project">About The Project</a></li> <li><a href="#built-with">Built With</a></li> <li><a href="#getting-started">Getting Started</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#available-tools">Available Tools</a></li> <li><a href="#roadmap">Roadmap</a></li> <li><a href="#contributing">Contributing</a></li> <li><a href="#license">License</a></li> <li><a href="#acknowledgments">Acknowledgments</a></li> </ol> </details>

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.

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Built With

[![Python][Python-badge]][Python-url] [![Docker][Docker-badge]][Docker-url] [![Cloudflare][Cloudflare-badge]][Cloudflare-url]

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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
   

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Roadmap

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

License

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

Acknowledgments

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

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- MARKDOWN LINKS & IMAGES --> [contributors-shield]: https://img.shields.io/github/contributors/npab19/withings-mcp.svg?style=for-the-badge [contributors-url]: https://github.com/npab19/withings-mcp/graphs/contributors [forks-shield]: https://img.shields.io/github/forks/npab19/withings-mcp.svg?style=for-the-badge [forks-url]: https://github.com/npab19/withings-mcp/network/members [stars-shield]: https://img.shields.io/github/stars/npab19/withings-mcp.svg?style=for-the-badge [stars-url]: https://github.com/npab19/withings-mcp/stargazers [issues-shield]: https://img.shields.io/github/issues/npab19/withings-mcp.svg?style=for-the-badge [issues-url]: https://github.com/npab19/withings-mcp/issues [license-shield]: https://img.shields.io/github/license/npab19/withings-mcp.svg?style=for-the-badge [license-url]: https://github.com/npab19/withings-mcp/blob/master/LICENSE [Python-badge]: https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white [Python-url]: https://python.org/ [Docker-badge]: https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white [Docker-url]: https://docker.com/ [Cloudflare-badge]: https://img.shields.io/badge/Cloudflare-F38020?style=for-the-badge&logo=cloudflare&logoColor=white [Cloudflare-url]: https://cloudflare.com/