MCP Weather Server

A Model Context Protocol (MCP) server that provides real-time weather alerts and forecasts for locations across the United States. Built with FastMCP and powered by the National Weather Service (NWS) API.

Author

Matheus Remigio
Contact: matheus.remido@gmail.com

🌟 Features

• Weather Alerts: Get current weather alerts for any US state
• Weather Forecasts: Retrieve detailed 5-day weather forecasts for specific coordinates
• Real-time Data: Powered by the official National Weather Service API
• MCP Integration: Seamlessly integrates with MCP-compatible clients and AI assistants
• Async Support: Built with async/await for optimal performance
• Error Handling: Robust error handling with graceful fallbacks

🚀 Quick Start

Prerequisites

• Python 3.13 or higher
• uv package manager (recommended)
• MCP-compatible client (like Cursor IDE)

Installation

1. Clone the repository

   git clone https://github.com/msremigio/mcp-server-weather.git
   cd mcp_weather
   

2. Install dependencies using uv

   uv sync
   

3. Activate the virtual environment

   uv shell
   

Running the Server

uv run weather.py

The server will start and listen for MCP protocol messages via stdio transport.

🔧 Configuration

MCP Client Configuration

Add the following to your MCP client configuration (e.g., mcp.json):

{
  "mcpServers": {
    "mcp_weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/mcp_weather/project",
        "run",
        "weather.py"
      ]
    }
  }
}

Note: Update the --directory path to match your actual project location.

📚 API Reference

Available Tools

1. Get Weather Alerts (get_alerts)

Retrieves current weather alerts for a specific US state.

Parameters:

• state (str): Two-letter state abbreviation (e.g., "CA", "NY", "TX")

Returns:

• Formatted string containing all active alerts for the specified state

Example Response:

Event: Severe Thunderstorm Warning
Area: Northern California
Severity: Severe
Description: Severe thunderstorms capable of producing large hail and damaging winds
Instructions: Move to an interior room on the lowest floor of a building

---

Event: Flash Flood Watch
Area: Southern California
Severity: Moderate
Description: Heavy rainfall may cause flash flooding
Instructions: Monitor weather conditions and be prepared to take action

2. Get Weather Forecast (get_forecast)

Retrieves a 5-day weather forecast for specific coordinates.

Parameters:

• latitude (str): Latitude coordinate (decimal degrees)
• longitude (str): Longitude coordinate (decimal degrees)

Returns:

• Formatted string containing the next 5 forecast periods

Example Response:

Tonight:
- Temperature: 45°F
- Wind: 5 mph NW
- Forecast: Clear skies with light winds

---

Tomorrow:
- Temperature: 72°F
- Wind: 10 mph SW
- Forecast: Sunny and warm with increasing clouds in the afternoon

🏗️ Project Structure

mcp_weather/
├── weather.py          # Main MCP server implementation
├── main.py             # Simple entry point (placeholder)
├── pyproject.toml      # Project configuration and dependencies
├── mcp.json           # MCP client configuration template
├── README.md          # This file
├── uv.lock            # Dependency lock file
├── .python-version    # Python version specification
└── .venv/             # Virtual environment directory

🔌 Dependencies

• httpx: Modern async HTTP client for API requests
• mcp: Model Context Protocol implementation
• FastMCP: FastMCP framework for building MCP servers

🌐 Data Source

This project uses the National Weather Service (NWS) API, which provides:

• Real-time weather alerts and warnings
• Detailed weather forecasts
• Geographic point data
• Free and reliable weather information

🛠️ Development

Adding New Tools

To add new weather-related tools:

1. Create a new async function in weather.py
2. Decorate it with @mcp.tool()
3. Add proper type hints and docstrings
4. Implement the tool logic using the existing helper functions

Testing

# Run the server in development mode
uv run weather.py

# Test with MCP client tools
# The server will respond to MCP protocol messages

📝 Error Handling

The server includes comprehensive error handling:

• HTTP request failures
• API response validation
• Network timeouts (30-second limit)
• Graceful fallbacks for missing data

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License.

🙏 Acknowledgments

• National Weather Service for providing the weather data API
• MCP Project for the protocol specification
• FastMCP for the server framework

📞 Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check the MCP documentation
• Review the National Weather Service API documentation

---

Note: This server requires an active internet connection to fetch weather data from the NWS API.