Saltar a contenido

Garúa

Logo de Garúa

Garúa descarga, explora y analiza datos hidrometeorológicos oficiales del SENAMHI Perú.

Garúa es la llovizna fina característica de la costa peruana.

PyPI Python License: MIT

Documentación: https://garua.danyneyra.dev

Código fuente: https://github.com/danyneyra/garua

Garúa es una herramienta de código abierto para trabajar con estaciones meteorológicas e hidrológicas del SENAMHI. Permite buscar estaciones, descargar datos históricos en CSV, revisar archivos locales, resumir periodos, comparar meses o años, validar calidad de datos y recomendar estaciones cercanas a un punto geográfico.

Qué puedes hacer

  • Buscar estaciones

    Filtra estaciones por nombre, código, ubicación, tipo, altitud o cercanía a un punto geográfico.

  • Descargar históricos

    Obtén datos mensuales, anuales o multianuales en archivos CSV listos para revisar o procesar.

  • Analizar periodos

    Resume precipitación, temperatura, humedad, viento o nivel de río según el tipo de estación.

  • Validar calidad

    Detecta duplicados, fechas faltantes, valores S/D, trazas T y otros problemas frecuentes.

Elige tu flujo

  • App interactiva

    Ejecuta garua y navega por un menú en terminal. Es ideal para explorar estaciones y descargar datos paso a paso.

    Ver uso interactivo

  • Comandos directos

    Usa parámetros cuando ya conoces la estación y el periodo, o cuando quieres automatizar búsquedas y descargas.

    Ver comandos CLI

  • Servidor MCP

    Conecta Garúa con VS Code, Claude Desktop, Codex u otros clientes de IA compatibles con Model Context Protocol.

    Ver uso MCP

Instalación

Requisitos: Python 3.11+

Antes de instalar Garúa, asegúrate de tener Python disponible en tu sistema. Se recomienda usar una versión reciente de Python y revisar la guía oficial Python Setup and Usage si necesitas ayuda con la instalación.

Navegador basado en Chromium

Para descargar datos en CSV desde SENAMHI, Garúa necesita abrir un navegador local basado en Chromium, como Google Chrome, Brave o Microsoft Edge. En Windows, Microsoft Edge suele venir instalado con el sistema operativo.

Con Python instalado, ejecuta este comando desde tu terminal 1:

Powershell 
pip install garua
████████████████████████████████ 100%

Ver la guía completa de Instalación.

Uso rápido

Abre la app interactiva:

$ garua

 ╭─── Garúa v0.30.0 ───────────────────────────────────╮
 │                                                     │
 │  GARUA                                              │
 │  Datos meteorológicos e hidrológicos                │
 │  del SENAMHI del Perú                               │
 │  Consulta estaciones. Descarga históricos           │
 │                                                     │
 ╰─────────────────────────────────────────────────────╯
 ───────────────────────────────────────────────────────
 BÚSQUEDA DE ESTACIÓN
 ───────────────────────────────────────────────────────
 💧 Código o nombre (ej: 472D30C8 o SIHUAS):

Si todo se ejecutó correctamente, ya puedes usar Garúa 🎉

También puedes ejecutar acciones directas con parámetros.

Buscar estaciones desde la línea de comandos:

garua --search Cabana

Descargar un mes específico:

garua --station 108047 --mode month --year 2025 --month 7

Ejecutar el servidor MCP:

garua-mcp

Vista MCP

Garúa también funciona como servidor MCP: puedes pedir tareas en lenguaje natural y el cliente usa las herramientas de Garúa para buscar estaciones, descargar datos o analizar CSV. Puedes ver la configuración completa en Configurar MCP y más ejemplos en Uso MCP.

Nota sobre descargas

Cuando pidas descargar datos, Garúa abrirá un navegador local para consultar el sitio de SENAMHI y superar la verificación Cloudflare Turnstile cuando aparezca. Esto es esperado en la herramienta de descarga.

Vista de Garúa MCP en Codex

Puedes descargarlo desde la web oficial de Codex.

Vista de Garúa MCP en Claude Desktop

Puedes descargarlo desde la web oficial de Claude Desktop.

Ejemplos en un cliente MCP:

Busca estaciones meteorológicas en Arequipa sobre 3000 msnm
Recomienda una estación para lat -7.61, lon -77.82 con altitud 3000 msnm
Descarga datos de febrero 2025 de la estación Cabana
Resume diciembre 2025 para la estación 107008
Compara marzo 2025 vs marzo 2026 para Cabana

Siguientes pasos

  • Primeros pasos

    Sigue el camino corto para instalar Garúa, buscar una estación y descargar tu primer CSV.

    Ir a primeros pasos

  • Guías de uso

    Revisa flujos concretos para buscar estaciones, descargar datos, explorar CSV y analizar periodos.

    Ver guías

  • Desarrollo

    Consulta la arquitectura del proyecto si quieres contribuir o entender cómo está organizado Garúa.

    Ver arquitectura

Licencia

Este proyecto se publica bajo los términos de la licencia MIT.

  1. Puedes usar terminales como PowerShell, CMD, Warp, etc. ↩