google-health-mcp

Servidor MCP para la API de Google Health, con caché SQLite local y análisis de tendencias.

Diseñado para Claude Code y otros clientes MCP. Tus datos se sincronizan en una base de datos en tu propia máquina, por lo que las consultas son rápidas, funcionan sin conexión y no consumen cuota de API.

Características

• Caché SQLite local: sincroniza una vez, consulta al instante

• Sincronización incremental: cada ejecución obtiene solo lo nuevo, reanudando desde donde se detuvo la anterior

• Modo sin conexión: sirve la caché sin credenciales y sin red

• Tendencias: agregados semanales, mensuales o trimestrales, y comparaciones entre dos períodos

• ECG: lecturas almacenadas completas, incluida la forma de onda, que se devuelven solo cuando se solicitan

• doctor: diagnostica una configuración sin conexión y de solo lectura, sin gastar cuota

Related MCP server: google-health-mcp-server

Tipos de datos

Requisitos

• Python 3.13+ (probado en 3.13 y 3.14 en CI)

• Una cuenta de Google con datos de salud y un proyecto de Google Cloud para autorizar. No se necesita cuenta de facturación: la consola ofrece una prueba gratuita durante toda la configuración y puedes rechazarla por completo.

Configuración

1. Instalación

pip install google-health-mcp

O ejecútalo sin instalarlo, en cuyo caso cada comando google-health-mcp ... que veas a continuación se convierte en uvx google-health-mcp ...:

uvx google-health-mcp --version

2. Crear el proyecto de Google Cloud

Cada usuario registra su propio cliente OAuth. Son siete pasos en la consola, y los nombres de las páginas son los de Google a fecha de agosto de 2026.

La página de configuración propia de Google te enviará a otro sitio: sigue los pasos a continuación. Su inicio rápido crea un cliente Web con https://www.google.com como URI de redirección, lo que se adapta al OAuth Playground más que a un programa que se ejecuta en tu máquina; este servidor rechaza ese archivo y así lo indica. Usa esa página solo para comprobar si alguna de las páginas siguientes ha cambiado de nombre.

1. Proyecto. Crea un proyecto en console.cloud.google.com/projectcreate y selecciónalo.

2. API. Habilita Google Health API en la página de habilitación de API.

3. Comenzar. Abre Google Auth Platform y completa Comenzar: nombre de la aplicación, correo de soporte, audiencia Externa, correo de contacto. Un proyecto nuevo no tiene páginas de Audiencia, Acceso a datos o Clientes hasta que se hace esto.

4. Audiencia. En Usuarios de prueba, añade tu propia cuenta de Google. Omitir esto hace que el inicio de sesión falle con 403: access_denied.

5. Acceso a datos. Haz clic en Añadir o eliminar permisos, busca "Google Health API" y marca los permisos de solo lectura que se indican en Permisos de OAuth a continuación.

6. Clientes. Crea un cliente OAuth de tipo Aplicación de escritorio y descarga su JSON. Un cliente de escritorio permite la redirección de bucle local automáticamente, por lo que no hay nada que registrar; un cliente web no lo hace y falla en el consentimiento.

7. Publicar. Vuelve a la página de Audiencia y haz clic en Publicar aplicación.

El paso 7 es el que más duele, y merece la pena comprobarlo en lugar de asumirlo. Mientras el estado de publicación de una aplicación es "Probando", Google emite tokens de actualización que caducan siete días después del consentimiento, así que todo funciona y, una semana después, la sincronización se detiene sin que nada apunte a este momento. La página de Audiencia puede indicar "En producción" mientras que el servidor de tokens no está de acuerdo. Dos lecturas que no fallan: la línea de estado de verificación en la página de Marca, y google-health-mcp doctor, que falla de forma visible cuando el token almacenado registra una caducidad corta.

3. Autorizar

Coloca el JSON del cliente descargado donde el servidor lo busca, sin editar:

mkdir -p ~/.config/google-health-mcp
cp ~/Downloads/client_secret_*.json ~/.config/google-health-mcp/google_client.json
google-health-mcp auth

