dinesh207/weather-mcp-server

Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data through the Open-Meteo API. This server allows AI agents and applications to fetch current weather information for any location using latitude and longitude coordinates.

Features

• 🌤️ Real-time Weather Data: Get current weather conditions for any location
• 📍 Coordinate-based Lookup: Use latitude and longitude for precise location targeting
• 🔄 Async Operations: Built with async/await for efficient API calls
• 🛡️ Error Handling: Robust error handling with graceful fallbacks
• 📊 Comprehensive Data: Includes temperature, precipitation, weather codes, and more

Prerequisites

• Python 3.13 or higher
• uv package manager (recommended) or pip

Installation

1. Clone or navigate to the project directory:

   cd weather_mcp_Server
   

2. Install dependencies using uv:

   uv sync
   

   Or using pip:

   pip install -r requirements.txt
   

Usage

Running the Server

Start the MCP server:

python server.py

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

Available Tools

get_current_weather

Fetches current weather data for a specified location.

Parameters:

• latitude (float): Latitude coordinate of the location
• longitude (float): Longitude coordinate of the location

Returns:

• dict[str, Any]: Weather data including:
  • Hourly data: temperature, precipitation, weather codes
  • Daily data: max/min temperatures, precipitation sums
  • Timezone information

Example Usage:

# Get weather for New York City (40.7128, -74.0060)
weather_data = await get_current_weather(40.7128, -74.0060)

API Integration

This server integrates with the Open-Meteo API, a free weather API that provides:

• No API Key Required: Free to use with reasonable rate limits
• Global Coverage: Weather data for locations worldwide
• Multiple Data Points: Temperature, precipitation, wind, pressure, and more
• High Accuracy: Based on multiple weather models

API Endpoints Used

• Forecast Endpoint: https://api.open-meteo.com/v1/forecast
• Parameters: latitude, longitude, hourly/daily variables, timezone

Project Structure

weather_mcp_Server/
├── server.py              # Main MCP server with tool definitions
├── weather_api_client.py # Open-Meteo API client utilities
├── pyproject.toml         # Project dependencies and metadata
├── uv.lock               # Lock file for dependency versions
└── README.md             # This file

Dependencies

• httpx: Async HTTP client for API requests
• mcp[cli]: Model Context Protocol server implementation
• Python 3.13+: Modern Python features and type hints

Development

Adding New Tools

To add new weather-related tools:

1. Create the tool function in server.py or tools.py
2. Decorate with @mcp.tool()
3. Define proper type hints for parameters and return values
4. Add comprehensive docstrings

Example:

@mcp.tool()
async def get_weather_forecast(latitude: float, longitude: float, days: int = 7) -> dict[str, Any]:
    """Get weather forecast for the next N days."""
    # Implementation here
    pass

Error Handling

The server includes robust error handling:

• API Timeouts: 30-second timeout for API requests
• Network Errors: Graceful handling of connection issues
• Invalid Data: Fallback responses for malformed data
• User-Agent: Proper identification for API requests

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

This project is open source. Please check the license file for details.

Support

For issues or questions:

• Check the Open-Meteo API documentation
• Review the MCP protocol documentation
• Open an issue in the project repository

Note: This server is designed to work with MCP-compatible clients and agents. Make sure your client supports the MCP protocol for proper integration.