Weather MCP Server

A Mastra Model Context Protocol (MCP) server that provides weather forecast data from the US National Weather Service API. This server exposes weather tools that can be used by any MCP-compatible client.

Features

ZIP Code Weather Lookup: Get detailed weather forecasts by US ZIP code
Coordinate Weather Lookup: Get weather forecasts by latitude/longitude coordinates
National Weather Service Data: Uses the official US government weather API
MCP Compatible: Works with any MCP client (Claude Desktop, Cursor, Windsurf, etc.)
Multiple Transport Options: Supports both stdio and HTTP SSE protocols

Installation

pnpm install @mastra/core@latest @mastra/mcp@latest zod

Project Structure

src/
├── mastra/
│   ├── mcp/
│   │   └── weather-server.ts    # MCP server configuration
│   ├── tools/
│   │   └── weather.ts           # Weather tools implementation
│   └── index.ts                 # Main Mastra configuration
├── mastra/src/mastra/scripts/
│   └── test-zip.ts              # Simple script to exercise the ZIP tool

Available Tools

`getWeatherByZip`

Get weather forecast for a US ZIP code.

Input:

zipCode (string): 5-digit US ZIP code (e.g., "10001", "90210")

Output: Detailed forecast with location info, multiple forecast periods including temperature, conditions, wind, humidity, and precipitation probability.

`getWeatherByCoordinates`

Get weather forecast for specific coordinates.

Input:

latitude (number): Latitude in decimal degrees (-90 to 90)
longitude (number): Longitude in decimal degrees (-180 to 180)

Output: Detailed forecast periods with weather conditions and timing.

Local testing

You can quickly exercise the weather tool via the included test script:

npm run test

This runs a simple script that calls the getWeatherByZip tool for ZIP code 96021 and prints the result.

Package.json Scripts

{
  "scripts": {
    "build": "tsc",
    "test": "tsx src/mastra/src/mastra/scripts/test-zip.ts",
    "test:watch": "tsx --watch src/mastra/src/mastra/scripts/test-zip.ts",
    "lint": "eslint src --ext .ts",
    "format": "prettier --write \"src/**/*.ts\"",
    "typecheck": "tsc --noEmit"
  }
}

Configuration

The server is configured in src/mastra/mcp/weather-server.ts:

Server ID: weather-mcp-server
Version: 0.0.1
Name: Weather MCP Server
API: US National Weather Service (api.weather.gov)

MCP Client Integration

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["path/to/your/dist/server-stdio.js"]
    }
  }
}

HTTP Clients

Connect to http://localhost:8080/mcp when running the HTTP server.

Example Usage

Once connected to an MCP client, you can use natural language to interact with the weather tools:

"What's the weather like in New York? Use ZIP code 10001"
"Get me the forecast for coordinates 40.7128, -74.0060"
"What's the weather forecast for ZIP code 90210?"

Data Source

This server uses the US National Weather Service API (api.weather.gov), which provides:

Official government weather data
Detailed forecast periods
High accuracy for US locations
Free public access
No API key required

Requirements

Node.js 16+
Internet connection for API requests
Valid US ZIP codes or coordinates within US boundaries

Error Handling

The server handles common errors gracefully:

Invalid ZIP codes
Network timeouts
API unavailability
Coordinates outside US coverage area

License

This project follows the Mastra framework licensing terms.

Weather MCP Server