mcp-weather-server

MCP Weather Server

A Model Context Protocol (MCP) server that provides weather data through OpenWeatherMap API. This server enables MCP clients like Kiro and Claude to access current weather conditions and forecasts for any location.

Features

• Current Weather: Get real-time weather data including temperature, conditions, humidity, wind speed, and more
• Weather Forecasts: Retrieve weather forecasts for up to 8 days
• Flexible Location Input: Support for both city names and latitude/longitude coordinates
• Comprehensive Data: Includes UV index, sunrise/sunset times, atmospheric pressure, and visibility
• Error Handling: Robust error management with descriptive messages
• MCP Protocol: Full compliance with Model Context Protocol specification

Prerequisites

• Python 3.10 or higher
• OpenWeatherMap API key (free tier available at openweathermap.org)
• uv and uvx installed (see installation guide)

Installation

For Use with Kiro or Other MCP Clients

No manual installation required! The server will be automatically downloaded and run via uvx.

For Development

1. Clone the repository:

git clone <repository-url>
cd mcp-weather-server

1. Install dependencies:

uv pip install -e ".[dev]"

1. Copy the example environment file and add your API key:

cp .env.example .env
# Edit .env and add your OPENWEATHER_API_KEY

Configuration

Get an OpenWeatherMap API Key

1. Sign up at OpenWeatherMap
2. Navigate to your API keys section
3. Generate a new API key (free tier includes 1,000 calls/day)

Configure in Kiro

Add the following to your .kiro/settings/mcp.json file:

{
  "mcpServers": {
    "weather": {
      "command": "uvx",
      "args": ["mcp-weather-server"],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "autoApprove": ["get_current_weather", "get_weather_forecast"]
    }
  }
}

Replace your_api_key_here with your actual OpenWeatherMap API key.

Environment Variables

• OPENWEATHER_API_KEY (required): Your OpenWeatherMap API key
• LOG_LEVEL (optional): Logging level (DEBUG, INFO, WARNING, ERROR). Default: INFO
• API_TIMEOUT (optional): Timeout for API requests in seconds. Default: 10

Usage

Available Tools

get_current_weather

Get current weather conditions for a location.

Parameters:

• location (string, required): City name (e.g., "Paris") or coordinates (e.g., "48.8566,2.3522")
• units (string, optional): "metric" (default) or "imperial"

Example: `` Get the current weather in Tokyo ``

get_weather_forecast

Get weather forecast for upcoming days.

Parameters:

• location (string, required): City name or coordinates
• days (integer, optional): Number of days (1-8). Default: 7
• units (string, optional): "metric" (default) or "imperial"

Example: `` Show me the 5-day forecast for London ``

Using with Kiro

Once configured, simply ask Kiro natural language questions:

• "What's the weather like in Paris?"
• "Give me a 3-day forecast for New York"
• "What's the temperature in Tokyo right now?"
• "Show me the weather forecast for coordinates 51.5074,-0.1278"

Testing

For detailed testing instructions, see TESTING.md.

Quick Structure Validation

python3 test_structure.py

Integration Tests (requires valid API key)

OPENWEATHER_API_KEY=your_key python3 test_integration.py

Development

Running the Server Locally

python -m mcp_weather_server

Project Structure

mcp-weather-server/
├── src/
│   └── mcp_weather_server/
│       ├── __init__.py
│       ├── __main__.py          # Entry point
│       ├── server.py            # MCP server implementation
│       ├── weather_service.py   # OpenWeatherMap API client
│       ├── config.py            # Configuration management
│       ├── models.py            # Data models
│       ├── tools/               # MCP tool handlers
│       │   ├── current_weather.py
│       │   └── forecast.py
│       └── utils/               # Utilities
│           ├── errors.py
│           └── formatters.py
├── tests/                       # Test suite
├── pyproject.toml              # Project configuration
├── README.md                   # This file
└── .env.example                # Example environment configuration

API Rate Limits

The free tier of OpenWeatherMap includes:

• 1,000 API calls per day
• 60 calls per minute

The server handles rate limit errors gracefully and will inform you if limits are exceeded.

Troubleshooting

"API key is invalid"

• Verify your API key is correct in the configuration
• Ensure the API key is activated (can take a few hours after creation)

"Location not found"

• Check the spelling of the city name
• Try using coordinates instead: "latitude,longitude"

"Service temporarily unavailable"

• OpenWeatherMap API may be experiencing issues
• Check OpenWeatherMap status

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• Check the OpenWeatherMap API documentation
• Review the MCP specification
• Open an issue in this repository