SNOTEL MCP Server

Fornece acesso aos dados meteorológicos e de neve do USDA SNOTEL.

Documentação

SNOTEL MCP Server

Um servidor Model Context Protocol (MCP) construído com FastMCP para acessar dados meteorológicos e de neve do USDA SNOTEL (SNOwpack TELemetry) através da API REST AWDB (Air and Water Database).

Este servidor fornece a assistentes de IA como o Claude acesso a condições de neve em tempo real e históricas, dados meteorológicos e análise de manto de neve de mais de 800 estações SNOTEL em todo o oeste dos Estados Unidos.

Recursos

🏔️ Descoberta de Estações

Encontrar por Estado: Obtenha todas as estações SNOTEL em qualquer estado
Encontrar por Localização: Pesquise estações dentro de um raio de coordenadas
Detalhes da Estação: Acesse metadados abrangentes da estação

📊 Acesso a Dados

Dados Históricos: Recupere profundidade de neve, SWE, temperatura e precipitação
Condições Recentes: Obtenha as últimas leituras e tendências recentes
Intervalos de Datas Personalizados: Consulte qualquer período de tempo com resolução diária

📈 Ferramentas de Análise

Tendências do Manto de Neve: Analise condições de pico e padrões sazonais
Rastreamento de Tempestades: Identifique eventos de nevasca e acúmulos
Resumos Estatísticos: Calcule médias, máximos e contagens de dias de neve

Início Rápido

Pré-requisitos

Python 3.9+
Gerenciador de pacotes uv (recomendado) ou pip

Instalação

# 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]"

Executando o Servidor

FastMCP lida com toda a configuração de transporte automaticamente:

# Run with default stdio transport
python -m snotel_mcp_server

# Or if installed
snotel-mcp-server

Uso com Claude Desktop

Adicione à sua configuração do 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"
    }
  }
}

Ou se instalado via pip:

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

Ferramentas Disponíveis

`find_snotel_stations`

Encontre estações SNOTEL por estado ou localização geográfica.

Parâmetros:

state (opcional): Abreviação do estado (ex.: "CO", "MT")
latitude (opcional): Latitude para busca por localização
longitude (opcional): Longitude para busca por localização
radius_miles (opcional): Raio de busca em milhas (padrão: 50)
network (opcional): Tipo de rede (padrão: "SNTL")

Exemplos:

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

`get_station_info`

Obtenha informações detalhadas sobre uma estação SNOTEL específica.

Parâmetros:

station_triplet (obrigatório): Identificador da estação (ex.: "713:CO:SNTL")

Exemplo:

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

`get_station_data`

Recupere dados brutos de neve e meteorológicos de uma estação em formato JSON.

Parâmetros:

station_triplet (obrigatório): Identificador da estação
start_date (obrigatório): Data de início (AAAA-MM-DD)
end_date (obrigatório): Data de término (AAAA-MM-DD)
elements (opcional): Tipos de dados ["SNWD", "WTEQ", "TOBS", "PREC"]
duration_name (opcional): Duração das medições ["DAILY", "HOURLY", "MONTHLY"]

Retorna: Dados JSON brutos da API SNOTEL

Exemplos:

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`

Obtenha condições recentes de uma estação (últimos 30 dias por padrão).

Parâmetros:

station_triplet (obrigatório): Identificador da estação
days (opcional): Número de dias recentes (padrão: 30)

Exemplo:

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

`analyze_snowpack_trends`

Analise tendências do manto de neve e calcule estatísticas para um período de tempo.

Parâmetros:

station_triplet (obrigatório): Identificador da estação
start_date (obrigatório): Data de início da análise
end_date (obrigatório): Data de término da análise

Exemplos:

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

Exemplos de Conversas

Encontrando Estações

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

Obtendo Condições Atuais

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

Analisando Tendências

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 Dados

O servidor suporta estas medições SNOTEL comuns:

SNWD: Profundidade de neve (polegadas)
WTEQ: Equivalente de água da neve (polegadas)
TOBS: Temperatura do ar observada (°F)
PREC: Incremento de precipitação (polegadas)
TMAX: Temperatura máxima do ar (°F)
TMIN: Temperatura mínima do ar (°F)

Referência da API

O servidor se conecta à API REST AWDB do USDA:

URL Base: https://wcc.sc.egov.usda.gov/awdbRestApi
Documentação: Swagger UI
Limites de Taxa: Seja respeitoso com o uso da API

Desenvolvimento

Estrutura do Projeto

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

Executando Testes

# 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

Qualidade do 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

Configuração

Variáveis de Ambiente

AWDB_API_BASE: Substitui a URL base padrão da API
AWDB_TIMEOUT: Tempo limite de requisição em segundos (padrão: 30)

Registro de Logs

O servidor suporta níveis de log configuráveis. Defina o nível de log via variável de ambiente:

# 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

Níveis de Log:

DEBUG: Mais verboso, mostra todas as operações internas
INFO: Mostra requisições de API, respostas e operações gerais
WARNING: Mostra apenas avisos e erros (padrão)
ERROR: Mostra apenas erros

Solução de Problemas

Problemas Comuns

Erros de Conexão

Verifique a conectividade com a internet para os servidores do USDA
Verifique se o endpoint da API está acessível
Verifique restrições de proxy/firewall

Nenhum Dado Retornado

Verifique o formato do trio da estação (ex.: "713:CO:SNTL")
Verifique se os intervalos de datas são válidos
Algumas estações podem ter lacunas de dados

Estação Não Encontrada

Use find_snotel_stations para verificar se a estação existe
Verifique se a abreviação do estado está correta
Garanta que a estação está ativa

Modo de Depuração

Ative o registro detalhado para ver todas as requisições de API:

LOGLEVEL=INFO python -m snotel_mcp_server

Para máxima verbosidade:

LOGLEVEL=DEBUG python -m snotel_mcp_server

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Projetos Relacionados

Model Context Protocol - A especificação MCP e SDKs
Claude Desktop - Assistente de IA com suporte a MCP
USDA SNOTEL - Informações oficiais do programa SNOTEL

Agradecimentos

USDA Natural Resources Conservation Service por fornecer a rede SNOTEL e a API
Anthropic por criar o Model Context Protocol
A comunidade de código aberto pelas ferramentas e bibliotecas subjacentes

Feliz Rastreamento de Neve! 🎿❄️