Weather MCP Server

🚀 Weather MCP Server

A Model Context Protocol (MCP) server that utilizes the WeatherAPI service to offer weather information. It allows AI assistants to obtain current weather, forecasts, and search for locations via stdio communication.

🚀 Quick Start

The Weather MCP Server is a powerful tool that enables seamless access to weather information. Before getting started, ensure you have the necessary prerequisites installed and configured.

✨ Features

• Current Weather: Retrieve real - time weather conditions for any location.
• Weather Forecast: Get weather forecasts up to 14 days in advance.
• Location Search: Find and validate location names.
• Air Quality Data: Optionally obtain air quality information.
• Debug Logging: Comprehensive logging for easy troubleshooting.
• Stdio Communication: Direct MCP protocol communication through stdin/stdout.

📦 Installation

Option 1: Via Smithery (Recommended)

Automatically install the server via the Smithery MCP registry:

npx -y @smithery/cli install weather-mcp-server --client claude

For other MCP clients:

npx -y @smithery/cli install weather-mcp-server

This process will:

• Install the weather MCP server.
• Add it to your MCP client configuration.
• Prompt you to enter your WeatherAPI key.

Option 2: Manual Installation

1. Clone or download this repository.
2. Get a WeatherAPI key:
   • Sign up at https://www.weatherapi.com.
   • Retrieve your free API key from the dashboard.
   • ⚠️ Important Note: Keep your API key secure and never commit it to version control.
3. Install dependencies:

   uv sync
   

📚 Documentation

Configuration

Environment Variables

Set your WeatherAPI key:

export WEATHER_API_KEY=your_api_key_here

Optional - Enable debug logging:

export DEBUG=true

MCP Client Configuration

Add this server to your MCP client configuration (e.g., config.json):

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

To enable debug logging, add the DEBUG environment variable:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here",
        "DEBUG": "true"
      }
    }
  }
}

Usage

Running the Server

Direct execution:

WEATHER_API_KEY=your_api_key uv run server.py

With debug logging:

DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py

With MCP client: The server automatically starts when your MCP client (such as mcphost or Claude Desktop) connects to it.

Available Tools

1. weather_current

Get current weather conditions for a location. Parameters:

• q (required): Location query (city name, coordinates, postal code).
• aqi (optional): Include air quality data ("yes" or "no", default: "no"). Example:

{
  "name": "weather_current",
  "arguments": {
    "q": "New York, NY",
    "aqi": "yes"
  }
}

2. weather_forecast

Get weather forecast for 1 - 14 days. Parameters:

• q (required): Location query.
• days (optional): Number of forecast days (1 - 14, default: 1). Example:

{
  "name": "weather_forecast",
  "arguments": {
    "q": "London, UK",
    "days": 7
  }
}

3. weather_search

Search for locations matching a query. Parameters:

• q (required): Search query. Example:

{
  "name": "weather_search",
  "arguments": {
    "q": "Paris"
  }
}

Location Query Formats

The weather tools accept various location formats:

• City name: "New York", "London".
• City and state/country: "New York, NY", "London, UK".
• Coordinates: "40.7128,-74.0060".
• Postal code: "10001", "SW1A 1AA".
• Airport code: "JFK", "LHR".

Testing

Manual Testing

Test the server with JSON - RPC requests:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | WEATHER_API_KEY=your_api_key uv run server.py

With debug logging:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py

Tool Testing

Test a weather tool:

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"weather_current","arguments":{"q":"New York"}}}' | WEATHER_API_KEY=your_api_key uv run server.py

Docker Support

Building the Image

docker build -t weather-mcp-server .

Running with Docker

docker run --rm -i -e WEATHER_API_KEY=your_api_key weather-mcp-server

Debug Mode

The server offers optional debug logging. Set the DEBUG environment variable to enable detailed logging. Log levels:

• INFO: Basic server operations (default).
• DEBUG: Detailed request/response information, API calls (when DEBUG=true).

Error Handling

The server gracefully handles common errors:

• Invalid API key: Returns an error message with guidance.
• Location not found: Suggests alternative search terms.
• Network issues: Provides retry suggestions.
• Rate limiting: Indicates when limits are exceeded.

Dependencies

• httpx: HTTP client for API requests.
• asyncio: Async/await support.
• Standard library: json, logging, sys, os.

API Limits

The WeatherAPI free tier includes:

• 1 million calls per month.
• Current weather and 3 - day forecast.
• Upgrade for extended forecasts and higher limits.

Troubleshooting

Common Issues

1. "No content response received"
   • Check if the API key is set correctly.
   • Verify network connectivity.
   • Review debug logs for errors.
2. "API key not provided"
   • Set the WEATHER_API_KEY environment variable.
   • Check the MCP client configuration.
3. "Location not found"
   • Try different location formats.
   • Use the weather_search tool to find valid locations.

Debug Output

Enable detailed logging by setting the DEBUG environment variable:

DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py 2>&1 | grep -E "(DEBUG|ERROR)"

Architecture

This server implements the MCP protocol using:

• stdio communication: Direct JSON - RPC over stdin/stdout.
• Asyncio event loop: Non - blocking request handling.
• Manual JSON - RPC: Custom implementation for precise control.
• WeatherAPI integration: RESTful API calls with error handling.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Test thoroughly.
5. Submit a pull request.

📄 License

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

Support

• WeatherAPI Documentation: https://www.weatherapi.com/docs/
• MCP Specification: https://spec.modelcontextprotocol.io/
• Issues: Report bugs and feature requests in the repository issues

Last updated: July 12, 2025