Withings MCP Server

A Model Context Protocol (MCP) server that brings your Withings health data into Claude. Access your sleep patterns, body measurements, workouts, heart data, and more through natural conversation.

🔒 Privacy First: This is my personal project, and the repository is intentionally public to demonstrate transparency. The code shows that no personal information is logged or stored maliciously. All sensitive data (tokens, user IDs) is encrypted at rest and automatically redacted from logs. You can review the entire codebase to verify this commitment to privacy.

⚠️ Disclaimer: This server is provided as-is without any guarantees or warranties. While I've made every effort to ensure security and privacy, I make no guarantees about availability, data integrity, or security. Use at your own risk. For production use cases, consider self-hosting your own instance.

What Can You Do With This?

This MCP server gives Claude access to your Withings health data, allowing you to:

Analyze your sleep: Ask about sleep quality, duration, deep sleep stages, heart rate during sleep
Track body metrics: Weight trends, body composition, blood pressure, heart rate over time
Review workouts: Analyze exercise patterns, calories burned, heart rate zones
Monitor heart health: Access ECG recordings and detailed heart data
Set and track goals: Review your fitness and health goals
Identify patterns: Find correlations between sleep, activity, and other metrics
Generate insights: Get AI-powered analysis of your health trends

All through natural conversation with Claude or any other MCP-compatible client.

For End Users: Using the Hosted Server

If you just want to use this MCP server with Claude Desktop without hosting anything yourself, follow these steps:

Prerequisites

A Withings account with connected devices
Claude Desktop or any other MCP-compatible client installed on your computer

Setup Instructions

Step 1: Add Connector in Claude Desktop

Open Claude Desktop
Go to Settings (gear icon in the bottom-left corner)
Navigate to the Connectors tab
Click Add Custom Connector
Fill in the following details:
- Name: Withings (or any name you prefer)
- Remote MCP server URL: https://withings-mcp.com/mcp
Click Add

Note: If your MCP client doesn't support UI-based connector configuration, you can manually edit the config file instead. See the manual configuration guide below.

Step 2: Connect and Authorize

In the Connectors settings, find the Withings connector you just added
Click Connect next to the connector
Your web browser will open with the Withings authorization page
Log in to your Withings account
Review and approve the permissions requested
You'll be redirected back and the connection will be complete

After authorization, Claude will have access to your Withings data!

Available Tools

Once connected, Claude can use these tools to access your data:

Sleep & Activity

get_sleep_summary - Sleep duration, stages (light/deep/REM), heart rate, breathing, sleep score
get_activity - Daily steps, distance, calories, elevation, activity durations
get_intraday_activity - High-frequency activity data throughout the day
get_workouts - Detailed workout summaries with heart rate zones and metrics

Body Measurements

get_measures - Weight, body composition, blood pressure, heart rate, temperature, VO2 max, and more

Devices & Goals

get_user_devices - List of connected Withings devices
get_user_goals - Your health and fitness goals (steps, sleep, weight)

Heart Health

list_heart_records - List of ECG recordings
get_heart_signal - Detailed ECG waveform data

Stethoscope (if you have BPM Core)

list_stetho_records - List of stethoscope recordings
get_stetho_signal - Detailed audio signal data

Example Conversations

Try asking Claude:

"How has my sleep quality been over the past week?"
"Show me my weight trend for the last month"
"What's my average resting heart rate?"
"Did I hit my step goal this week?"
"Compare my workout intensity between this month and last month"
"When did I sleep best this month?"

Privacy & Security

Encrypted tokens: All authentication tokens are encrypted using AES-256-GCM before storage
No logging of personal data: The code is public - you can verify that no sensitive information is logged
Automatic redaction: All user IDs, tokens, and credentials are automatically redacted from system logs
OAuth 2.0: Industry-standard secure authentication with Withings
You're in control: Revoke access anytime from your Withings account settings

For Developers: Self-Hosting

Want to run your own instance? Here's how to deploy this MCP server yourself.

Prerequisites

Node.js 18+ and npm installed
Deno CLI installed for deployment
A Withings Developer Account

Step 1: Create Withings Application

Go to Withings Developer Portal
Create a new application
Note your Client ID and Client Secret
Set your Redirect URI to: https://your-domain.com/callback
- This must be a publicly accessible URL (localhost is not supported by Withings)
- Can be any domain where you'll host the server (e.g., Deno Deploy, your own server, etc.)

Step 2: Clone and Setup

# Clone the repository
git clone https://github.com/your-username/withings-mcp.git
cd withings-mcp

# Install dependencies
npm install

# Generate encryption secret
npm run generate-secret
# Copy the output - you'll need it for environment variables

Step 3: Local Development

Note: Withings requires a publicly accessible URL for OAuth callbacks. For local development, use a tunneling service to expose your local server or deploy to a staging environment for testing.

# Copy environment template
cp .env.example .env

# Edit .env with your values
# WITHINGS_CLIENT_ID=your_client_id
# WITHINGS_CLIENT_SECRET=your_client_secret
# WITHINGS_REDIRECT_URI=https://your-tunnel-url.com/callback
# ENCRYPTION_SECRET=paste_generated_secret_here
# PORT=3000

