Servidor MCP para la Withings Health API con OAuth, caché local SQLite y análisis de tendencias.
Lo que hace diferente a este servidor de otros servidores MCP de Withings:
Caché local SQLite para consultas rápidas sin conexión y análisis histórico de tendencias
Sincronización incremental: solo obtiene datos nuevos desde la última sincronización
Amplia cobertura de Withings: 17 métricas de composición corporal más sueño, actividad diaria, entrenamientos y ECG/AFib
Refresco automático de tokens OAuth (tokens de acceso: 3 h, tokens de refresco: 1 año)
Cero dependencias más allá de mcp (HTTP vía stdlib)
Python 3.13+
Herramienta | Descripción | Fuente de datos |
| Sincroniza datos desde la API de Withings a la caché local | API en vivo -> SQLite |
| Composición corporal (peso, % grasa, músculo, hueso, PA, SpO2) | Caché local (auto-sincroniza si está obsoleto) |
| Resúmenes de sueño, o fases detalladas por hora con | Caché (resumen) / en vivo (detalle) |
| Pasos diarios, distancia, calorías, tiempo activo | Caché local (auto-sincroniza si está obsoleto) |
| Sesiones de entrenamiento con tipo, duración, frecuencia cardíaca | Caché local (auto-sincroniza si está obsoleto) |
| Registros de ECG y detección de AFib | API en vivo (siempre) |
| Dispositivos conectados con estado de batería | API en vivo (siempre) |
| Promedios por período, tendencias semanales/mensuales/trimestrales, comparaciones | Caché local (auto-sincroniza si está obsoleto) |
Las herramientas de consulta con respaldo en caché se sincronizan automáticamente cuando sus datos están desactualizados, y aceptan live=True para omitir la caché y obtener datos directamente de la API de Withings. withings_get_heart y withings_get_devices siempre usan datos en vivo. withings_get_sleep(detail=True) devuelve las fases de sueño minuto a minuto (en vivo, hasta 7 días por solicitud).
Related MCP server: Withings MCP Server
Python 3.13+
uv (recomendado) o pip
Una cuenta de desarrollador de Withings y una aplicación registrada
pip install withings-mcpO ejecútalo sin instalar con uvx withings-mcp. Para desarrollo desde un clon:
git clone https://github.com/partymola/withings-mcp.git
cd withings-mcp
uv venv --python 3.13 .venv
uv pip install -e .Crea una nueva aplicación
Establece la URL de devolución de llamada a http://localhost:8585
Anota tu Client ID y Client Secret
.venv/bin/withings-mcp authEsto abre tu navegador para la autorización de Withings. Después de aprobar, los tokens se guardan localmente en config/.
claude mcp add -s user withings -- /path/to/withings-mcp/.venv/bin/withings-mcpEn Claude Code, di: "Sincroniza mis datos de Withings"
Esto ejecuta withings_sync para poblar la caché local. Las sincronizaciones posteriores solo obtienen datos nuevos.
Si algo no funciona (no hay datos donde esperas, una sincronización que deja de ocurrir), ejecuta withings-mcp doctor. Informa sobre las rutas y credenciales realmente en uso y qué necesita corregirse, sin hacer una llamada a la API.
También puedes sincronizar desde la línea de comandos sin un cliente MCP:
.venv/bin/withings-mcp sync # all data types, last 30 days
.venv/bin/withings-mcp sync --types body,sleep # a subset
.venv/bin/withings-mcp sync --days 90 # deeper history on first syncwithings-mcp Start the MCP server (stdio transport)
withings-mcp auth Interactive OAuth setup (opens the browser)
withings-mcp sync Sync data to the local cache (--types, --days)
withings-mcp doctor Check the setup and report what needs fixing
withings-mcp --version Print the installed package versionVariable de Entorno | Valor por defecto | Descripción |
|
| Directorio para credenciales y tokens |
|
| Ruta de la base de datos SQLite |
(Note: The original table had two variables, but I see the original has WITHINGS_MCP_CONFIG_DIR and WITHINGS_MCP_DB_PATH with defaults ./config/ and ./withings.db respectively. I'll keep them.)
Wait, the original table says:
| WITHINGS_MCP_CONFIG_DIR | ./config/ | Directory for credentials and tokens |
| WITHINGS_MCP_DB_PATH | ./withings.db | SQLite database path |
I'll translate the descriptions: "Directorio para credenciales y tokens" and "Ruta de la base de datos SQLite".
Now the rest.
"Sincroniza mis datos de Withings"
"Muestra mi peso de los últimos 3 meses"
"¿Cómo ha cambiado mi sueño este año?"
"Compara mi composición corporal de este mes con la del mes pasado"
"¿Qué entrenamientos hice en marzo?"
"¿Qué dispositivos Withings tengo conectados?"
"Muestra mis tendencias de sueño del último año"
# Install with dev dependencies
uv pip install -e . && uv pip install pytest
# Run tests (all use in-memory SQLite with fictional data)
.venv/bin/python -m pytest tests/ -v # .venv\Scripts\python on WindowsSin modificación de datos: ninguna herramienta modifica datos en los servidores de Withings
Almacenamiento local: los datos se guardan en tu base de datos SQLite local
Almacenamiento de tokens: en config/ (ignorado por git; creado con modo 0600 en Unix; Windows ignora el modo y controla el acceso mediante ACL)
Mensajes de error: nunca contienen valores de datos de salud, solo códigos de estado
Pre-commit opcional: un hook opcional (scripts/check-no-data.sh) evita que archivos de base de datos y credenciales se incluyan en los commits; instálalo con el comando de una línea en CONTRIBUTING.md
Consulta CONTRIBUTING.md para la configuración de desarrollo, el flujo de trabajo de pruebas y el hook de pre-commit. Los cambios se rastrean en CHANGELOG.md.
GPL-3.0-or-later
Get daily activity summaries (steps, distance, calories, active time).
Returns one entry per day from the local cache by default. Run withings_sync first to populate the cache.
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "30d". Default: last 30 days. end_date: End date as "YYYY-MM-DD". Default: today. live: If true, fetch from Withings API instead of cache.
Returns daily activity data sorted by date, with steps, distance in km, calories, and active minutes by intensity level. Not for workout sessions -- use withings_get_workouts instead.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains behavior: default uses cache, optional live fetch from API, returns sorted daily data with specific fields. It lacks mention of rate limits or auth, but those are secondary for a read tool. Overall, it provides sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: summary, default behavior, arguments with defaults, return format, exclusion. It is concise but not overly terse—each sentence adds value. Could be slightly tighter, but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 optional params, cache mechanism, and an output schema (so return values are documented there), the description covers prerequisites, usage, and alternatives. It lacks error handling notes, but for this simple tool, it is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates by explaining start_date format ('YYYY-MM-DD', 'YYYY-MM', or '30d') and default (last 30 days), end_date format and default (today), and live boolean meaning. This adds value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets daily activity summaries with specific metrics (steps, distance, calories, active time). It distinguishes from withings_get_workouts by explicitly stating 'Not for workout sessions -- use withings_get_workouts instead.' The verb 'get' and resource 'activity' are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Run withings_sync first to populate the cache.' and 'Not for workout sessions -- use withings_get_workouts instead.' This provides clear when-to-use and when-not-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get body composition measurements (weight, fat, muscle, etc.).
Returns measurements from the local cache by default. Use live=True to fetch directly from Withings API. Run withings_sync first to populate the cache.
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "30d" for relative days. Default: last 30 days. end_date: End date as "YYYY-MM-DD". Default: today. metrics: Comma-separated metric filter, e.g. "weight_kg,fat_pct". Default: all available metrics. Names match exactly and are case-sensitive; one that is not on this list is refused, naming them. Options: weight_kg, height_m, lean_mass_kg, fat_pct, fat_mass_kg, muscle_mass_kg, hydration_kg, bone_mass_kg, heart_rate, systolic_bp, diastolic_bp, spo2_pct, temperature_c, body_temperature_c, pulse_wave_velocity, visceral_fat_index, basal_metabolic_rate.
live: If true, fetch from Withings API instead of cache.Returns measurements sorted by date, one entry per measurement group. Not for sleep or activity data -- use withings_get_sleep or withings_get_activity instead.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| metrics | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses behavior: cache default, live override, sync requirement, sorted results, one entry per group, and metric validation by refusing invalid names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized with a clear purpose statement, parameter list, and return info. The metric list is necessary for usability, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return format, exclusions, prerequisites, and alternatives, making it self-sufficient for an agent to decide and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the text provides thorough parameter details: date formats, defaults, exact metric options, and the live flag's effect, fully compensating for the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets body composition measurements and explicitly distinguishes from sleep and activity tools by pointing to withings_get_sleep and withings_get_activity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (body composition) and when not to (sleep/activity), plus provides guidance on cache vs. live fetching and the need to run withings_sync first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get connected Withings devices with battery and firmware info.
Always fetched live from the Withings API.
Returns device type, model name, battery level (high/medium/low), and last session date for each connected device.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool fetches live data and returns device type, model, battery level, and last session date. This is sufficient for a non-destructive tool with no parameters, though additional details on authentication or rate limits could be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the purpose. Every sentence adds value, and there is no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and the presence of an output schema (not shown but indicated), the description is complete. It covers the purpose, behavior, and return fields adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (0 params, 100% schema coverage). The description adds value by detailing what the return includes (battery level, firmware info), which goes beyond the empty schema. Baseline for 0 params is 4, and the added context warrants a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets connected Withings devices with battery and firmware info. The verb 'Get' and resource 'connected Withings devices' are specific, and it distinguishes itself from sibling tools that focus on other data types like activity or sleep.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It notes that the data is 'Always fetched live from the Withings API,' implying when to use this tool (for live device status). However, it does not explicitly mention when not to use it or suggest alternatives, though the sibling names naturally guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get ECG recordings and atrial fibrillation detection results.
Always fetched live from the Withings API (not cached due to large signal data). Requires a Withings device with ECG capability (ScanWatch, BPM Core).
Args: start_date: Start date as "YYYY-MM-DD" or "30d". Default: last 30 days. end_date: End date as "YYYY-MM-DD". Default: today.
Returns ECG recording list with timestamps, AFib classification (negative/positive/inconclusive), and heart rate. Does not include raw signal waveforms. For resting heart rate trends, use withings_get_body or withings_get_sleep instead.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: always fetched live (not cached), requires specific devices, returns ECG list with timestamps and AFib classification, and explicitly excludes raw waveforms. Minor omission: no mention of pagination or rate limits, but given simplicity of tool, transparency is high.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise yet comprehensive: first sentence states purpose, then caching behavior, device requirements, parameter details in a clear list, return summary, and alternative tool. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 2 optional parameters and an output schema, the description covers all essential aspects: input semantics, output contents, behavioral constraints, and sibling differentiation. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully compensates: specifies date formats ('YYYY-MM-DD' or '30d' for start, 'YYYY-MM-DD' for end), defaults (last 30 days, today), and purpose (define date range for ECG recordings). Adds meaning beyond schema's basic string type.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool fetches 'ECG recordings and atrial fibrillation detection results', distinguishing it from sibling tools like withings_get_body (resting heart rate trends) and withings_get_sleep. The verb 'Get' and specific resource are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: requires a Withings device with ECG capability (ScanWatch, BPM Core), and advises to use withings_get_body or withings_get_sleep instead for resting heart rate trends. No ambiguity about when to use this vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get sleep data (summaries or detailed phases).
Summary mode (default): nightly totals with duration, sleep score, HR, respiratory rate, and snoring. From local cache unless live=True.
Detail mode (detail=True): minute-by-minute sleep phases (awake, light, deep, REM) with HR and respiratory rate. Always fetched live. Maximum 7 days per request (Withings API limit).
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "7d". Default: last 7 days (detail) or last 30 days (summary). end_date: End date as "YYYY-MM-DD". Default: today. detail: If true, return minute-by-minute sleep phases instead of nightly summaries. Always live, max 7 days. live: If true, fetch summaries from API instead of cache. Ignored when detail=True (always live).
Returns nightly sleep data sorted by date. Not for body composition -- use withings_get_body instead.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| detail | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavioral traits: summary uses local cache unless live=True, detail always fetched live, live is ignored when detail=True, default date ranges differ by mode. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections for summary/detail, bullet points for parameters, and a separate line for return value. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema, the description does not need to detail return values. It covers all necessary context: modes, parameter behaviors, caveats (max 7 days), and sibling differentiation, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description provides extensive parameter details: start_date format options ('YYYY-MM-DD', 'YYYY-MM', '7d'), default behavior for both modes, end_date default, and flags effect. Fully compensates for schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets sleep data in two modes (summary or detail), lists what each mode returns, and explicitly distinguishes from sibling tool withings_get_body for body composition. The verb 'Get' and resource 'sleep' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use summary vs detail, when to use live flag, and explicitly tells when not to use (for body composition, use withings_get_body). It also notes the maximum 7-day limit for detail mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get workout sessions (type, duration, HR, calories).
Returns individual workout sessions from the local cache by default. Run withings_sync first to populate the cache.
Args: start_date: Start date as "YYYY-MM-DD", "YYYY-MM", or "90d". Default: last 90 days. end_date: End date as "YYYY-MM-DD". Default: today. category: Filter by workout type, case-insensitive partial match. A value matching none of the categories below is refused, naming the ones your cache holds. Options: badminton, baseball, basketball, bmx, bodyboard, boxing, calisthenics, climbing, cycling, dancing, elliptical, fencing, football, golf, handball, hiking, hockey, horse_riding, ice_hockey, ice_skating, indoor_cycling, indoor_running, indoor_walk, kitesurfing, martial_arts, multi_sport, other, pilates, rowing, rugby, run, skating, skiing, snowboarding, soccer, squash, surfing, swimming, table_tennis, tennis, volleyball, walk, waterpolo, weightlifting, windsurfing, wrestling, yoga, zumba.
live: If true, fetch from Withings API instead of cache.Returns workout sessions sorted by date with type, duration, calories, distance, and heart rate data. Not for daily step/activity totals -- use withings_get_activity.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | ||
| category | No | ||
| end_date | No | ||
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavior. It clearly states it returns data 'sorted by date with type, duration, calories, distance, and heart rate data' and explains the default cache vs. live API behavior. It does not mention potential side effects (e.g., API rate limits), but as a read-only operation with no mutation, this is sufficient for transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary, an 'Args' section, and a return/exclusion note. It is front-loaded with the purpose. The category list is long but necessary for completeness. Minor redundancy (repeating 'from cache' in both the first line and the 'live' description) could be trimmed, but overall it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (not shown here), the description need not enumerate return fields in detail, but it does mention the return content. It covers prerequisites, parameter semantics, and the scope limitation. It is complete enough for an agent to know when and how to invoke the tool without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema provides no descriptions (0% coverage), the description text thoroughly explains each parameter. It specifies date formats ('YYYY-MM-DD', 'YYYY-MM', or '90d'), defaults ('last 90 days', 'today'), the category filter case-insensitivity and the full list of options, and the 'live' flag's effect. This adds meaningful semantics beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get workout sessions (type, duration, HR, calories).' It also explicitly distinguishes itself from the sibling tool by noting 'Not for daily step/activity totals -- use withings_get_activity.' The verb 'Get' and the resource 'workout sessions' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-not guidance ('Not for daily step/activity totals') and names the alternative tool. It also gives a prerequisite: 'Run withings_sync first to populate the cache.' Additionally, it explains the 'live' parameter for fetching from the API instead of cache, offering clear decision-making guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync Withings health data to the local cache.
Fetches data from the Withings API and stores it in SQLite for fast offline queries. Run this before using other withings_get_* tools.
Syncs incrementally: only fetches data newer than the last sync. First sync fetches the specified number of days of history.
Args: data_types: What to sync. Options: "all", "body", "sleep", "activity", "workouts". Comma-separated for multiple, e.g. "body,sleep". Default: "all". days: Days of history for first sync (default: 30). Ignored on subsequent syncs (uses last sync timestamp).
Returns summary of records synced per data type. Not for querying data - use withings_get_body, withings_get_sleep, withings_get_activity, or withings_get_workouts instead.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | ||
| data_types | No | all |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses incremental sync behavior, first sync history fetching, storage in SQLite, and return summary. Missing minor details like API rate limits or authentication, but still comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear heading, paragraphs, bullet points, and explicit sections for args and returns. It is concise yet complete, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and an output schema, the description covers purpose, usage guidelines, parameter semantics, behavioral details, and returns. It fully equips the AI agent to select and invoke the tool correctly, even in the context of sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add full meaning. It explains data_types options with examples and default, and clarifies that 'days' applies only to the first sync. This adds significant value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Sync Withings health data to the local cache.' It uses a specific verb-resource pair and explicitly distinguishes from sibling query tools like withings_get_body and withings_get_sleep.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'Run this before using other withings_get_* tools' and 'Not for querying data - use withings_get_body, withings_get_sleep, withings_get_activity, or withings_get_workouts instead.' It clearly tells the AI agent when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyse trends in cached health data.
Computes averages, min/max, and changes over time from the local cache. Auto-syncs if the cache is stale (no sync today).
Args: data_type: What to analyse. Options: "body", "sleep", "activity". period: Aggregation period. Options: "weekly", "monthly", "quarterly". Default: "monthly". start_date: Start date as "YYYY-MM-DD" or "12m" for relative. Default: last 12 months. end_date: End date as "YYYY-MM-DD". Default: today. compare: Compare two periods. Format: "last_30d vs previous_30d", "2026-03 vs 2026-02", "2026-Q1 vs 2025-Q4". When set, period/start_date/end_date are ignored.
Returns aggregated averages with change indicators. For body data: weight, fat%, muscle trends. For sleep: duration, score, HR trends. For activity: steps, distance, calorie trends. Not for raw data -- use withings_get_body/sleep/activity instead.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | monthly | |
| compare | No | ||
| end_date | No | ||
| data_type | No | body | |
| start_date | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It states the computation/return behaviour and the auto-sync side effect, but it does not fully spell out whether the sync mutates local storage or whether network access may occur; the mention of auto-sync implies this but leaves some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well organised but contains some redundancy: 'Computes averages, min/max, and changes over time' is repeated as 'Returns aggregated averages with change indicators'. Still, it is concise overall and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, parameters, return content per data type, and explicitly routes raw-data requests to sibling getter tools. It also clarifies the cache/sync context, making it self-contained for an agent deciding between this tool and its siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema lacks descriptions, the prose explains every parameter: data_type options, period enum/default, start_date/end_date formats and defaults, and compare format including the rule that compare overrides the other date parameters. This is more than enough for an agent to fill the arguments correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: analysing trends in cached health data with aggregates (averages, min/max, changes). It explicitly distinguishes itself from raw-data getters by naming the alternative tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete guidance on when to use the tool (trends/aggregates) and when not to use it ('Not for raw data -- use withings_get_body/sleep/activity instead'). It also explains the auto-sync behaviour when the cache is stale, providing useful context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.8.0withings_trends2 fields changedInput schema / properties / data_type / enumAdded value: +[
+ "body",
+ "sleep",
+ "activity"
+]Input schema / properties / period / enumAdded value: +[
+ "weekly",
+ "monthly",
+ "quarterly"
+]v0.1.0withings_get_activitywithings_get_bodywithings_get_deviceswithings_get_heartwithings_get_sleepwithings_get_workoutswithings_syncwithings_trendsScored across 8 tools
Each tool targets a distinct data domain: activity, workouts, body composition, sleep, heart ECG, devices, and trend analysis. Cross-references are used effectively to prevent confusion between similar tools like activity vs workouts and body vs sleep.
Most tools follow a clear withings_get_<resource> pattern, making the set predictable. The exceptions are withings_sync and withings_trends, which break the get- verb pattern but are still understandable and not chaotic.
With 8 tools, the server is well-scoped for a health-data integration covering sync, raw data retrieval, and analysis. Each tool has a clear purpose and the count feels neither bloated nor thin.
The tool surface covers the major Withings health domains: activity, workouts, body composition, sleep, heart/ECG, devices, and trend analysis. The sync tool provides a reasonable update mechanism, and there are no obvious dead ends or missing lifecycle operations.
Read wearables and lab health data — sleep, activity, workouts, timeseries, lab tests and orders.
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Read sleep, readiness, activity, stress, heart rate and workouts from the Oura Ring.
Read WHOOP recovery, sleep, cycles, workouts and body measurements.