Tu navegador te advertirá de que Google no ha verificado esta aplicación. Es de esperar, y la aplicación es tuya: estos permisos de salud están clasificados como restringidos y la verificación solo importa por encima de 100 usuarios. Haz clic en Avanzado y luego en Ir a google-health-mcp (no seguro), y concede los permisos.

El flujo escucha en localhost:8081 la devolución de llamada, por lo que ese puerto debe estar libre. Guarda los tokens en ~/.config/google-health-mcp/google_tokens.json con permisos 0600. Los tokens de acceso duran una hora y se renuevan automáticamente. Los tokens de actualización no rotan, por lo que un token emitido en una máquina con navegador se puede copiar a una sin interfaz.

Si autorizaste antes de publicar la aplicación, vuelve a ejecutar google-health-mcp auth después: publicar no amplía un token ya concedido, y ese sigue caducando a los siete días.

4. Regístrate en tu cliente MCP

claude mcp add -s user google-health -- google-health-mcp

Ejecutarlo con uvx en su lugar: claude mcp add -s user google-health -- uvx google-health-mcp.

5. Compruébalo

google-health-mcp doctor

Merece la pena ejecutarlo antes y después del paso 3 (Autorizar): informa de si el puerto 8081 está libre y de si este equipo puede abrir un navegador, que son las dos formas en las que auth falla antes de empezar.

Sin conexión y de solo lectura: informa de qué rutas se resuelven dónde, si los archivos de credenciales tienen la forma correcta, si el token es de corta duración y si la caché se mantiene al día.

6. Primera sincronización (opcional)

Las herramientas de consulta se sincronizan en el primer uso de cada día, por lo que puedes omitir esto. Para precargar la caché o para extraer un historial más antiguo:

google-health-mcp sync --days 30
google-health-mcp sync --since 2023-10-01     # backfill

Uso de la CLI

google-health-mcp                Start the MCP server (stdio transport)
google-health-mcp -V, --version  Print the installed package version
google-health-mcp auth           Interactive OAuth setup
google-health-mcp doctor         Check the setup and report what needs fixing
google-health-mcp sync           Sync data to the local cache
  --days N              Days of history for a first sync (default: 30)
  --types TYPE,...      Data types to sync (default: all). One or more of:
                        heart_rate, activity, exercises, sleep, weight, spo2,
                        hrv, azm, breathing_rate, skin_temperature,
                        core_temperature, cardio_fitness, food_log, ecg, irn
  --since YYYY-MM-DD    Fetch from this date, ignoring the incremental cursor
  --until YYYY-MM-DD    Inclusive end date for a --since window; together they
                        re-fetch exactly that window, to repair a gap in the
                        middle of the cache
google-health-mcp import         Import exported JSON data files
  --data-dir PATH       Directory containing the JSON files

Referencia de herramientas MCP

Las herramientas de consulta se sincronizan en la primera consulta de cada día por tipo de datos y luego leen la caché.

Todas las herramientas de consulta excepto health_get_devices y health_get_lifetime_stats, que no aceptan argumentos, aceptan:

• start_date: AAAA-MM-DD, AAAA-MM o 30d (relativo). Por defecto: últimos 30 días.

• end_date: AAAA-MM-DD. Por defecto: hoy.

• live: si es verdadero, vuelve a obtener esta ventana de la API antes de leer la caché. Una actualización fallida se notifica en lugar de responderse silenciosamente desde la caché.

health_get_exercises también acepta exercise_type, una coincidencia de subcadena que no distingue entre mayúsculas y minúsculas en el nombre del entrenamiento. health_get_ecg también acepta include_waveform: una traza son miles de voltajes, por lo que la respuesta predeterminada incluye la clasificación, la frecuencia media, la duración y un recuento de muestras.

health_sync

• data_types: all o un subconjunto separado por comas de los nombres que se indican en Uso de la CLI anterior (irn son las notificaciones de ritmo irregular). Por defecto: all.

• days: días de historial para una primera sincronización (por defecto: 30). Las sincronizaciones posteriores son incrementales.

• since / until: obtiene una ventana exacta independientemente de lo que haya en la caché.

health_trends

