SNOTEL MCP Server

Proporciona acceso a datos meteorológicos y de nieve de USDA SNOTEL.

Documentación

SNOTEL MCP Server

Un servidor de Model Context Protocol (MCP) construido con FastMCP para acceder a datos meteorológicos y de nieve del USDA SNOTEL (SNOwpack TELemetry) a través de la API REST de AWDB (Air and Water Database).

Este servidor proporciona a asistentes de IA como Claude acceso a condiciones de nieve en tiempo real e históricas, datos meteorológicos y análisis de la capa de nieve de más de 800 estaciones SNOTEL en el oeste de los Estados Unidos.

Características

🏔️ Descubrimiento de Estaciones

Buscar por estado: Obtén todas las estaciones SNOTEL en cualquier estado
Buscar por ubicación: Busca estaciones dentro de un radio de coordenadas
Detalles de la estación: Accede a metadatos completos de la estación

📊 Acceso a Datos

Datos históricos: Recupera profundidad de nieve, SWE, temperatura y precipitación
Condiciones recientes: Obtén las últimas lecturas y tendencias recientes
Rangos de fechas personalizados: Consulta cualquier período de tiempo con resolución diaria

📈 Herramientas de Análisis

Tendencias de la capa de nieve: Analiza condiciones máximas y patrones estacionales
Seguimiento de tormentas: Identifica eventos de nevadas y acumulaciones
Resúmenes estadísticos: Calcula promedios, máximos y conteos de días de nieve

Inicio Rápido

Requisitos Previos

Python 3.9+
uv administrador de paquetes (recomendado) o pip

Instalación

# Clone the repository
git clone https://github.com/example/snotel-mcp-server.git
cd snotel-mcp-server

# Create and activate virtual environment with uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

# Or install development dependencies
uv pip install -e ".[dev]"

Ejecutando el Servidor

FastMCP maneja toda la configuración de transporte automáticamente:

# Run with default stdio transport
python -m snotel_mcp_server

# Or if installed
snotel-mcp-server

Uso con Claude Desktop

Añade a tu configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "snotel": {
      "command": "python",
      "args": ["-m", "snotel_mcp_server"],
      "cwd": "/path/to/snotel-mcp-server"
    }
  }
}

O si se instaló mediante pip:

{
  "mcpServers": {
    "snotel": {
      "command": "snotel-mcp-server"
    }
  }
}

Herramientas Disponibles

`find_snotel_stations`

Encuentra estaciones SNOTEL por estado o ubicación geográfica.

Parámetros:

state (opcional): Abreviatura del estado (ej., "CO", "MT")
latitude (opcional): Latitud para búsqueda por ubicación
longitude (opcional): Longitud para búsqueda por ubicación
radius_miles (opcional): Radio de búsqueda en millas (predeterminado: 50)
network (opcional): Tipo de red (predeterminado: "SNTL")

Ejemplos:

Find all SNOTEL stations in Colorado
Find SNOTEL stations within 25 miles of Aspen, Colorado (39.1911, -106.8175)

`get_station_info`

Obtén información detallada sobre una estación SNOTEL específica.

Parámetros:

station_triplet (obligatorio): Identificador de la estación (ej., "713:CO:SNTL")

Ejemplo:

Get information about Red Mountain Pass station (713:CO:SNTL)

`get_station_data`

Recupera datos crudos de nieve y meteorológicos de una estación en formato JSON.

Parámetros:

station_triplet (obligatorio): Identificador de la estación
start_date (obligatorio): Fecha de inicio (AAAA-MM-DD)
end_date (obligatorio): Fecha de fin (AAAA-MM-DD)
elements (opcional): Tipos de datos ["SNWD", "WTEQ", "TOBS", "PREC"]
duration_name (opcional): Duración de las mediciones ["DAILY", "HOURLY", "MONTHLY"]

Devuelve: Datos JSON crudos de la API SNOTEL

Ejemplos:

Get raw JSON data from Red Mountain Pass for March 2025
Get hourly temperature data from Wolf Creek Pass for a specific day
Get monthly averages for a station over a year

`get_recent_conditions`

Obtén condiciones recientes de una estación (últimos 30 días por defecto).

Parámetros:

station_triplet (obligatorio): Identificador de la estación
days (opcional): Número de días recientes (predeterminado: 30)

Ejemplo:

What are current conditions at Loveland Pass?
Show me the last 14 days of data from Independence Pass

`analyze_snowpack_trends`

Analiza tendencias de la capa de nieve y calcula estadísticas para un período de tiempo.

Parámetros:

station_triplet (obligatorio): Identificador de la estación
start_date (obligatorio): Fecha de inicio del análisis
end_date (obligatorio): Fecha de fin del análisis

Ejemplos:

Analyze snowpack trends at Wolf Creek for the 2024-2025 season
Compare peak snow conditions between March 2024 and March 2025 at Red Mountain Pass

Conversaciones de Ejemplo

Encontrando Estaciones

User: "Find SNOTEL stations near Aspen, Colorado"
Assistant: I'll find SNOTEL stations near Aspen for you.

[Uses find_snotel_stations with coordinates for Aspen]

