Skip to main content
Glama
deenesjakoruzh
kingshuknandy2016

weather

by kingshuknandy2016
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

mcp-weather-ts

Servidor TypeScript MCP que expone el tiempo de EE. UU. desde la National Weather Service API a hosts como Cursor.

El host inicia node build/index.js y se comunica mediante JSON-RPC a través de stdio. El modelo nunca llama a NWS por sí mismo; llama a las herramientas de este servidor (y puede leer un recurso o usar un prompt).

Cómo funciona MCP (herramientas, recursos, prompts, transporte): docs/create-mcp.readme.md.

Requisitos

  • Node.js 22+ (este repositorio usa ESM y fetch)

  • npm

  • Acceso por red a https://api.weather.gov (solo ubicaciones de EE. UU.)

Related MCP server: weather

Configuración

npm install
npm run build

tsc escribe JavaScript en build/. Cursor debe ejecutar el archivo compilado, no src/index.ts.

Scripts

Comando

Qué hace

npm run build

Compila src/ → build/

npm test

Prueba de humo de NWS: /points y luego las URLs de forecast + hourly

Montar en Cursor

  1. Compila (npm run build).

  2. Añade .cursor/mcp.json en este proyecto:

{
  "mcpServers": {
    "weather": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/build/index.js"]
    }
  }
}

Para todos los proyectos de Cursor, usa %USERPROFILE%\.cursor\mcp.json y una ruta completa a build\index.js en lugar de ${workspaceFolder}.

  1. Abre Customize → MCP (o Cursor Settings → MCP) y activa weather.

  2. Después de cambiar src/, vuelve a ejecutar npm run build y desactiva/activa el servidor para que Cursor reinicie el proceso.

No uses console.log después de que el servidor se conecte: stdout es el canal de MCP. Usa console.error para los logs.

Qué puedes invocar

Herramientas

El modelo (o tú, preguntándole en el chat de Agent) invoca estas herramientas con tools/call.

Nombre

Entradas

Qué hace

get_alerts

state — código de 2 letras de EE. UU. (CA, NY)

Alertas activas para ese estado

get_forecast

latitude, longitude

Pronóstico de 12 horas (NWS /points y luego properties.forecast)

test_tool

name

Práctica: Hello, {name}!

Ejemplo de chat:

  • «¿Hay alertas meteorológicas para CA?»

  • «Pronóstico para 39.7456, -97.0892»

Ejemplos de argumentos:

{ "state": "CA" }
{ "latitude": 39.7456, "longitude": -97.0892 }

Recurso

Nombre

URI

Qué hace

nws_guide

weather://nws-guide

Nota estática breve sobre las herramientas y el flujo de consulta de NWS

Pídele al agente que lea weather://nws-guide, o usa resources/read en un cliente.

Prompt

Nombre

Argumentos

Qué hace

check_weather

place — p. ej. Boston MA o CA

Plantilla de mensaje de usuario que indica al modelo que use get_forecast / get_alerts

En Cursor, elige el prompt Check weather y rellena place.

Estructura del proyecto

src/index.ts              Create McpServer, register, connect stdio
src/tools.ts              get_alerts, get_forecast, test_tool
src/resources.ts          weather://nws-guide
src/prompts.ts            check_weather
src/weather-api-call.ts   NWS fetch + types + alert formatting
src/createTransport.ts    StdioServerTransport + connect
tests/weather-api-call.test.ts
docs/create-mcp.readme.md How to design MCP servers

Orden de inicio en src/index.ts:

  1. new McpServer({ name: "weather", version: "1.0.0" })

  2. registerWeatherTools / registerWeatherResources / registerWeatherPrompts

  3. connectStdioTransport(server)

Notas sobre NWS

  • Los pronósticos no están en /points/{lat},{lon}/forecast. Carga /points/{lat},{lon} (cuatro decimales) y luego sigue properties.forecast o properties.forecastHourly.

  • NWS requiere una cabecera User-Agent (configurada en weather-api-call.ts).

  • La cobertura es de EE. UU. (y algunos territorios). Otras coordenadas suelen fallar.

Solución de problemas

Síntoma

Qué probar

Servidor en rojo / sin herramientas

Recompila, confirma que build/index.js existe, desactiva/activa MCP

El handshake falla

Asegúrate de hacer connect con stdio y de no escribir logs en stdout

Pronóstico vacío o fallido

Solo lat/lon de EE. UU.; consulta MCP Logs

npm test falla

Red / caída de NWS

Cursor: Output → MCP Logs.

Licencia

ISC

Available Tools

3 tools
get_alertsWeather AlertsB

Get weather alerts for a US state

