{
  "markdown": "# withings-mcp\n\n<!-- mcp-name: io.github.partymola/withings-mcp -->\n\n[![CI](https://github.com/partymola/withings-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/partymola/withings-mcp/actions/workflows/ci.yml)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/withings-mcp)](https://pypi.org/project/withings-mcp/)\n[![Glama MCP Server](https://glama.ai/mcp/servers/partymola/withings-mcp/badges/score.svg)](https://glama.ai/mcp/servers/partymola/withings-mcp)\n\nMCP server for the [Withings Health API](https://developer.withings.com/) with OAuth, local SQLite cache, and trend analysis.\n\n**What makes this different from other Withings MCP servers:**\n- Local SQLite cache for fast offline queries and historical trend analysis\n- Incremental sync - only fetches new data since last sync\n- Broad Withings coverage: 17 body-composition metrics plus sleep, daily activity, workouts, and ECG/AFib\n- Automatic OAuth token refresh (access tokens: 3h, refresh tokens: 1 year)\n- Zero dependencies beyond `mcp` (HTTP via stdlib)\n- Python 3.13+ (tested on 3.13 and 3.14, on Linux, macOS and Windows, in CI)\n\n## Tools\n\n| Tool | Description | Data source |\n|------|-------------|-------------|\n| `withings_sync` | Sync data from Withings API to local cache | Live API -> SQLite |\n| `withings_get_body` | Body composition (weight, fat%, muscle, bone, BP, SpO2) | Local cache (auto-syncs if stale) |\n| `withings_get_sleep` | Sleep summaries, or detailed phase time-series with `detail=True` | Cache (summary) / live (detail) |\n| `withings_get_activity` | Daily steps, distance, calories, active time | Local cache (auto-syncs if stale) |\n| `withings_get_workouts` | Workout sessions with type, duration, HR | Local cache (auto-syncs if stale) |\n| `withings_get_heart` | ECG recordings and AFib detection | Live API (always) |\n| `withings_get_devices` | Connected devices with battery status | Live API (always) |\n| `withings_trends` | Period averages, weekly/monthly/quarterly trends, comparisons | Local cache (auto-syncs if stale) |\n\nThe cache-backed query tools auto-sync when their data is stale, and accept `live=True` to bypass the cache and fetch straight from the Withings API. `withings_get_heart` and `withings_get_devices` are always live. `withings_get_sleep(detail=True)` returns minute-by-minute sleep phases (live, up to 7 days per request).\n\n## Prerequisites\n\n- Python 3.13+ (tested on 3.13 and 3.14, on Linux, macOS and Windows, in CI)\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n- A Withings developer account and registered application\n\n## Installation\n\n```bash\npip install withings-mcp\n```\n\nOr run it without installing with `uvx withings-mcp`. For development from a clone:\n\n```bash\ngit clone https://github.com/partymola/withings-mcp.git\ncd withings-mcp\nuv venv --python 3.13 .venv\nuv pip install -e .\n```\n\n## Setup\n\n### 1. Register a Withings app\n\n1. Go to https://developer.withings.com/dashboard\n2. Create a new application\n3. Set the callback URL to `http://localhost:8585`\n4. Note your Client ID and Client Secret\n\n### 2. Authenticate\n\n```bash\n.venv/bin/withings-mcp auth\n```\n\nThis opens your browser for Withings authorization. After approving, tokens are saved locally in `config/`.\n\n### 3. Register with Claude Code\n\n```bash\nclaude mcp add -s user withings -- /path/to/withings-mcp/.venv/bin/withings-mcp\n```\n\n### 4. First sync\n\nIn Claude Code, say: \"Sync my Withings data\"\n\nThis runs `withings_sync` to populate the local cache. Subsequent syncs only fetch new data.\n\nIf anything does not work - no data where you expect it, a sync that stops happening - run `withings-mcp doctor`. It reports the paths and credentials actually in use and what needs fixing, without making an API call.\n\nYou can also sync from the command line without an MCP client:\n\n```bash\n.venv/bin/withings-mcp sync                      # all data types, last 30 days\n.venv/bin/withings-mcp sync --types body,sleep   # a subset\n.venv/bin/withings-mcp sync --days 90            # deeper history on first sync\n```\n\n## CLI\n\n```\nwithings-mcp              Start the MCP server (stdio transport)\nwithings-mcp auth         Interactive OAuth setup (opens the browser)\nwithings-mcp sync         Sync data to the local cache (--types, --days)\nwithings-mcp doctor       Check the setup and report what needs fixing\nwithings-mcp --version    Print the installed package version\n```\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `WITHINGS_MCP_CONFIG_DIR` | `./config/` | Directory for credentials and tokens |\n| `WITHINGS_MCP_DB_PATH` | `./withings.db` | SQLite database path |\n\n## Example Prompts\n\n- \"Sync my Withings data\"\n- \"Show my weight for the last 3 months\"\n- \"How has my sleep changed this year?\"\n- \"Compare my body composition this month vs last month\"\n- \"What workouts did I do in March?\"\n- \"What Withings devices do I have connected?\"\n- \"Show my sleep trends quarterly\"\n\n## Development\n\n```bash\n# Install with dev dependencies\nuv pip install -e . && uv pip install pytest\n\n# Run tests (all use in-memory SQLite with fictional data)\n.venv/bin/python -m pytest tests/ -v      # .venv\\Scripts\\python on Windows\n```\n\n## Security\n\n- **Read-only**: No tools modify data on Withings servers\n- **Local storage**: Health data stays in your local SQLite database\n- **Token storage**: OAuth tokens stored in `config/` (gitignored; created 0600 on POSIX - Windows ignores the mode and governs access by ACLs)\n- **Error messages**: Never contain health data values - only status codes\n- **Pre-commit hook**: An optional hook (`scripts/check-no-data.sh`) blocks database files and credentials from commits - install it with the one-liner in [CONTRIBUTING.md](https://github.com/partymola/withings-mcp/blob/main/CONTRIBUTING.md)\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/partymola/withings-mcp/blob/main/CONTRIBUTING.md) for development setup, the test workflow, and the pre-commit hook. Changes are tracked in [CHANGELOG.md](https://github.com/partymola/withings-mcp/blob/main/CHANGELOG.md).\n\n## License\n\nGPL-3.0-or-later\n",
  "bytes": 6314,
  "sha": "546b0a285f8ac6a0d81b6d7b56c1cb5425a6287262e34df0e1168769c57bec9a",
  "repo_slug": "partymola/withings-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_partymola_withings_mcp_6eef496a/readme"
}