Found 5 SNOTEL stations within 50 miles of Aspen:
• Independence Pass (589:CO:SNTL) - 12,095 ft
• Grizzly Peak (457:CO:SNTL) - 11,900 ft  
• Schofield Pass (737:CO:SNTL) - 10,707 ft
...

Obteniendo Condiciones Actuales

User: "What are current snow conditions at Red Mountain Pass?"
Assistant: I'll check the current conditions at Red Mountain Pass.

[Uses get_recent_conditions for station 713:CO:SNTL]

Recent Conditions: Red Mountain Pass (713:CO:SNTL)
Latest Reading: 2025-05-26
• Snow Depth: 21.0"
• Snow Water Equivalent: 8.2"
• Temperature: 29.3°F

Analizando Tendencias

User: "How did March 2025 compare to typical March conditions at Wolf Creek?"
Assistant: I'll analyze March 2025 snowpack trends at Wolf Creek.

[Uses analyze_snowpack_trends for March 2025]

March 2025 Analysis:
• Peak Depth: 156" on March 15th
• Total New Snow: 67"
• Snow Days: 12
• Above average snowfall for March

Elementos de Datos

El servidor admite estas mediciones comunes de SNOTEL:

SNWD: Profundidad de nieve (pulgadas)
WTEQ: Equivalente de agua de nieve (pulgadas)
TOBS: Temperatura del aire observada (°F)
PREC: Incremento de precipitación (pulgadas)
TMAX: Temperatura máxima del aire (°F)
TMIN: Temperatura mínima del aire (°F)

Referencia de la API

El servidor se conecta a la API REST de USDA AWDB:

URL base: https://wcc.sc.egov.usda.gov/awdbRestApi
Documentación: Swagger UI
Límites de tasa: Sé respetuoso con el uso de la API

Desarrollo

Estructura del Proyecto

snotel-mcp-server/
├── src/
│   └── snotel_mcp_server/
│       ├── __init__.py     # FastMCP server implementation
│       └── __main__.py     # Module entry point
├── pyproject.toml          # Project configuration
├── requirements.txt        # Dependencies
├── README.md               # This file
├── tests/                  # Test files
│   └── test_tools.py       # MCP tool tests
└── examples/               # Usage examples
    └── example_usage.py    # Example usage

Ejecutando Pruebas

# Install development dependencies
uv pip install -e ".[dev]"
# Or install from requirements.txt
pip install pytest pytest-asyncio pytest-cov

# Run tests
pytest

# Run with coverage (requires pytest-cov)
pytest --cov=src/snotel_mcp_server tests/

# Run specific test file
pytest tests/test_tools.py -v

Calidad del Código

# Format code
black snotel_mcp_server.py
isort snotel_mcp_server.py

# Lint code
ruff check snotel_mcp_server.py

# Type checking
mypy snotel_mcp_server.py

Configuración

Variables de Entorno

AWDB_API_BASE: Sobrescribe la URL base de la API predeterminada
AWDB_TIMEOUT: Tiempo de espera de solicitud en segundos (predeterminado: 30)

Registro (Logging)

El servidor admite niveles de registro configurables. Establece el nivel de registro mediante la variable de entorno:

# Show API requests and responses (recommended for debugging)
LOGLEVEL=INFO python -m snotel_mcp_server

# Show detailed debug information
LOGLEVEL=DEBUG python -m snotel_mcp_server

# Show only warnings and errors (default)
LOGLEVEL=WARNING python -m snotel_mcp_server

Niveles de registro:

DEBUG: Más detallado, muestra todas las operaciones internas
INFO: Muestra solicitudes, respuestas de API y operaciones generales
WARNING: Muestra solo advertencias y errores (predeterminado)
ERROR: Muestra solo errores

Solución de Problemas

Problemas Comunes

Errores de Conexión

Verifica la conectividad a Internet con los servidores de USDA
Verifica que el endpoint de la API sea accesible
Comprueba restricciones de proxy/cortafuegos

No se Devolvieron Datos

Verifica el formato del trío de la estación (ej., "713:CO:SNTL")
Comprueba que los rangos de fechas sean válidos
Algunas estaciones pueden tener lagunas de datos

Estación No Encontrada

Usa find_snotel_stations para verificar que la estación existe
Verifica que la abreviatura del estado sea correcta
Asegúrate de que la estación esté activa

Modo de Depuración

Habilita el registro detallado para ver todas las solicitudes de API:

LOGLEVEL=INFO python -m snotel_mcp_server

Para máxima verbosidad:

LOGLEVEL=DEBUG python -m snotel_mcp_server

Contribuciones

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Realiza un commit de tus cambios (git commit -m 'Add amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre una solicitud de extracción (Pull Request)

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Proyectos Relacionados

Model Context Protocol - La especificación y los SDK de MCP
Claude Desktop - Asistente de IA con soporte para MCP
USDA SNOTEL - Información oficial del programa SNOTEL

Agradecimientos

USDA Natural Resources Conservation Service por proporcionar la red y la API de SNOTEL
Anthropic por crear el Model Context Protocol
La comunidad de código abierto por las herramientas y bibliotecas subyacentes

¡Feliz seguimiento de nieve! 🎿❄️