ParametersJSON Schema
NameRequiredDescriptionDefault
stateYesTwo-letter state code (e.g. CA, NY)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description alone must carry behavioral disclosure. It only says 'get', which suggests a read-only operation, but it does not state whether any side effects occur, whether auth is required, rate limits, or what happens on error. For a simple getter, this is a notable gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded with the core action and object. While it is brief, it is efficient and avoids fluff, earning a high score for conciseness without sacrificing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema), the description provides a minimal but adequate foundation. It does not describe the return format or any special conditions, but for a straightforward alert retrieval, the current description may suffice. However, it could be improved by mentioning that it returns a list of alerts or any date relevance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers the single parameter fully: 'Two-letter state code (e.g. CA, NY)' with length constraints. The description adds no additional meaning beyond what the schema provides. With 100% schema description coverage, the baseline of 3 is appropriate; the description does not enhance understanding of the parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'get' and the resource 'weather alerts for a US state', which clearly distinguishes it from sibling tools (get_forecast for forecasts, test_tool for testing). It is specific about the domain (weather) and geographic scope (US state), so an agent can understand the primary function without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for any US state but does not explicitly contrast with get_forecast or mention any alternatives. There is no explicit when-not-to-use guidance or relationship to siblings. However, the context of 'US state' implies the parameter scope, so usage is reasonably clear but leaves room for ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_forecastWeather ForecastC

Get weather forecast for a location

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYesLatitude of the location
longitudeYesLongitude of the location

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states 'Get', implying a read-only operation, but does not mention what the forecast contains, whether authentication is required, potential rate limits, or the format of the response. The lack of any behavioral details beyond the obvious is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It is front-loaded with the core action. While it is appropriately concise, it is also so minimal that it misses opportunities to add value through structure, such as listing key output or usage notes. Overall, it is concise but not optimally informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, annotations, and any additional description, the tool is incomplete for an agent to call it correctly. There is no indication of what the forecast data looks like, how to interpret the response, or any caveats about precision or coverage. For a simple tool with two parameters, the description should at least mention typical return fields (e.g., temperature, conditions) to provide sufficient context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the schema documenting latitude and longitude ranges and simple descriptions. The tool description adds nothing beyond the schema, but since the schema already defines both parameters adequately, a baseline score of 3 is appropriate. No additional semantic meaning is supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'weather forecast', which is specific and unambiguous. However, it does not differentiate from the sibling tool get_alerts, which might also relate to weather, leaving some ambiguity about the precise distinction between forecast and alert retrieval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus get_alerts or test_tool. The description provides no context about conditions that would make this tool preferable, nor any exclusion criteria or alternative suggestions. The agent must infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

test_toolTest ToolD

Test tool

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the person to greet

TDQS

D1.6/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It says nothing about side effects, return values, or operational details, offering no insight beyond the tool's existence. This is a complete failure to convey behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is short (one word), this is under-specification rather than conciseness. It lacks any substantive content, so while it is minimal, it does not earn credit for efficient wording because it provides no value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter, the description is grossly incomplete. It omits the purpose, expected behavior, output, and any conditions or prerequisites. Even with a well-documented schema, the tool cannot be used correctly without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the 'name' parameter is described as 'The name of the person to greet'), so per the rubric the baseline is 3. The description adds no additional parameter semantics, but the schema already documents the parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tautological: description restates name/title.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the siblings (get_alerts, get_forecast). The description gives no context, no conditions, and no exclusions, leaving the agent with zero direction on tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedget_alerts
    • First observedget_forecast
    • First observedtest_tool
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.4/5.0

Scored across 3 tools

Disambiguation4/5

get_alerts and get_forecast are clearly distinct in purpose, but test_tool is ambiguous and could be mistaken for a generic utility, though it doesn't overlap with the weather tools. An agent can easily differentiate the two weather tools, and test_tool is separate enough to avoid confusion.

Naming Consistency3/5

Two tools follow a consistent 'get_<noun>' pattern (get_alerts, get_forecast), but test_tool breaks this convention with a different verb and structure. The naming is still readable, but the inconsistency is noticeable given only three tools.

Tool Count3/5

Three tools is borderline for a weather server, which typically needs more operations like current conditions or location search. The presence of test_tool, which does not serve a core weather purpose, makes the count feel less purposeful and slightly thin.

Completeness2/5

The server covers alerts and forecasts but lacks fundamental weather operations like current conditions or historical data. The test_tool is irrelevant to the domain, leaving notable gaps that would require agents to work around missing functionality.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • weather

    qurioskill
    F
    license
    C
    quality
    C
    maintenance
    Exposes US weather data as MCP tools, resources, and prompts via the National Weather Service API, enabling clients like Claude Desktop to get alerts, forecasts, and weather briefings.
    2
    1
    -

  • Weather MCP Demo

    huanhuang1
    F
    license
    Not graded
    quality
    C
    maintenance
    This MCP server provides tools to get current weather, forecasts, and weather alerts from the US National Weather Service via REST APIs, enabling AI agents to query live weather data.
    1
    -

  • Weather MCP Server

    Krishna-Dhawangale
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables natural-language weather queries for U.S. states and coordinates, returning real-time alerts and forecasts from the National Weather Service API via MCP tools.
    -