Weather MCP Server

A Model Context Protocol (MCP) server that provides weather information using the WeatherAPI service. This server enables AI assistants to fetch current weather, forecasts, and search for locations through stdio communication.

Features

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

Prerequisites

Python 3.13+
uv package manager
WeatherAPI account and API key

Installation

Option 1: Via Smithery (Recommended)

Install automatically via Smithery MCP registry:

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

Or for other MCP clients:

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

This will automatically:

Install the weather MCP server
Add it to your MCP client configuration
Prompt you for your WeatherAPI key

Option 2: Manual Installation

Clone or download this repository
Get a WeatherAPI key:
- Sign up at https://www.weatherapi.com
- Get your free API key from the dashboard
- ⚠️ Keep your API key secure - never commit it to version control
Install dependencies:
```
uv sync
```

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 (like 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 includes 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 handles common errors gracefully:

Invalid API key: Returns 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

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

"No content response received"
- Check API key is set correctly
- Verify network connectivity
- Review debug logs for errors
"API key not provided"
- Set the WEATHER_API_KEY environment variable
- Check the MCP client configuration
"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

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
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

Weather MCP Server

Features

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

Prerequisites

Python 3.13+
uv package manager
WeatherAPI account and API key

Installation

Option 1: Via Smithery (Recommended)

Install automatically via Smithery MCP registry:

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

Or for other MCP clients:

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

This will automatically:

Install the weather MCP server
Add it to your MCP client configuration
Prompt you for your WeatherAPI key

Option 2: Manual Installation

Clone or download this repository
Get a WeatherAPI key:
- Sign up at https://www.weatherapi.com
- Get your free API key from the dashboard
- ⚠️ Keep your API key secure - never commit it to version control
Install dependencies:
```
uv sync
```

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 (like 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 includes 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 handles common errors gracefully:

Invalid API key: Returns 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

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

"No content response received"
- Check API key is set correctly
- Verify network connectivity
- Review debug logs for errors
"API key not provided"
- Set the WEATHER_API_KEY environment variable
- Check the MCP client configuration
"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

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
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