Withings MCP Server

A Model Context Protocol server that wraps the Withings Health API — including the full OAuth2 handshake and token refresh — so an MCP client (Claude, etc.) can read your smart-scale data: weight, body fat, muscle mass, bone mass, water, and more.

It runs as a remote, hosted server on AWS Lambda (Streamable-HTTP transport), with:

• Withings credentials in SSM Parameter Store SecureString parameters (KMS-encrypted).
• OAuth tokens in DynamoDB (encrypted at rest), refreshed automatically.
• A server-side /callback route that completes the OAuth code exchange for you.
• A bearer-key guard on the MCP endpoint so only you can reach it.

It also runs locally (single process, JSON-file token cache) for development.

---

Architecture

  MCP client ──Bearer key──▶  Lambda Function URL
                                   │
                    ┌──────────────┴───────────────┐
                    │  Starlette ASGI app (Mangum)  │
                    │   /mcp       Streamable-HTTP  │──▶ tools
                    │   /callback  OAuth code→token │
                    │   /health                     │
                    └───────┬───────────────┬───────┘
                            │               │
                  SSM SecureString     DynamoDB
                (client_id/secret/key)  (tokens + oauth state)
                            │
                            └──▶ Withings API (account.withings.com, wbsapi.withings.net)

Why Lambda + Streamable-HTTP: the transport runs stateless (one self-contained JSON request/response per call), which maps cleanly onto Lambda — no long-lived SSE connection to hold open. Tokens live in DynamoDB precisely because Lambda containers are ephemeral.

---

Tools

Tool	Description
withings_connection_status	Whether an account is linked and when the token expires.
withings_start_authorization	Returns an authorization_url to open in a browser to grant access.
withings_get_measurements	Weight + body-composition groups, filterable by meastypes, start_date/end_date, days, limit.
withings_get_latest_weight	The most recent weigh-in with full body composition.
withings_list_measure_types	All Withings measurement type codes with names/units.
withings_disconnect	Delete the stored tokens.

Measurement values are returned already decoded (Withings sends value + unit exponent; the server computes value × 10^unit), e.g. {"weight": {"value": 70.5, "unit": "kg"}}.

---

Prerequisites

1. A Withings developer account and application: developer.withings.com → Dashboard → create an app. Note the Client ID and Client Secret. You will add a Callback URL after the first deploy (step 5).
2. AWS account with credentials configured (aws configure).
3. AWS SAM CLI (brew install aws-sam-cli or install docs) and Python 3.12.

---

Deploy to AWS (Lambda)

1. Store secrets in SSM Parameter Store

These are KMS-encrypted SecureStrings (default aws/ssm key — no extra cost) and are never placed in the CloudFormation template or Lambda env vars.

WITHINGS_CLIENT_ID=xxxxxxxx \
WITHINGS_CLIENT_SECRET=yyyyyyyy \
./scripts/setup-ssm.sh

The script generates a random MCP API key and prints it — save it, your MCP client sends it as Authorization: Bearer <key>. (Override with MCP_API_KEY=... , or change the SSM prefix with SSM_PREFIX=....)

2. Build

sam build

3. First deploy (redirect URL not known yet)

cp samconfig.toml.example samconfig.toml   # edit region if needed
sam deploy --guided                        # accept defaults; leave PublicBaseUrl empty

When it finishes, note the stack Outputs:

• FunctionUrl — e.g. https://abc123.lambda-url.eu-west-1.on.aws/
• McpEndpoint — that URL + mcp
• RedirectUri — that URL + callback

4. Register the callback in Withings

In your Withings app settings, add the RedirectUri from the outputs (exactly, including https:// and /callback) to the app's Callback URLs.

5. Redeploy with the public base URL

The server needs to know its own address to build the OAuth redirect_uri. Pass the FunctionUrl without a trailing slash:

sam deploy --parameter-overrides \
  "SsmPrefix=/withings-mcp PublicBaseUrl=https://abc123.lambda-url.eu-west-1.on.aws"

That's it — the server is live.

---

Connect an MCP client

Point your client at the McpEndpoint (.../mcp) with the bearer header.

For a client that supports remote HTTP MCP servers with headers, e.g.:

{
  "mcpServers": {
    "withings": {
      "type": "streamable-http",
      "url": "https://abc123.lambda-url.eu-west-1.on.aws/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_API_KEY" }
    }
  }
}

Claude Desktop's stdio config doesn't send custom headers directly. If your client can't attach an Authorization header, use a local bridge such as mcp-remote: npx mcp-remote https://.../mcp --header "Authorization: Bearer YOUR_MCP_API_KEY".

First-run authorization

1. Ask the client to call withings_start_authorization.
2. Open the returned authorization_url, sign in to Withings, approve.
3. You're redirected to /callback, which stores your tokens and shows a success page.
4. Call withings_connection_status to confirm, then withings_get_latest_weight or withings_get_measurements.

Access tokens are refreshed automatically using the stored refresh token, so this is a one-time step.

---

Local development

python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env          # fill in Withings client id/secret
python scripts/run_local.py   # serves http://localhost:8000

Register http://localhost:8000/callback as a callback URL in your Withings app and set PUBLIC_BASE_URL=http://localhost:8000 in .env. Tokens are cached to ~/.withings-mcp/tokens.json. The MCP endpoint is http://localhost:8000/mcp.

Run the tests (no network/AWS needed):

pytest

---

Security notes

• Secrets never leave SSM except as decrypted values inside the Lambda execution environment. The IAM role grants ssm:GetParameter* scoped to <prefix>/* and kms:Decrypt only ViaService ssm.
• The MCP endpoint is bearer-protected. The Function URL is AuthType: NONE (so Withings can reach /callback), but /mcp requires your key, compared in constant time. Rotate it by re-running setup-ssm.sh with a new MCP_API_KEY.
• /callback is public but CSRF-protected: it only accepts an OAuth state that this server issued (stored in DynamoDB with a 10-minute TTL) and consumes it once.
• Tokens sit in DynamoDB with encryption at rest (AWS-owned KMS key by default). For a customer-managed key, add an SSESpecification with SSEType: KMS and your key ARN in template.yaml.
• This is a single-user server ("my scale data"). To support multiple Withings accounts, key the token store by the Withings userid returned in the token response instead of the fixed tokens partition key.

---

Measurement type reference (common scale metrics)

Code	Metric	Unit
1	Weight	kg
5	Fat-free mass	kg
6	Fat ratio	%
8	Fat mass weight	kg
76	Muscle mass	kg
77	Hydration	kg
88	Bone mass	kg
170	Visceral fat	—

Call withings_list_measure_types for the full set (blood pressure, heart rate, SpO₂, temperature, pulse wave velocity, etc.).

---

License

MIT