weather

This MCP server implements an OpenWeatherMap integration, exposing tools to retrieve current weather, 5-day forecasts, location search, weather by ZIP, and air quality data. You can call tools such as get_current_weather, get_forecast, search_location, get_weather_by_zip, and get_air_quality to obtain structured weather information for locations around the world. The server supports unit selection (metric, imperial, standard) and can return detailed information when requested. Use the built-in status and cache endpoints to monitor health and performance, and take advantage of caching to minimize external API calls.

To interact with the server, run it via Python as shown in the installation guide, then invoke tools through a FastMCP-compatible client or the provided CLI. For example, get_current_weather accepts a location (city name or coordinates) and a units setting, while get_forecast returns a 5-day forecast in 3-hour steps. The search_location tool helps find coordinates for a city, and get_weather_by_zip enables ZIP-based lookups with an ISO country code. The get_air_quality tool provides AQI data for a location and communicates AQI levels using the defined scale. These tools can be combined to build travel itineraries, weather comparisons, and location-aware alerts.

If you integrate with FastMCP, you can script calls to these tools and parse the results programmatically, enabling automation and dashboarding for weather data in your applications.

Prerequisites:

• Python 3.8+ installed on your system
• Access to the OpenWeatherMap API key
• Python package manager (pip) installed

Installation steps:

1. Clone or navigate to the project directory: cd /home/jez/Documents/fastmcp/weather-mcp-server

2. Create and configure the virtual environment (optional but recommended): python -m venv venv source venv/bin/activate # Linux/macOS venv\Scripts\activate # Windows

3. Install dependencies from requirements.txt: pip install -r requirements.txt

4. Ensure you have a .env file with your API key and defaults, or update environment variables as shown in the configuration example below. The example uses placeholder values which you should replace with real credentials:

5. Run the server (development mode): python weather_server.py

6. Optional transports:

• HTTP transport: set TRANSPORT=http and PORT as needed, then run: TRANSPORT=http PORT=8000 python weather_server.py
• FastMCP CLI: fastmcp run weather_server.py
• Development inspector with FastMCP: fastmcp dev weather_server.py

7. Test mode (optional): python weather_server.py --test

Environment variables and configuration options:

• API_KEY: Your OpenWeatherMap API key.
• DEFAULT_UNITS: Default units for responses (metric, imperial, standard).
• DEFAULT_LANG: Default language code for responses (e.g., en).
• CACHE_TTL: Cache time-to-live in seconds to limit API calls (e.g., 600).
• LOG_LEVEL: Logging verbosity (DEBUG, INFO, WARNING, ERROR).
• MAX_DAILY_CALLS: Upper limit on API calls per day to control usage.

Common issues and tips:

• Ensure the API key is valid and has access to the OpenWeatherMap endpoints used by the server.
• If responses seem stale, verify the CACHE_TTL setting and networking to the API.
• When running behind a proxy or in a restricted environment, confirm outbound access for API requests.
• Use the status endpoints (weather://api/status or weather://cache/stats) to diagnose health and cache metrics.
• If you modify environment variables, restart the server for changes to take effect.