Weather MCP Server

https://modelcontextprotocol.io/docs/develop/build-server#typescript

Professional TypeScript MCP server that exposes weather tools backed by the US National Weather Service API.

Features

• MCP server over stdio
• TypeScript strict mode
• No required API key
• Safe .env handling
• CLI client for manual testing
• Automated MCP smoke tests using a local mock NWS server
• Tools:
  • get-alerts
  • get-forecast

Important: api.weather.gov only supports locations in the United States and US territories. Forecasts for Italy or other non-US locations will not work with this data source.

Requirements

• Node.js 20 or newer
• npm

Check your versions:

node -v
npm -v

Installation

From the project folder:

npm install

Build

npm run build

This creates compiled JavaScript in build/.

Run the MCP server

npm start

The server communicates over stdio, so when started directly it waits for an MCP client.

Manual CLI testing

First build the project:

npm run build

Then run the included client:

npm run client

Example commands inside the client prompt:

get-alerts { "state": "CA" }
get-forecast { "latitude": 34.05, "longitude": -118.25 }
quit

Automated tests

npm test

The tests do not depend on the live National Weather Service API. They start a local mock weather server and verify that the MCP server lists and executes its tools correctly.

Configuration

No configuration is required for normal use.

Optional environment variables:

NWS_API_BASE=https://api.weather.gov
NWS_USER_AGENT=weather-mcp-server/2.0 your-email@example.com

Do not commit .env files. Use .env.example as a template only.

Claude Desktop configuration example

After running npm run build, add something like this to Claude Desktop's MCP configuration, adjusting the path to your local project folder:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "C:/Users/torre/Desktop/myWeather/build/server.js"
      ]
    }
  }
}

Project structure

src/
  cli.ts       Manual MCP client
  nws.ts       NWS API helpers and formatting
  server.ts    MCP server entry point
tests/
  mcp-smoke.test.js

Available npm scripts

npm run build   Compile TypeScript
npm start       Start the MCP server
npm run dev     Start the server with tsx
npm run client  Start the manual CLI client
npm test        Build and run automated tests
npm run clean   Remove build output

Security note

The original project contained a .env file. This version removes it from the distributable project and ignores all .env files by default. If the previous .env contained a real API key, revoke or rotate that key.