Personal Health Data (community)

Compatible with Withings.

An unofficial, community-built plugin. It is not affiliated with, endorsed or sponsored by Withings. For general wellness and informational use only. It is not a medical device and not medical advice (see Disclaimer). It reads only your own data, through Withings' Public API (https://developer.withings.com), using a Withings developer app that you create for yourself. It is read-only: it cannot change anything in your Withings account or on your devices.

Withings is a trademark of Withings. The name is used here only to say which service the plugin is compatible with. No Withings logo or artwork is used.

It is a small stdio MCP server (Node.js 18+, no dependencies, no install step) packaged as a Cursor plugin, plus one skill that tells the agent when to use the tools. It works with any MCP client that can launch a local stdio server (Cursor, Grok Bot, Claude Desktop and others). The entry point is server/index.mjs; the setup CLI is server/cli.mjs.

New here? Start with the walkthrough

Setting this up is not super straightforward, but if you follow the steps exactly it should be fine. It is mostly copy-pasting. The first time takes about 10–15 minutes.

docs/SETUP-WITHINGS.md is the step-by-step for someone who has never used a developer portal. The short version of the callback: if you do not have a website, register exactly http://localhost:8765/callback (the plugin's default; it can answer that address on your own computer). An assistant should call setup_guide and give you one step at a time. Before anyone opens the Withings link, auth_status / start_authorization name the redirect the running process will actually send, and whether that value was configured or just the default.

Related MCP server: Withings MCP Server

Tools

Range tools take start_date / end_date (YYYY-MM-DD, your local dates; up to 366 days per call). Values are decoded from Withings' value × 10^unit format into the units named in each field. Metrics your device didn't measure are null, never 0. Every result carries data_source: "Withings".

The plugin requests only the read scopes user.info, user.metrics and user.activity. It never requests anything that can write. Withings may still add user.sleepevents to the grant it returns; that scope only drives sleep-event webhook notifications, which this plugin doesn't use. auth_status shows both lists: requested_scopes and granted_scopes (with any extras explained under extra_granted_scopes).

Install

There is nothing to install: the server uses only Node.js built-ins, so there is no npm install / npm ci step (a package-lock.json with no packages is included so npm ci also succeeds). Get the code and run it with Node:

git clone https://github.com/emilniclashofseth/personal-health-data-mcp.git
cd personal-health-data-mcp
node server/index.mjs          # stdio MCP server (normally your MCP client starts it)

In Cursor you can instead install it from the directory: https://cursor.directory/plugins/personal-health-data-community

Setup (about 10–15 minutes the first time)

Follow docs/SETUP-WITHINGS.md if this is your first time. The rest of this section is the same setup, shorter, for reference.

You need a Withings account with your devices synced in the Withings app. Withings' current terms say that sharing data with a third-party service may require an active Withings+ subscription (Terms of Use §6.4.1); check this if authorization works but data calls fail.

1. Create your own Withings developer app

1. Open the Withings Developer Dashboard: https://developer.withings.com/dashboard/ and sign in. You can use your normal Withings account. Withings' guide: https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/developer-account/create-your-accesses-no-medical-cloud

