Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data using the free Open-Meteo API.

Features

• No API Key Required: Uses the free Open-Meteo API
• Current Weather: Get real-time weather conditions for any location
• Daily Forecast: Multi-day weather forecasts (up to 16 days)
• Hourly Forecast: Detailed hour-by-hour predictions (up to 7 days)
• Location Search: Find coordinates for any city worldwide
• Flexible Units: Support for metric and imperial units
• Multiple Formats: Both human-readable markdown and machine-readable JSON outputs

Tools

1. weather_search_location

Search for a city to get its coordinates.

Parameters:

• city (str): City name to search
• count (int, optional): Maximum number of results (default: 5)
• response_format (str, optional): Output format - 'markdown' or 'json' (default: 'markdown')

Example:

{
    "city": "London",
    "count": 3
}

2. weather_get_current

Get current weather conditions for a location.

Parameters:

• latitude (float): Latitude coordinate (-90 to 90)
• longitude (float): Longitude coordinate (-180 to 180)
• temperature_unit (str, optional): 'celsius' or 'fahrenheit' (default: 'celsius')
• wind_speed_unit (str, optional): 'kmh', 'ms', 'mph', or 'kn' (default: 'kmh')
• response_format (str, optional): Output format (default: 'markdown')

Example:

{
    "latitude": 51.5074,
    "longitude": -0.1278,
    "temperature_unit": "celsius"
}

3. weather_get_forecast

Get daily weather forecast for up to 16 days.

Parameters:

• latitude (float): Latitude coordinate
• longitude (float): Longitude coordinate
• days (int, optional): Number of forecast days 1-16 (default: 7)
• temperature_unit (str, optional): Temperature unit (default: 'celsius')
• wind_speed_unit (str, optional): Wind speed unit (default: 'kmh')
• response_format (str, optional): Output format (default: 'markdown')

Example:

{
    "latitude": 40.7128,
    "longitude": -74.0060,
    "days": 5,
    "temperature_unit": "fahrenheit"
}

4. weather_get_hourly

Get hourly weather forecast for up to 7 days (168 hours).

Parameters:

• latitude (float): Latitude coordinate
• longitude (float): Longitude coordinate
• hours (int, optional): Number of forecast hours 1-168 (default: 24)
• temperature_unit (str, optional): Temperature unit (default: 'celsius')
• wind_speed_unit (str, optional): Wind speed unit (default: 'kmh')
• response_format (str, optional): Output format (default: 'markdown')

Example:

{
    "latitude": 35.6762,
    "longitude": 139.6503,
    "hours": 48
}

Installation

Prerequisites

• Python 3.10 or higher
• pip

Install Dependencies

cd weather_mcp
pip install -r requirements.txt

Usage

Running the Server

The server uses stdio transport for local integration:

python server.py

Using with Claude Desktop or Other MCP Clients

Add the following to your MCP client configuration:

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/weather_mcp/server.py"]
    }
  }
}

For Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/weather_mcp/server.py"]
    }
  }
}

Testing with MCP Inspector

You can test the server using the MCP Inspector:

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
npx @modelcontextprotocol/inspector python server.py

Example Client

See client_example.py for a complete example of how to use the MCP server programmatically.

python client_example.py

Example Queries

Here are some example queries you can use with this MCP server:

1. Find a city and get its weather:

   First, search for "Paris" to get coordinates, then get current weather for those coordinates.
   

2. Get a weekly forecast:

   Get a 7-day weather forecast for London (51.5074, -0.1278) in Fahrenheit.
   

3. Check hourly conditions:

   Get the next 24 hours of weather data for Tokyo (35.6762, 139.6503).
   

API Response Formats

Markdown Format (Default)

Human-readable format with headers, bullet points, and clear structure. Ideal for display to users.

JSON Format

Machine-readable structured data. Perfect for programmatic processing or integration with other tools.

Data Source

This server uses the Open-Meteo API, which provides:

• Free access for non-commercial use
• No API key required
• High-quality weather data from multiple national weather services
• Global coverage

Architecture

• FastMCP Framework: Uses the official MCP Python SDK with FastMCP
• Pydantic Validation: All inputs are validated using Pydantic v2 models
• Async HTTP: Non-blocking API calls using httpx
• Type Safety: Full type hints throughout the codebase
• Error Handling: Comprehensive error messages with actionable suggestions

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT License - See LICENSE file for details.

Acknowledgments

• Weather data provided by Open-Meteo
• Built with Model Context Protocol