# Build the project
npm run build

# Run locally
npm start

Make sure your redirect URI in the .env file matches the publicly accessible URL pointing to your local server.

Step 4: Deploy to Production

# Build the project
npm run build

# Deploy to your hosting platform of choice
# The build output is in the ./build directory

Set the following environment variables on your hosting platform:

Variable	Required	Example
`WITHINGS_CLIENT_ID`	Yes	`your_client_id`
`WITHINGS_CLIENT_SECRET`	Yes	`your_client_secret`
`WITHINGS_REDIRECT_URI`	Yes	`https://your-domain.com/callback`
`ENCRYPTION_SECRET`	Yes	Generated from step 2
`PORT`	No	`3000` (or your platform's default)
`LOG_LEVEL`	No	`info`
`ALLOWED_ORIGINS`	No	`https://example.com,https://app.example.com`

Step 5: Update Withings App Settings

Go back to your Withings developer app and update the redirect URI to match your deployed URL: https://your-domain.com/callback

Step 6: Configure Your MCP Client

For Claude Desktop:

Open Claude Desktop
Go to Settings → Connectors tab
Click Add Custom Connector
Fill in the following details:
- Name: Withings (or any name you prefer)
- Remote MCP server URL: https://your-domain.com/mcp
Click Add
Click Connect next to the connector to authorize

For Other MCP Clients:

Configure your MCP client with the following connection details:

Server URL: https://your-domain.com
Transport: Server-Sent Events (SSE)
Endpoint: /mcp
Authentication: OAuth 2.0
Discovery URL: /.well-known/oauth-authorization-server

Environment Variables Reference

Variable	Required	Description
`WITHINGS_CLIENT_ID`	Yes	Your Withings app client ID
`WITHINGS_CLIENT_SECRET`	Yes	Your Withings app client secret
`WITHINGS_REDIRECT_URI`	Yes	OAuth callback URL (must match Withings app settings)
`ENCRYPTION_SECRET`	Yes	32+ character secret for token encryption (generate with `npm run generate-secret`)
`PORT`	No	Server port (default: 3000)
`LOG_LEVEL`	No	Logging level: trace, debug, info, warn, error (default: info)
`ALLOWED_ORIGINS`	No	Comma-separated list of allowed CORS origins for browser clients

Development Commands

npm run build            # Compile TypeScript to JavaScript
npm run dev              # Watch mode - recompile on changes
npm run generate-secret  # Generate encryption secret for ENCRYPTION_SECRET env variable

Project Structure

src/
├── auth/              # OAuth 2.0 authentication & token storage
├── server/            # Hono app, MCP endpoints, middleware
├── tools/             # MCP tools for Withings API (sleep, measure, user, heart, stetho)
├── transport/         # Custom SSE transport for MCP
├── withings/          # Withings API client
├── utils/             # Logger and encryption utilities
└── index.ts           # Main entry point

See CLAUDE.md for detailed architecture documentation.

Security Features

Token Encryption

All Withings access and refresh tokens are encrypted at rest using AES-256-GCM:

Algorithm: AES-256-GCM (authenticated encryption)
Key Derivation: PBKDF2 with 100,000 iterations
Defense in Depth: Even if the database is compromised, tokens remain protected

Important: Keep your ENCRYPTION_SECRET:

At least 32 characters long
Randomly generated (use npm run generate-secret)
Secure and never committed to version control
Consistent across server restarts

Privacy-Safe Logging

The custom logger automatically redacts all sensitive information:

✅ Operational events and errors logged
❌ No tokens, credentials, or auth codes
❌ No user IDs or personal information
❌ No API request/response payloads with sensitive data

You can review the logging implementation in src/utils/logger.ts.

Contributing

This is a personal project, but contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

Issues: Report bugs or request features on GitHub Issues
Withings API: See Withings API Documentation
MCP Protocol: See Model Context Protocol Documentation

Acknowledgments

Built with:

Model Context Protocol by Anthropic
Withings API
Hono web framework
Deno Deploy for hosting

Name		Name	Last commit message	Last commit date
Latest commit History 81 Commits
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
deno.json		deno.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

akutishevsky/withings-mcp

Folders and files

Latest commit

History

Repository files navigation

Withings MCP Server

Table of Contents

What Can You Do With This?

For End Users: Using the Hosted Server

Prerequisites

Setup Instructions

Step 1: Add Connector in Claude Desktop

Step 2: Connect and Authorize

Available Tools

Sleep & Activity

Body Measurements

Devices & Goals

Heart Health

Stethoscope (if you have BPM Core)

Example Conversations

Privacy & Security

For Developers: Self-Hosting

Prerequisites

Step 1: Create Withings Application

Step 2: Clone and Setup

Step 3: Local Development

Step 4: Deploy to Production

Step 5: Update Withings App Settings

Step 6: Configure Your MCP Client

For Claude Desktop:

For Other MCP Clients:

Environment Variables Reference

Development Commands

Project Structure

Security Features

Token Encryption

Privacy-Safe Logging

Contributing

License

Support

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages