NWS Weather

npx add-mcp 'https://agent-evidence-api.thx93.workers.dev/weather/mcp'

Um Servidor MCP de Clima Simples escrito em TypeScript

Um servidor mínimo de Model Context Protocol que expõe dados meteorológicos dos EUA da National Weather Service API como duas ferramentas somente leitura.

A API do NWS é gratuita, sem chave e exclusiva dos EUA, então este servidor não precisa de credenciais nem de conta para funcionar.

Ferramenta	Entrada	Retorno
get-alerts	state — código de duas letras, ex.: CA	Alertas meteorológicos ativos para aquele estado
get-forecast	latitude, longitude	Os próximos cinco períodos de previsão para aquele ponto

Ambas as ferramentas são anotadas como readOnlyHint: true e destructiveHint: false, então um host que respeita anotações de ferramentas pode invocá-las sem perguntar antes. Ambas acessam api.weather.gov e são marcadas como openWorldHint: true por esse motivo.

Use hospedado, pago por chamada

Executá-lo você mesmo não custa nada. Há também uma versão hospedada, paga por chamada em USDC na Base via x402, para agentes que preferem não carregar um processo Node e uma camada de dados:

https://agent-evidence-api.thx93.workers.dev/weather/mcp

Ela serve as mesmas duas ferramentas, com os mesmos esquemas de saída e os mesmos fallbacks de null, além de uma ferramenta health gratuita e tools/list gratuitos para que o serviço possa ser descoberto e testado antes de pagar. A descoberta é gratuita; uma chamada tools/call para get-alerts ou get-forecast retorna 402 com o preço. Ambas são declaradas somente leitura, então um host que respeita anotações não perguntará duas vezes.

O server.json neste repositório anuncia esse remoto, então um cliente MCP pode instalá-lo pelo nome do registro em vez de clonar qualquer coisa.

Pré-requisitos

• Node.js 24+
• npm

Compilar, testar e executar

npm install
npm test          # builds, then runs the suite
npm run build     # compile only
node build/index.js

A suíte executa o servidor real via InMemoryTransport com a API do NWS simulada, então npm test não toca em rede e não precisa de credenciais. Ela cobre a descoberta de ferramentas e anotações, os caminhos de dados de get-alerts e get-forecast, os fallbacks para campos que o NWS envia como null, o contrato de falha e a validação de entrada.

Executar node build/index.js fala o protocolo MCP via stdio: ele imprime para stderr e aguarda um cliente em stdin, então é feito para ser iniciado por um host em vez de manualmente.

Adicionando a um cliente

A maioria dos hosts MCP usa o mesmo formato de três linhas:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-weather-server/build/index.js"]
    }
  }
}

Ou, uma vez que o pacote seja publicado no npm:

{
  "mcpServers": {
    "weather": { "command": "npx", "args": ["-y", "@thx93/mcp-weather-server"] }
  }
}

Ou direto do repositório, sem precisar de conta de registro:

npm install github:Thx93/mcp-weather-server

Esse caminho funciona porque prepare compila o servidor durante a instalação; build/ não é versionado, então sem ele o bin apontaria para um arquivo que não existe. Foi verificado de ponta a ponta — instalar do GitHub, depois falar MCP com o resultado, e ambas as ferramentas listam com esquemas de saída de objeto.

Verificado contra a fonte

As ferramentas retornam os próprios dados do National Weather Service, então a correção é verificável em vez de presumida. Em 2026-10-19, api.weather.gov relatou um alerta ativo para TX e uma chamada paga ao get-alerts hospedado retornou exatamente um — Event: Flood Advisory — para o mesmo estado.

Isso importa mais do que parece: o serviço de evidência irmão carrega uma lacuna de confiabilidade documentada em seu veredito (veja seu docs/evidence-quality.md), enquanto estas ferramentas não têm julgamento inferido para errar. Elas buscam e remodelam; os valores são do NWS.

Comportamento que vale a pena conhecer

Falhas são resultados de ferramentas, não erros de protocolo. Uma solicitação que o NWS não pode responder — uma localização fora dos EUA, uma indisponibilidade, um tempo limite — retorna como { isError: true, content: [{ type: "text", text: "<what failed>" }] }. Esse é o contrato MCP para "esta chamada foi bem formada e o trabalho falhou", distinto de um erro JSON-RPC, que significa que a própria chamada estava quebrada. Um cliente pode mostrar o texto a um usuário e tentar novamente.

O NWS demora para desistir e nós não. Cada solicitação carrega um tempo limite de 10 segundos, então um upstream travado aparece como uma chamada de ferramenta falha em vez de uma pendurada.

Campos ausentes têm fallback em vez de imprimir null. O NWS retorna null para campos que não possui. Um nome de evento ausente é renderizado como Unknown, uma temperatura ausente como Unknown — nunca a string literal null.

get-forecast retorna no máximo cinco períodos. Suficiente para responder "como está o clima", curto o bastante para uma janela de contexto.

Conteúdo estruturado

Ambas as ferramentas declaram um outputSchema e retornam structuredContent, e ambos os esquemas são objetos: get-forecast retorna { latitude, longitude, periods }, get-alerts retorna { alerts: [...] }.

get-alerts declarava anteriormente um array de nível superior, o que a revisão de protocolo 2026-07-28 permite. Foi alterado porque um cliente no MCP SDK amplamente implantado rejeita toda a resposta tools/list quando encontra um esquema de array — invalid_value: expected "object" — então tal cliente não consegue se conectar ao servidor de forma alguma. Envolver o array em um objeto é o que torna essas ferramentas acessíveis a partir de clientes comuns; o resumo textual que um modelo lê permanece inalterado.

Proveniência

Iniciado a partir do tutorial Build an MCP server e depois foi além: esquemas de saída tipados, anotações de ferramentas somente leitura, um fetch limitado com um contrato de falha explícito e uma suíte de testes. Licenciado sob ISC.