• data_type: cualquier tipo en caché con una serie diaria; las lecturas de ECG y las alertas de ritmo son episodios y no tienen tendencia. Por defecto: activity.

• period: weekly, monthly, quarterly. Por defecto: monthly.

• start_date / end_date: por defecto, los últimos 12 meses.

• compare: dos períodos, p. ej., last_30d vs previous_30d, 2026-03 vs 2026-02, 2026-Q1 vs 2025-Q4. Cuando se establece, se ignoran period, start_date y end_date.

Permisos de OAuth

Marca estos permisos de solo lectura en la página de Acceso a datos. Todos están en https://www.googleapis.com/auth/googlehealth.:

location.readonly y profile.readonly son dos que la consola ofrece y que este paquete solicita deliberadamente, porque nada de lo que hay aquí lee ninguna de las dos: la primera es la pista GPS que se registra durante un ejercicio.

Lee la lista de la consola, no de la página de permisos publicada: hay permisos de solo lectura que no aparecen ni en la documentación de Google ni en el propio documento de descubrimiento de la API, y el documento de descubrimiento omite nutrition.readonly por completo. Para solicitar menos, marca menos en la página de Acceso a datos y edita GOOGLE_SCOPES en config.py antes de autorizar, lo que requiere una copia del código fuente en lugar de una instalación con pip o uvx. Una concesión no gana permisos al renovarse, por lo que ampliar la lista más tarde significa ejecutar auth de nuevo.

Configuración

Modo sin conexión / solo caché

Por defecto, el servidor sincroniza bajo demanda, por lo que no se necesita ninguna tarea cron. Establece GOOGLE_HEALTH_MCP_OFFLINE=1 para ejecutarlo como un lector puro en su lugar:

• No se requieren credenciales: el servidor nunca abre el archivo de tokens.

• No se realiza ninguna llamada de red. La sincronización automática está desactivada, y live=True, health_get_devices y health_sync devuelven un mensaje claro que indica "offline mode" en lugar de acceder a la API.

• Las herramientas de consulta sirven los datos desde la caché, con la etiqueta "offline_mode": true.

Usos típicos:

• Varias máquinas, una caché: un host ejecuta google-health-mcp sync desde cron o systemd contra una base de datos compartida; los demás definen GOOGLE_HEALTH_MCP_OFFLINE=1, apuntan GOOGLE_HEALTH_MCP_DB_PATH al mismo archivo y solo leen.

• CI y privacidad: ejecuta consultas sin acceso a la red y sin credenciales.

Límites de peticiones

Google aplica una cuota de peticiones por usuario, documentada en developers.google.com/health/rate-limits. La sincronización normal no se acerca ni de lejos a esa cuota: la actualización de un día es un puñado de peticiones, y una carga retroactiva de tres años de todos los tipos de datos, medida en la práctica, rondó las 250. Si una sincronización se interrumpe, ese tipo de datos se registra como una sincronización parcial y la siguiente ejecución se reanuda desde su cursor en lugar de empezar de cero.

Consultar desde la caché, la opción predeterminada, no consume cuota alguna.

Seguridad de los datos

Tus datos de salud permanecen en tu máquina: este servidor no tiene backend, no envía nada a ningún sitio y solo se comunica con la API de Google con tus propias credenciales.

El repositorio incluye un hook de pre-commit que rechaza hacer commit de archivos de base de datos, cualquier cosa bajo config/, y archivos grandes; CONTRIBUTING.md explica cómo instalarlo.

Importación de datos existentes

Si ya tienes datos de salud como archivos JSON, procedentes de una exportación o de un script propio:

google-health-mcp import --data-dir /path/to/json/files/

Nombres de archivo esperados: heart_rate.json, activity.json, exercises.json, sleep.json, weight.json, spo2.json, hrv.json. Consulta src/google_health_mcp/importer.py para ver el formato que espera cada uno. La importación cubre esos siete tipos; todo lo demás llega mediante sync.

Contribuciones

Consulta CONTRIBUTING.md para la configuración de desarrollo, el flujo de trabajo de pruebas y el hook de pre-commit. Los cambios se registran en CHANGELOG.md.

Licencia

GPL-3.0-or-later