OpenWeatherMap MCP Server

A Model Context Protocol (MCP) server that provides weather data using the OpenWeatherMap API. This example demonstrates how to build an MCP server with multiple tools for current weather, forecasts, and air pollution data.

Features

• Current Weather: Get real-time weather conditions for any city
• 5-Day Forecast: Retrieve weather forecasts with 3-hour intervals
• Air Pollution: Access air quality data including pollutant concentrations

Prerequisites

• Python 3.12+
• OpenWeatherMap API key (free at openweathermap.org)

Installation

1. Clone this repository:

git clone git@github.com:mattiaperi/openweathermap-mcp-server.git
cd openweathermap-mcp-server

2. Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip3 install -r requirements.txt

4. Set your OpenWeatherMap API key:

export OPENWEATHER_API_KEY="your_api_key_here"

Usage

Running the Server

python server.py

Testing with the Client

python test_mcp_client.py Milan
# or
python test_mcp_client.py # Will prompt for city name

Using with Amazon Q

1. Create .amazonq/mcp.json in your project:

{
  "mcpServers": {
    "weather": {
      "command": ".venv/bin/python",
      "args": ["server.py"],
      "env": {}
    }
  }
}

2. Restart Amazon Q and ask: "What's the weather like in Tokyo?"

Available Tools

get_current_weather(city: str)

Returns current weather conditions including temperature, humidity, pressure, and weather description.

get_weather_forecast(city: str)

Returns a 5-day weather forecast with data points every 3 hours.

get_air_pollution(city: str)

Returns air quality data including AQI and pollutant concentrations (CO, NO, NO2, O3, SO2, PM2.5, PM10, NH3).

API Response Format

All tools return the complete OpenWeatherMap API response, allowing LLMs to extract relevant information based on context. Error responses include an error field with descriptive messages.

Development

Project Structure

├── server.py          # MCP server implementation
├── requirements.txt   # Python dependencies
└── README.md          # This file

Adding New Tools

1. Define a function with type hints
2. Add the @mcp.tool decorator
3. Include a descriptive docstring
4. Handle errors gracefully

Example:

@mcp.tool
def get_uv_index(city: str) -> dict:
    """Get UV index data for a city."""
    # Implementation here

Security Notes

• Never commit API keys to version control
• Use environment variables for sensitive data
• Consider rate limiting for production use
• Validate input parameters

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

MIT License - see LICENSE file for details

Resources

• MCP Documentation
• FastMCP Library
• OpenWeatherMap API