# 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:

```powershell
node -v
npm -v
```

## Installation

From the project folder:

```powershell
npm install
```

## Build

```powershell
npm run build
```

This creates compiled JavaScript in `build/`.

## Run the MCP server

```powershell
npm start
```

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

## Manual CLI testing

First build the project:

```powershell
npm run build
```

Then run the included client:

```powershell
npm run client
```

Example commands inside the client prompt:

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

## Automated tests

```powershell
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:

```text
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:

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

## Project structure

```text
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

```text
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.