2. Create an application: Public API integration on the Public Cloud (free; endpoint https://wbsapi.withings.net).

3. Give it any name and description that is your own, e.g. "My health data". Don't call it "Withings …".

4. Callback URL — pick one, and register it exactly. The plugin's default, used whenever WITHINGS_REDIRECT_URI is unset, is http://localhost:8765/callback. auth_status shows the value the running process will send (redirect_uri), whether you set it or it was defaulted (redirect_uri_defaulted, redirect_uri_source), and a warning to compare it with the dashboard before you open Withings. If they differ, Withings shows redirect_uri_mismatch and does not give you a code.

   • No website of your own: http://localhost:8765/callback. Leave WITHINGS_REDIRECT_URI empty. Withings accepts http/localhost callbacks for apps in the integration (development) phase, which is limited to 10 users. That's fine because the only user is you. With this callback the plugin finishes the setup by itself when the browser is on the same computer: it listens on 127.0.0.1:8765 for up to 10 minutes after you start authorization. Use a different port by registering it and setting WITHINGS_REDIRECT_URI to the same value. Do not point the callback at a third-party redirect service; the browser is sent there with a one-time code.

   • If the dashboard rejects localhost: register any HTTPS URL you control (e.g. a page on your own website). The page doesn't have to do anything. After you approve, your browser lands on https://your-url?code=…&state=…. Copy that whole address within 30 seconds (Withings codes are valid for 30 s and work once) and give it to the setup CLI or the exchange_code tool. Set WITHINGS_REDIRECT_URI to exactly the URL you registered.

5. Save. The dashboard shows your Client ID and Secret (you can look them up there again later).

2. Give the client id and secret to the server

The server reads WITHINGS_CLIENT_ID, WITHINGS_CLIENT_SECRET and, if you didn't use the default callback, WITHINGS_REDIRECT_URI. Pass them in one of two ways (never paste the secret into chat, a project file or a commit):

• WITHINGS_ENV_FILE (recommended outside Cursor): the absolute path of a 600 file with KEY=value lines:

  WITHINGS_CLIENT_ID=your-client-id
  WITHINGS_CLIENT_SECRET=your-secret
  # optional:
  # WITHINGS_REDIRECT_URI=http://localhost:8765/callback
  # WITHINGS_TOKEN_FILE=/absolute/path/tokens.json

  Only those four names are read; blank lines, # comments, export and quotes are allowed; nothing is shell-expanded. Variables set directly in the server's environment win over the file.

• Directly as environment variables in your client's settings for the server.

The env file is re-read on every auth_status, setup_guide, start_authorization, and exchange_code call, so a callback change in that file shows up on the next call. Values in the process environment (Cursor's Configure fields, or variables you exported in the shell) were copied in when the process started. They do not change until a new process starts, and they override the file. auth_status reports process_started_at, config_read_at, redirect_uri_source (default, environment, or env_file), and config_stale_warning when the file and the environment disagree.

Then register the server with your MCP client and restart/reload it when you set or change environment variables:

• Cursor: install the plugin. When it asks for settings, paste the Client ID into WITHINGS_CLIENT_ID and the Secret into WITHINGS_CLIENT_SECRET (and the callback URL into WITHINGS_REDIRECT_URI if you didn't use the default). To change them later: Plugins → Personal Health Data (community) → Configure, then reload the window.

• Any other client: see Use with other MCP clients.

3. Authorize once

Ask the agent to "set up Withings" (it calls start_authorization), or run it yourself:

WITHINGS_ENV_FILE=/absolute/path/to/withings.env node server/cli.mjs authorize

(Putting the secret on the command line instead, WITHINGS_CLIENT_ID=... WITHINGS_CLIENT_SECRET=... node server/cli.mjs authorize, also works but leaves it in your shell history.) The CLI must use the same WITHINGS_TOKEN_FILE as your MCP server (the default path, unless you set one). Open the printed URL, sign in to Withings and approve. With the localhost callback and the browser on the same computer, the page says "Connected" and you're done. With your own HTTPS callback, paste the full redirect URL when the CLI asks (within 30 seconds). Check with auth_status or node server/cli.mjs status.

Then ask something like "How has my weight and body fat changed this month?"

Browser and server on different computers

The localhost callback only completes by itself when the browser runs on the same machine as the server, because Withings redirects your browser to http://localhost:8765/callback, i.e. to the browser's own machine.

The common case for a hosted assistant is exactly that: the plugin runs on the assistant's computer, and your browser is on your own computer. The localhost page fails to load. That is expected. Copy the whole address from the address bar (http://localhost:8765/callback?code=…&state=…) and paste it back to the assistant right away (within 30 seconds). The assistant passes it to exchange_code on the same server process that ran start_authorization.

The same paste works if the server is a remote box, a container, or an SSH session. At the CLI, paste it at the Redirect URL (or wait): prompt of the same node server/cli.mjs authorize run.

Or forward the port before you approve: ssh -L 8765:127.0.0.1:8765 you@server, then the redirect reaches the server's listener through the tunnel and finishes by itself.

Use with other MCP clients (Grok Bot, Claude Desktop, etc.)

The bundled mcp.json is for Cursor: ${CURSOR_PLUGIN_ROOT} and ${WITHINGS_…} are Cursor plugin variables, and other clients will not expand them. Elsewhere, point the client at server/index.mjs with an absolute path (no ~, no ${...}) and pass the credentials by file:

{
  "mcpServers": {
    "personal-health-data": {
      "command": "node",
      "args": ["/absolute/path/to/personal-health-data-mcp/server/index.mjs"],
      "env": { "WITHINGS_ENV_FILE": "/absolute/path/to/withings.env" }
    }
  }
}

• command may need the absolute path to node (which node) if the client does not inherit your shell's PATH.

• Put secrets in env (better: in the env file), never in args: args show up in process lists.

• On Windows use a path like "C:\\Users\\you\\personal-health-data-mcp\\server\\index.mjs".

Keeping secrets out of client configs: launcher script

If your client can only run a command, or you want one place to manage credentials, use a launcher that points the server at the 600 env file and execs it. The client config then names only the script. A copy is in examples/run-health-data.sh:

#!/usr/bin/env bash
set -euo pipefail
ROOT=/absolute/path/to/personal-health-data-mcp
export WITHINGS_ENV_FILE="${WITHINGS_ENV_FILE:-$HOME/.config/personal-health-data-mcp/withings.env}"
[ -r "$WITHINGS_ENV_FILE" ] || { echo "run-health-data: env file missing or unreadable" >&2; exit 1; }
exec node "$ROOT/server/index.mjs"

Client config: {"command": "/absolute/path/to/run-health-data.sh", "args": []}. Keep the script, the env file and the token file outside any repository you commit.

Tokens, lifetime and re-authorizing

• Tokens are stored in ~/.config/personal-health-data-mcp/tokens.json ($XDG_CONFIG_HOME if set; on Windows %APPDATA%\personal-health-data-mcp\tokens.json), outside any project, with the folder at mode 700 and the file at 600. Your Withings user id is not stored.

• WITHINGS_TOKEN_FILE (env or env file) sets another absolute path, e.g. to keep it next to your other secrets or to give separate installs separate files. The server creates the folder (700) and file (600) when you authorize.

• Sharing one token file between installs (two MCP clients, two machines with a synced folder, a dev copy and an installed copy): the refresh token rotates on every refresh and the old one stops working soon after. Sharing is only safe when every process uses the same file on the same filesystem and the same lock: an exclusive flock on the sidecar file <token file>.lock (for example tokens.json.lock), re-reading the token file after taking the lock and saving by atomic rename. This plugin does that from v0.3.1 (through the flock, perl or python3 command; on Windows it only serialises within one process). Your own script can join in, e.g. Python: fcntl.flock(open(path + ".lock", "a"), fcntl.LOCK_EX). Never delete the lock file. Don't share the token file with tools that lock differently, copy it between machines, or put it on a synced/network folder where the lock doesn't work: one side will refresh, the other will keep an outdated refresh token, and you'll have to re-authorize. If in doubt, give each install its own WITHINGS_TOKEN_FILE and authorize each once.

• Per Withings' docs (https://developer.withings.com/developer-guide/v3/integration-guide/public-health-data-api/get-access/access-and-refresh-tokens-no-recover): the access token expires after 3 hours; the refresh token expires after 1 year; and every refresh returns a new refresh token. The old one stops working 8 hours later or as soon as the new access token is used.

• The server refreshes the access token automatically when it has less than 10 minutes left (or when Withings rejects it) and saves the new pair straight away, under a file lock, so two processes don't race on the rotating token.

• Re-authorize (run step 3 again) if the refresh token expired (about a year without use), if you revoked access in the Withings app, if you changed the app's secret, or if a tool says the token was rejected. Running authorization again simply replaces the token file.

• Revoke access at any time in the Withings app (connected apps/partners), or delete the app in the developer dashboard. Deleting the token file removes local access.

Privacy and security

• The client secret is stored either by your MCP client (e.g. Cursor's plugin settings) and passed to the local server as an environment variable, or in a file you control (WITHINGS_ENV_FILE) that the server reads at runtime. It is sent only to Withings (wbsapi.withings.net), and only when tokens are issued or refreshed.

• Errors are redacted. The secret, codes and tokens are never logged or returned by any tool.

• No telemetry, no third-party servers, no server run by the author. The code sends requests only to Withings. Your data goes from Withings to the computer running the server and then to your MCP client and the AI model you use there, under those providers' terms. Make sure you are comfortable sharing health data with that model.

• The author of this plugin does not receive, store or have access to your credentials, tokens or data. Tokens are kept only in the local token file described above.

• This is for your own data. Don't use it to run a service for other people, and don't share your app's secret. Each person who installs the plugin creates their own Withings app, so no one else's app or server sits between you and Withings.

Troubleshooting

The same cases, with the wording to expect, are in docs/SETUP-WITHINGS.md ("If you get this error, do this").

• Redirect URI mismatch. Withings shows redirect_uri_mismatch / "does not match partner callback url" instead of the approval page, or exchange_code / the CLI says it rejected the callback and names redirect_uri=…. The value this process sends (redirect_uri in auth_status) must equal a Callback URL in your developer app character for character: scheme (http vs https), host (localhost vs 127.0.0.1), port, path, and trailing slash. redirect_uri_defaulted: true means WITHINGS_REDIRECT_URI is unset and the server is using http://localhost:8765/callback — register that exact URL, or set the variable to the URL you already registered. If redirect_uri_source is environment, restart or reload so a new process starts. If it is env_file, the next auth call re-reads the file; a set environment variable still wins (config_stale_warning). Then run start_authorization again. The code from the failed attempt can't be reused.

• Changed the settings but the old value is still in use. Compare process_started_at with when you edited. Environment variables are frozen for the life of the process (a Cursor reload that does not actually respawn the server leaves the old value). The env file is not frozen. config_note says which redirect this process used. config_stale_warning is set when the env file and the environment disagree. For the redirect it names both URLs. For WITHINGS_CLIENT_ID or WITHINGS_CLIENT_SECRET it names the variable only and does not print the value.

• Code expired / invalid (status 304, "invalid code"). Codes last about 30 seconds, work once, and must be exchanged by the same server process that started the authorization. exchange_code says this separately from a callback mismatch. Run start_authorization again and paste the new address immediately. If the pasted address's callback is not the one this server is using, the code is not sent (so it is not used up) and the error names both URLs.

• "Not set up yet" although you set the values: your client probably passed the literal ${WITHINGS_CLIENT_ID} (only Cursor expands it). Use an absolute WITHINGS_ENV_FILE. auth_status shows env_file_problem if the file can't be read.

• State mismatch: the pasted redirect belongs to a different start_authorization. Start again; don't reuse the code.

• The localhost page will not load: the browser is not on the same computer as the plugin. That includes a hosted assistant (plugin on the assistant's computer, browser on yours). Copy the full address bar and paste it back to the assistant within 30 seconds, or forward the port (ssh -L 8765:127.0.0.1:8765 you@server).

• Port 8765 in use: free it, or register another localhost port and set WITHINGS_REDIRECT_URI to match.

• Token rejected after it worked before: see "Sharing one token file" above; re-authorize. If you changed the callback since authorizing, redirect_changed_warning says so; data calls keep working until you re-authorize.

• get_sleep_summary returns nothing: no sleep device is linked in Withings. Check list_devices.

Limits and caveats

• Withings asks partners not to poll more than about once every 10 minutes per user and reports rate limiting as status 601. The server spaces calls, retries 601/HTTP 5xx with backoff, and only calls the API when you ask.

• Body composition from a scale is an estimate. One step-on can be stored as several measurement groups a few seconds apart; the server merges groups from the same device that are at most 2 minutes apart into one row.

• Not included: writing or deleting data, ECG waveforms, intraday streams, webhooks/notifications.

• Field meanings follow Withings' API reference (https://developer.withings.com/api-reference) and may change when Withings updates it.

Development

npm test                     # offline tests: node --test test/*.test.mjs (mocked Withings HTTP; no credentials)
npm run test:live            # a few real read-only calls against your own account (needs env + a token file)
npm run authorize            # one-time authorization (CLI)

No dependencies, no install step (npm ci works with the empty lockfile but isn't needed). The code: server/client.mjs (OAuth, token file, refresh, retries, redirect warnings), server/auth-flow.mjs (localhost callback listener), server/setup-guide.mjs (the walkthrough setup_guide returns), server/tools.mjs (tools and output shapes), server/index.mjs (MCP stdio JSON-RPC), server/cli.mjs (setup CLI). The human setup steps are docs/SETUP-WITHINGS.md.

Disclaimer

• Not medical advice. This plugin retrieves data you already have in your Withings account, for general wellness and informational purposes only. It is not a medical device and is not intended to diagnose, treat, cure, monitor or prevent any disease or condition. Values (including blood pressure, heart rate and the device's own estimates such as body composition, metabolic or vascular age) come from consumer devices, may be missing or inaccurate, and are passed on as Withings reports them. Don't make medical decisions based on them; ask a doctor or other qualified health professional about any health concern. Any interpretation an AI assistant adds is the assistant's, not this plugin's.

• Your data. The plugin runs on the computer where you start it and talks only to Withings, using your own developer app. It has no telemetry and no server of its own, and the author does not receive, store or have access to your credentials, tokens or data. Your MCP client and AI model provider handle the data under their own terms, which you choose.

• Unofficial. Community project, compatible with Withings; not affiliated with, endorsed or sponsored by Withings. Withings is a trademark of Withings, used only to say what the plugin is compatible with.

• Provided as is, use at your own risk. No warranty of any kind (see LICENSE). You are responsible for following Withings' terms (Terms of Use and developer/API terms) and for your own data.

License

MIT (provided "as is", without warranty). See LICENSE. Not affiliated with Withings.