jcottam/mcp-server-weather

MCP Weather Server

A Model Context Protocol (MCP) server that provides weather-related functionality for any MCP client. This server integrates with the National Weather Service (NWS) API to deliver real-time weather alerts and forecasts for US locations.

Features

🌤️ Weather Alerts

• Get active weather alerts for any US state using two-letter state codes
• Displays event type, affected area, severity, status, and headlines
• Real-time data from the National Weather Service

📍 Weather Forecasts

• Get detailed weather forecasts for any US location using coordinates
• Includes temperature, wind conditions, and short forecast descriptions
• Supports multiple forecast periods (daily/hourly)

Prerequisites

• Node.js (version 14 or higher)
• pnpm (Package Manager) - automatically managed via Corepack
• Any MCP client (Claude Desktop, Ollama, etc.)

Installation

1. Install dependencies:

pnpm install

2. Build the project:

pnpm run build

Configuration

To integrate this server with an MCP client, you need to configure your client's MCP server settings. Here are examples for popular clients:

Claude Desktop

1. Open your Claude Desktop configuration file:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Add the following configuration to your MCP servers section:

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

Other MCP Clients

For other MCP clients, add a server configuration with:

• Command: node
• Args: ["/ABSOLUTE_PATH/mcp-server-weather/build/index.js"]

Replace /ABSOLUTE_PATH with the actual absolute path to your project directory.

Usage

Once configured, you can use the weather server through any MCP client with these commands:

Get Weather Alerts

Get weather alerts for California

• Returns active weather alerts for the specified state
• Uses two-letter state codes (CA, NY, TX, etc.)

Get Weather Forecast

Get the weather forecast for coordinates 40.7128, -74.0060

• Returns detailed forecast for the specified coordinates
• Only works for US locations (NWS API limitation)
• Includes temperature, wind, and forecast descriptions

Development

The project is written in TypeScript and uses the following key dependencies:

• @modelcontextprotocol/sdk: For MCP server implementation
• zod: For runtime type validation and schema definition
• typescript: For type safety and development

Project Structure

├── src/
│   └── index.ts      # Main server entry point with all weather tools
├── build/           # Compiled JavaScript output
├── package.json     # Project dependencies and scripts
└── pnpm-lock.yaml   # pnpm lock file for dependency management

Available Scripts

• pnpm install - Install dependencies
• pnpm run build - Compile TypeScript to JavaScript
• pnpm run clean - Remove build directory

API Integration

This server integrates with the National Weather Service (NWS) API:

• Base URL: https://api.weather.gov
• Data Format: GeoJSON
• Coverage: United States only
• Rate Limits: Standard NWS API limits apply

Supported Endpoints

• /alerts?area={STATE} - Get weather alerts by state
• /points/{lat},{lon} - Get grid point data for coordinates
• /gridpoints/{office}/{gridX},{gridY}/forecast - Get forecast data

Monitoring and Debugging

Logs

MCP clients typically write logs to their respective directories:

Claude Desktop:

• ~/Library/Logs/Claude/mcp*.log

Other clients:

• Refer to your specific client's documentation for log locations

To monitor logs in real-time (Claude Desktop example):

# View recent logs and follow new entries
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Error Handling

The server includes comprehensive error handling for:

• Network request failures
• Invalid coordinates or state codes
• NWS API service unavailability
• Data parsing errors

Limitations

• Geographic Coverage: Only supports US locations (NWS API limitation)
• Coordinate Precision: Uses 4 decimal places for coordinate precision
• Data Source: Relies on National Weather Service API availability

Resources

• MCP Server Quickstart Guide
• Model Context Protocol Documentation
• National Weather Service API

License

ISC License - See LICENSE file for details