Overview

This repository implements a minimal Model Context Protocol (MCP) server tailored for Withings health data. It acts as a secure broker between Withings OAuth-protected APIs and model-driven tools that need short-lived, consented access to user health data. The server demonstrates best practices for consent flow, token handling, and tool-level access control while remaining small and easy to adapt.

For developers building integrations that combine personal health information with AI models, this server is useful as a reference and starting point. It includes a simple example tool (a “count characters in phrases” endpoint) so you can see how to expose functionality to models through the MCP pattern without exposing raw credentials or long-term tokens.

Features

Minimal MCP-compliant server for Withings data access
OAuth2 authorization and token management for Withings accounts
Example tool: “count characters in phrases” — demonstrates an MCP tool implementation
Short-lived, consented model access patterns to avoid exposing persistent credentials
Configurable via environment variables and easily deployed with Docker
Basic security guidance: token encryption, webhook verification, TLS recommendation

Installation / Configuration

Clone the repository and choose either Docker or a local Node.js run.

Using Git and Docker:

git clone https://github.com/akutishevsky/withings-mcp.git
cd withings-mcp
docker-compose up -d

Run locally (Node.js):

git clone https://github.com/akutishevsky/withings-mcp.git
cd withings-mcp
# install dependencies if included
npm install
# set env variables then
npm start

Example .env (rename to .env or set environment variables directly):

PORT=3000
WITHINGS_CLIENT_ID=your_withings_client_id
WITHINGS_CLIENT_SECRET=your_withings_client_secret
WITHINGS_REDIRECT_URI=https://yourhost.example.com/mcp/oauth/callback
MCP_SIGNING_SECRET=a_random_secret_for_mcp
TOKEN_ENCRYPTION_KEY=32_byte_hex_or_base64_key
WEBHOOK_SECRET=optional_webhook_verification_secret

Common environment variables and meaning:

Variable	Description
PORT	HTTP port for the MCP server
WITHINGS_CLIENT_ID	Withings OAuth client ID
WITHINGS_CLIENT_SECRET	Withings OAuth client secret
WITHINGS_REDIRECT_URI	OAuth redirect for the consent flow
MCP_SIGNING_SECRET	Secret to sign MCP messages / tokens
TOKEN_ENCRYPTION_KEY	Key used to encrypt stored tokens (recommended)
WEBHOOK_SECRET	If using webhooks, secret to verify payloads

Security notes:

Always run behind TLS in production.
Use a strong, secret TOKEN_ENCRYPTION_KEY and store it securely.
Limit token lifetime and refresh access only when necessary.
Validate and verify webhooks from Withings.

Available Tools / Resources

Included example tool:

count-characters: simple endpoint that accepts a phrase and returns the character count. This shows how to implement a stateless MCP tool that a model can call without direct access to Withings tokens.

Useful resources:

Project repository: https://github.com/akutishevsky/withings-mcp
Withings API docs: (refer to Withings documentation for OAuth scopes and endpoints)
MCP specification: follow your organization’s Model Context Protocol guidelines for message formats and signing

Example API usage (count characters):

Request:

curl -X POST "https://your-mcp.example.com/tools/count-characters" \
  -H "Content-Type: application/json" \
  -d '{"text": "how many characters?"}'

Response:

{
  "text": "how many characters?",
  "character_count": 21
}

Use Cases

Secure model-assisted analytics: Allow an LLM to request aggregated Withings data (e.g., weekly step summaries) through the MCP server, which enforces consent and supplies only the data the model is permitted to see.
Research and prototyping: Quickly prototype model interactions with health data using the included “count characters” tool as a learning example for how to expose additional tools safely.
Multi-tenant HIPAA-aware integrations: Use the server’s token management and short-lived access patterns to reduce risk when integrating multiple users’ Withings accounts into AI workflows.
Audit-friendly deployments: Centralize the OAuth flow and token refresh logic so you can log and audit model requests for compliance purposes without leaking persistent credentials.

Extending the Server

To add a new tool:

Implement a new endpoint that follows the MCP message format expected by your models.
Validate MCP-signed requests using MCP_SIGNING_SECRET.
Limit the tool’s access to only the scopes required; do not accept raw Withings tokens from callers.
Add unit tests covering consent checks, token retrieval, and error handling.

This server is intentionally minimal to serve as a reference implementation. For production use, add robust logging, monitoring, rate limiting, and formal pen-testing to match your organization’s security posture.

Withings MCP Server: Secure Health Data Access