Weather-MCP-Server by thejokers69 - MCP Server

Weather MCP Server

A Model Context Protocol (MCP) server that provides real-time weather data and alerts for Claude for Desktop and other MCP clients. This server integrates with the US National Weather Service API to deliver accurate weather forecasts and severe weather alerts.

Introduction

Many language models like Claude lack access to real-time data such as weather forecasts and severe weather alerts. This MCP server solves that problem by providing a bridge between Claude for Desktop and the US National Weather Service API.

The server exposes two powerful tools:

Weather Alerts: Get active severe weather alerts for any US state
Weather Forecasts: Get detailed weather forecasts for any US location using coordinates

Built with TypeScript and the official MCP SDK, this server follows the Model Context Protocol specification and integrates seamlessly with Claude for Desktop and other MCP-compatible clients.

Features

🌤️ Real-time Weather Data: Access current weather forecasts and alerts
🚨 Severe Weather Alerts: Get active weather alerts by state
📍 Location-based Forecasts: Get detailed forecasts using latitude/longitude coordinates
🔧 MCP Compliant: Built using the official Model Context Protocol SDK
🚀 Zero Configuration: No API keys required - uses free NWS API
📦 Easy Installation: Simple npm/pnpm installation process
🛡️ Error Handling: Robust error handling for network issues and invalid inputs
🎯 TypeScript: Full TypeScript support with type safety

Installation

Prerequisites

Node.js 18+
pnpm (recommended) or npm
TypeScript 5.0+

Installation Steps

Clone the repository:
```
git clone <repository-url>
cd weather
```
Install dependencies:
```
pnpm install
```
Build the project:
```
pnpm build
```
Test the server:
```
pnpm start
```

You should see: Weather MCP Server running on stdio

Quick start

After installation, the server is ready to use with Claude for Desktop:

Configure Claude for Desktop:

macOS: Open the configuration file:

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

Windows: Open the configuration file:

code "%APPDATA%\Claude\claude_desktop_config.json"

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather/build/index.js"],
      "env": {}
    }
  }
}

Note: Replace /path/to/weather/build/index.js with the actual absolute path to your weather server build file.

Restart Claude for Desktop
Test the tools:
- Ask Claude: "What are the weather alerts in California?"
- Ask Claude: "What's the weather forecast for coordinates 40.7128, -74.0060?"

For Client Developers

If you're building your own MCP client, check out the MCP Quickstart for Client Developers to learn how to integrate with this weather server and other MCP servers.

Usage

Available Tools

`get-alerts`

Get weather alerts for a specific US state.

Parameters:

state (string): Two-letter state code (e.g., "CA", "NY", "TX")

Example:

{
  "name": "get-alerts",
  "kwargs": {
    "state": "CA"
  }
}

`get-forecast`

Get weather forecast for a specific location using coordinates.

Parameters:

latitude (number): Latitude coordinate (-90 to 90)
longitude (number): Longitude coordinate (-180 to 180)

Example:

{
  "name": "get-forecast", 
  "kwargs": {
    "latitude": 40.7128,
    "longitude": -74.0060
  }
}

Sample Outputs

Weather Alerts:

Active alerts for CA:

Event: Severe Thunderstorm Warning
Area: Los Angeles County
Severity: Severe
Status: Actual
Headline: Severe Thunderstorm Warning issued for Los Angeles County
---

Weather Forecast:

Forecast for 40.7128, -74.0060:

Tonight:
Temperature: 45°F
Wind: 10 mph NW
Mostly clear with a low around 45°F
---

Tomorrow:
Temperature: 62°F  
Wind: 15 mph SW
Sunny with a high near 62°F
---

Configuration

Claude for Desktop Configuration

The server can be configured in Claude for Desktop's configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

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

Environment Variables

No environment variables are required. The server uses the free US National Weather Service API which doesn't require authentication.

API Reference

National Weather Service API

This server integrates with the US National Weather Service API:

Base URL: https://api.weather.gov
Authentication: None required
Rate Limits: None specified
Coverage: United States only

Server Endpoints

The server exposes two MCP tools that internally call the NWS API:

Alerts Endpoint: /alerts?area={state}
Points Endpoint: /points/{lat},{lon}
Forecast Endpoint: Dynamically retrieved from points response

Known issues and limitations

US Coverage Only: The National Weather Service API only covers the United States
Coordinate Precision: Coordinates are rounded to 4 decimal places for API compatibility
Network Dependency: Requires internet connection to access weather data
API Reliability: Depends on the NWS API availability and response times

Getting help

If you encounter issues:

Check the logs: The server outputs error messages to stderr
Verify coordinates: Ensure coordinates are within valid ranges
Test connectivity: Verify internet connection and NWS API availability
Check configuration: Ensure Claude for Desktop configuration is correct

For bugs or feature requests, please open an issue on the project repository.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Build and test: pnpm build && pnpm start
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Original Author and License

This example is based on the code explained in MCP Quickstart (github), whose license is CC-BY-4.0. The completed code examples are also hosted in this repo, whose license is MIT (Copyright (c) 2025 Model Context Protocol). So I've chosen the MIT license for this repo.

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

Model Context Protocol: For providing the excellent SDK and specification
US National Weather Service: For providing free, reliable weather data
Claude for Desktop: For implementing MCP client support
TypeScript Team: For the excellent type system and tooling
pnpm: For fast, efficient package management

Author: Mohamed Lakssir (thejokers69)
Version: 1.0.0
Last Updated: January 2025

thejokers69/Weather-MCP-Server

get-alerts

get-forecast