Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information using the National Weather Service API. This server exposes tools for getting weather forecasts and alerts for US locations.

Features

• 🌤️ Weather Forecasts: Get detailed weather forecasts for any US location using latitude/longitude coordinates
• 🚨 Weather Alerts: Retrieve active weather alerts for any US state
• 🔌 MCP Integration: Works seamlessly with Claude for Desktop and other MCP-compatible clients
• 📡 Real-time Data: Fetches live data from the National Weather Service API

Tools Available

get-forecast

Get weather forecast for a specific location.

Parameters:

• latitude (float): Latitude of the location (-90 to 90)
• longitude (float): Longitude of the location (-180 to 180)

Example usage:

• "What's the weather forecast for San Francisco?" (Claude will use coordinates ~37.7749, -122.4194)
• "Give me the weather forecast for latitude 47.6062, longitude -122.3321" (Seattle)

get-alerts

Get active weather alerts for a US state.

Parameters:

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

Example usage:

• "What are the active weather alerts in California?"
• "Are there any weather warnings in Texas?"

Prerequisites

• Python 3.10 or higher
• uv package manager
• Access to the internet (for NWS API calls)

Installation

1. Install uv (if not already installed):

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. Clone or navigate to the project directory:

   cd weather
   

3. Install dependencies:

   uv sync
   

Running the Server

Standalone Testing

To test the server directly:

uv run weather.py

The server will start and listen on standard input/output. You can test it using the MCP inspector or other MCP clients.

With Claude for Desktop

1. Install Claude for Desktop from claude.ai/download

2. Configure Claude for Desktop by editing the configuration file:

   macOS/Linux:

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

   Windows:

   code $env:AppData\Claude\claude_desktop_config.json
   

3. Add the weather server configuration:

   macOS/Linux:

   {
     "mcpServers": {
       "weather": {
         "command": "uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/YOUR/weather",
           "run",
           "weather.py"
         ]
       }
     }
   }
   

   Windows:

   {
     "mcpServers": {
       "weather": {
         "command": "uv",
         "args": [
           "--directory",
           "C:\\ABSOLUTE\\PATH\\TO\\YOUR\\weather",
           "run",
           "weather.py"
         ]
       }
     }
   }
   

4. Restart Claude for Desktop completely

5. Verify the integration by looking for the "Search and tools" icon in Claude for Desktop

Usage Examples

Once configured with Claude for Desktop, you can ask questions like:

• "What's the weather forecast for Sacramento?"
• "Give me the weather forecast for New York City"
• "What are the active weather alerts in Florida?"
• "Are there any severe weather warnings in Texas?"
• "What's the weather like at coordinates 40.7128, -74.0060?" (NYC)

API Details

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

• Provides free access to US weather data
• Requires no API key
• Returns data in JSON format
• Only covers US locations

Project Structure

weather/
├── main.py          # Entry point (if needed)
├── weather.py       # Main MCP server implementation
├── pyproject.toml   # Project configuration and dependencies
├── uv.lock         # Dependency lock file
└── README.md       # This file

Troubleshooting

Server Not Showing Up in Claude

1. Check the configuration file syntax - Ensure valid JSON

2. Verify the absolute path - Use full paths, not relative ones

3. Check Claude's logs:

   # macOS/Linux
   tail -f ~/Library/Logs/Claude/mcp*.log
   
   # Windows
   # Check logs in %AppData%\Claude\logs\
   

4. Restart Claude for Desktop completely

Tool Calls Failing

1. Verify the server runs standalone:

   uv run weather.py
   

2. Check for rate limiting - The NWS API has rate limits
3. Ensure coordinates are for US locations - The NWS API only covers the US
4. Check internet connectivity - Server needs to reach api.weather.gov

Common Error Messages

• "Failed to retrieve grid point data": Usually means coordinates are outside the US
• "No active alerts for this state": Not an error - just means no current alerts
• "Unable to fetch forecast data": Network issue or invalid coordinates

Development

Adding New Tools

To add new weather-related tools:

1. Add the tool using the @mcp.tool() decorator
2. Implement the async function with proper type hints
3. Add error handling and validation
4. Test with uv run weather.py

Dependencies

Key dependencies (managed by uv):

• mcp: Model Context Protocol SDK
• httpx: HTTP client for API requests
• fastmcp: Simplified MCP server framework

License

This project is part of the Model Context Protocol ecosystem. Check individual dependencies for their licenses.

Contributing

Feel free to submit issues and pull requests to improve the weather server functionality.

Related Resources

• Model Context Protocol Documentation
• National Weather Service API
• Claude for Desktop
• MCP Python SDK