garua 0.30.0

CLI interactiva y servidor MCP para consultar estaciones SENAMHI y descargar datos hidrometeorológicos históricos del Perú.

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.

---

Documentación: garua.danyneyra.dev

Código fuente: 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

Tarea	Descripción
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.

Formas de uso

Garúa puede usarse de tres maneras:

• App interactiva: ejecuta garua y navega por un menú en terminal. Es ideal para explorar estaciones y descargar datos paso a paso.
• Comandos directos: usa parámetros cuando ya conoces la estación y el periodo, o cuando quieres automatizar búsquedas y descargas.
• Servidor MCP: conecta Garúa con VS Code, Claude Desktop, Codex u otros clientes de IA compatibles con Model Context Protocol.

Instalación rápida

Requisitos principales:

• Python 3.11+.
• Windows, macOS o Linux.
• Google Chrome, Brave o Microsoft Edge para las descargas desde SENAMHI.

Instala Garúa desde PyPI:

pip install garua

También puedes instalarlo con pipx si quieres usarlo como herramienta global de terminal:

pipx install garua

Verifica la instalación:

garua --help
garua --doctor

La guía completa está en Instalación.

Uso rápido

Abre la app interactiva:

garua

Busca estaciones desde la línea de comandos:

garua --search Cabana

Descarga un mes específico:

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

Ejecuta el servidor MCP:

garua-mcp

Nota: 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 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.

Codex

Claude Desktop

Ver configuración completa en Configurar MCP y más ejemplos en Uso MCP.

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

Documentación

• Primeros pasos
• Instalación
• Uso CLI
• Uso MCP
• Ejemplos completos
• Referencia de herramientas MCP
• Variables de entorno
• Changelog

Guías principales

• Buscar estaciones
• Descargar datos
• Explorar CSV
• Resumir un periodo
• Comparar periodos
• Validar calidad de datos
• Recomendar estaciones

Desarrollo

git clone https://github.com/danyneyra/garua.git
cd garua
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

En Linux o macOS:

source .venv/bin/activate

Más detalles en Arquitectura y Contribuir.

Licencia

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