<!-- 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>
    &middot;
    <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](https://docs.docker.com/get-docker/) and Docker Compose
- A [Withings developer account](https://developer.withings.com/) with a registered app
- A [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) token

### Withings App Setup

1. Go to [developer.withings.com](https://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
   ```sh
   git clone https://github.com/npab19/withings-mcp.git
   cd withings-mcp
   ```

2. Copy the environment template
   ```sh
   cp .env.example .env
   ```

3. Fill in your credentials in `.env`:
   ```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
   ```sh
   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`:
```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](LICENSE) for more information.

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

## Acknowledgments

* [Withings Health API Documentation](https://developer.withings.com/api-reference/)
* [Model Context Protocol](https://modelcontextprotocol.io/)
* [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/)
* [Best-README-Template](https://github.com/othneildrew/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/