Skip to main content
Glama
Thx93

mcp-weather-server

by Thx93
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

A Simple MCP Weather Server written in TypeScript

CI M8ven Score

A minimal Model Context Protocol server that exposes US weather data from the National Weather Service API as two read-only tools.

The NWS API is free, keyless and US-only, so this server needs no credentials and no account to run.

Tool

Input

Returns

get-alerts

state — two-letter code, e.g. CA

Active weather alerts for that state

get-forecast

latitude, longitude

The next five forecast periods for that point

Both tools are annotated readOnlyHint: true and destructiveHint: false, so a host that respects tool annotations can invoke them without asking first. Both reach out to api.weather.gov and are marked openWorldHint: true for that reason.

Use it hosted, paid per call

Running it yourself costs nothing. There is also a hosted version, paid per call in USDC on Base over x402, for agents that would rather not carry a Node process and a data layer:

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

It serves the same two tools, with the same output schemas and the same null fallbacks, plus a free health tool and free tools/list so the service can be discovered and probed before paying. Discovery is free; a tools/call for get-alerts or get-forecast returns 402 with the price. Both are declared read-only, so a host that respects annotations will not ask twice.

The server.json in this repository advertises that remote, so an MCP client can install it by registry name rather than by cloning anything.

Related MCP server: Weather MCP Server

Prerequisites

  • Node.js 24+

  • npm

Build, test and run

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

The suite drives the real server over InMemoryTransport with the NWS API stubbed, so npm test touches no network and needs no credentials. It covers tool discovery and annotations, the get-alerts and get-forecast data paths, the fallbacks for fields the NWS sends as null, the failure contract, and input validation.

Running node build/index.js speaks the MCP protocol over stdio: it prints to stderr and waits for a client on stdin, so it is meant to be launched by a host rather than by hand.

Adding it to a client

Most MCP hosts use the same three-line shape:

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

Or with npx, once the package is published:

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

Behaviour worth knowing

Failures are tool results, not protocol errors. A request the NWS cannot answer — a non-US location, an outage, a timeout — comes back as { isError: true, content: [{ type: "text", text: "<what failed>" }] }. That is the MCP contract for "this call was well formed and the work failed", as distinct from a JSON-RPC error, which means the call itself was broken. A client can show the text to a user and retry.

The NWS is slow to give up and we are not. Every request carries a 10-second timeout, so a stalled upstream surfaces as a failed tool call instead of a hung one.

Missing fields fall back rather than printing null. The NWS returns null for fields it does not have. A missing event name renders as Unknown, a missing temperature as Unknown — never the literal string null.

get-forecast returns at most five periods. Enough to answer "what is the weather like", short enough for a context window.

Structured content

Both tools declare an outputSchema and return structuredContent. get-forecast returns an object; get-alerts returns a top-level JSON array, which protocol revision 2026-07-28 is the first to allow — see Structured Content. serveStdio serves both protocol eras from one factory, and the SDK projects the array-rooted schema down to the {"result": [...]} form for a 2025-11-25 client, so adopting it costs older clients nothing. The tests assert the data either way.

Provenance

Started from the Build an MCP server tutorial and then went past it: typed output schemas, read-only tool annotations, a bounded fetch with an explicit failure contract, and a test suite. Licensed ISC.

Available Tools

2 tools
get-alertsGet Weather AlertsA
Read-onlyIdempotent
Inspect

Get weather alerts for a state

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

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

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

The annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds the state-scoping behavior, but it does not disclose additional behavioral details such as whether alerts are current, source, or result limits. This is adequate but not rich.

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

Conciseness5/5

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the agent's understanding of what the tool does, and it is appropriately sized for a simple one-parameter getter.

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

Completeness4/5

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

With a single required parameter, a fully documented schema, rich safety annotations, and an output schema present, the description is nearly complete. The only gap is that it does not explicitly route the agent between alerts and forecast, but the resource names make the distinction easy to infer.

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 coverage is 100% and the state parameter already has a clear description with min/max length and an example. The description adds no meaning beyond saying 'for a state,' so it meets the baseline for full schema coverage.

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

Purpose5/5

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

The description uses a specific verb and resource: 'Get weather alerts for a state.' It clearly identifies both the resource (weather alerts) and the scope (a state), and the tool name and resource type immediately distinguish it from the sibling get-forecast.

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

Usage Guidelines4/5

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

The description makes the intended context clear: use when weather alerts for a specific state are needed. It does not explicitly name get-forecast as the alternative or state when not to use this tool, so it stops short of a 5.

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

get-forecastGet Weather ForecastB
Read-onlyIdempotent
Inspect

Get weather forecast for a location

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYesLatitude of the location
longitudeYesLongitude of the location

Output Schema

ParametersJSON Schema
NameRequiredDescription
periodsYesThe forecast periods, soonest first
latitudeYesLatitude the forecast is for
longitudeYesLongitude the forecast is for

TDQS

B3.4/5.0
Behavior3/5

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

The annotations already indicate this is a safe read-only, idempotent operation, so the description does not need to restate that. It adds no behavioral context beyond 'for a location', but it does not contradict the annotations either.

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

Conciseness5/5

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

The description is a single short sentence with no filler. The core action and object are front-loaded, making it easy to scan.

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

Completeness4/5

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

Given the simple two-parameter schema, rich annotations, and an output schema, the description is mostly sufficient. A minor gap is that it does not clarify what kind of forecast data is returned, but the output schema likely covers that.

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 coverage is 100%, and the description does not add parameter-level detail. The phrase 'for a location' loosely maps to latitude/longitude, but the schema already documents those parameters adequately.

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 a clear verb and resource: it fetches a weather forecast for a location. It does not explicitly differentiate from the sibling get-alerts, though the resource names imply different purposes.

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?

No guidance is given about when to use this tool over get-alerts, nor any conditions, prerequisites, or exclusions. The intended context must be inferred entirely from the tool name and resource.

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. 2 tool updatesv1.0.0
    • First observedget-alerts
    • First observedget-forecast
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

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: one provides alerts for a state, the other provides forecasts for a location. No overlap or ambiguity.

Naming Consistency5/5

Both tools follow a consistent 'get-' verb prefix with a clear noun (alerts, forecast), maintaining a predictable pattern.

Tool Count3/5

With only 2 tools, the server feels thin. It's borderline—sufficient for a minimal weather use case but lacking the breadth typically expected.

Completeness2/5

The server lacks common weather operations such as current conditions, radar, or location search, creating significant gaps for typical weather-related queries.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Weather MCP Server

    BhavinPatel04
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides access to National Weather Service (NWS) data, enabling users to retrieve active weather alerts for US states and weather forecasts for specific geographic coordinates.
    102 npm
    MIT

  • Weather MCP Server

    OleBo
    A
    license
    B
    quality
    D
    maintenance
    Provides weather information and alerts from the National Weather Service, including active weather alerts for US states and location-based forecasts using latitude/longitude coordinates.
    2
    MIT

  • MCP Weather Server

    xue20010808
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides weather information using the US National Weather Service API, including active weather alerts for US states and location-specific forecasts based on latitude and longitude coordinates.
    102 npm
    MIT