NWS Weather

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

Un servidor MCP meteorológico simple escrito en TypeScript

Un servidor mínimo de Model Context Protocol que expone datos meteorológicos de EE. UU. de la API del Servicio Meteorológico Nacional como dos herramientas de solo lectura.

La API del NWS es gratuita, sin clave y solo para EE. UU., por lo que este servidor no necesita credenciales ni cuenta para ejecutarse.

Herramienta	Entrada	Devuelve
get-alerts	state — código de dos letras, p. ej. CA	Alertas meteorológicas activas para ese estado
get-forecast	latitude, longitude	Los próximos cinco períodos de pronóstico para ese punto

Ambas herramientas están anotadas como readOnlyHint: true y destructiveHint: false, por lo que un host que respete las anotaciones de herramientas puede invocarlas sin preguntar primero. Ambas se comunican con api.weather.gov y están marcadas como openWorldHint: true por esa razón.

Úsalo alojado, pago por llamada

Ejecutarlo tú mismo no cuesta nada. También hay una versión alojada, pago por llamada en USDC en Base a través de x402, para agentes que prefieran no llevar un proceso de Node y una capa de datos:

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

Sirve las mismas dos herramientas, con los mismos esquemas de salida y los mismos respaldos de null, además de una herramienta gratuita health y un tools/list gratuito para que el servicio pueda ser descubierto y probado antes de pagar. El descubrimiento es gratuito; una tools/call para get-alerts o get-forecast devuelve 402 con el precio. Ambas están declaradas como solo lectura, por lo que un host que respete las anotaciones no preguntará dos veces.

El server.json en este repositorio anuncia ese remoto, por lo que un cliente MCP puede instalarlo por nombre de registro en lugar de clonar nada.

Requisitos previos

• Node.js 24+
• npm

Compilar, probar y ejecutar

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

El conjunto de pruebas ejecuta el servidor real a través de InMemoryTransport con la API del NWS simulada, por lo que npm test no toca ninguna red y no necesita credenciales. Cubre el descubrimiento de herramientas y anotaciones, las rutas de datos de get-alerts y get-forecast, los respaldos para los campos que el NWS envía como null, el contrato de fallo y la validación de entrada.

Ejecutar node build/index.js habla el protocolo MCP a través de stdio: imprime en stderr y espera a un cliente en stdin, por lo que está pensado para ser lanzado por un host en lugar de a mano.

Añadirlo a un cliente

La mayoría de los hosts MCP usan la misma forma de tres líneas:

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

O, una vez que el paquete esté publicado en npm:

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

O directamente desde el repositorio, sin necesidad de cuenta de registro:

npm install github:Thx93/mcp-weather-server

Esa ruta funciona porque prepare compila el servidor durante la instalación; build/ no está confirmado, por lo que sin él el bin apuntaría a un archivo que no existe. Fue verificado de extremo a extremo — instalar desde GitHub, luego hablar MCP con el resultado, y ambas herramientas se listan con esquemas de salida de objeto.

Verificado contra la fuente

Las herramientas devuelven los propios datos del Servicio Meteorológico Nacional, por lo que la corrección es comprobable en lugar de afirmada. El 2026-10-19, api.weather.gov informó una alerta activa para TX y una llamada de pago al get-alerts alojado devolvió exactamente una — Event: Flood Advisory — para el mismo estado.

Eso importa más de lo que parece: el servicio de evidencia hermano lleva una brecha de confiabilidad documentada en su veredicto (ver su docs/evidence-quality.md), mientras que estas herramientas no tienen juicio inferido que pueda fallar. Obtienen y reforman; los valores son los del NWS.

Comportamiento que vale la pena conocer

Los fallos son resultados de herramientas, no errores de protocolo. Una solicitud que el NWS no puede responder — una ubicación fuera de EE. UU., una interrupción, un tiempo de espera — regresa como { isError: true, content: [{ type: "text", text: "<what failed>" }] }. Ese es el contrato MCP para "esta llamada estaba bien formada y el trabajo falló", a diferencia de un error JSON-RPC, que significa que la llamada en sí estaba rota. Un cliente puede mostrar el texto a un usuario y reintentar.

El NWS tarda en rendirse y nosotros no. Cada solicitud lleva un tiempo de espera de 10 segundos, por lo que un upstream estancado aparece como una llamada de herramienta fallida en lugar de una colgada.

Los campos faltantes tienen respaldo en lugar de imprimir null. El NWS devuelve null para los campos que no tiene. Un nombre de evento faltante se muestra como Unknown, una temperatura faltante como Unknown — nunca la cadena literal null.

get-forecast devuelve como máximo cinco períodos. Suficiente para responder "cómo está el clima", lo suficientemente corto para una ventana de contexto.

Contenido estructurado

Ambas herramientas declaran un outputSchema y devuelven structuredContent, y ambos esquemas son objetos: get-forecast devuelve { latitude, longitude, periods }, get-alerts devuelve { alerts: [...] }.

get-alerts anteriormente declaraba un arreglo de nivel superior, que la revisión de protocolo 2026-07-28 sí permite. Se cambió porque un cliente en el SDK MCP ampliamente implementado rechaza toda la respuesta de tools/list cuando encuentra un esquema de arreglo — invalid_value: expected "object" — por lo que tal cliente no puede conectarse al servidor en absoluto. Envolver el arreglo en un objeto es lo que hace que estas herramientas sean accesibles desde clientes ordinarios; el resumen textual que lee un modelo no cambia.

Procedencia

Comenzado desde el tutorial Build an MCP server y luego fue más allá: esquemas de salida tipados, anotaciones de herramientas de solo lectura, una obtención limitada con un contrato de fallo explícito y un conjunto de pruebas. Licencia ISC.