Weekly Weather MCP Server

1# 🌦️ Weekly Weather MCP Server
2 
3A weather forecast MCP (Model Context Protocol) server providing **8-day global weather forecasts** and current weather conditions using the [OpenWeatherMap](https://openweathermap.org) [One Call API 3.0](https://openweathermap.org/api/one-call-3).
4 
5> This project builds upon an earlier project by [Zippland](https://github.com/Zippland/weather-mcp), with modifications to support full week forecasts and additional time-of-day data points.
6 
7<div align="center">
8  <img src="https://rossshannon.github.io/weekly-weather-mcp/images/weather-mcp-thinking.gif" alt="Claude calling MCP server" width="800">
9  <p><em>Animation showing Claude Desktop processing the weather data from the MCP Server</em></p>
10</div>
11<br>
12<div align="center">
13  <img src="https://rossshannon.github.io/weekly-weather-mcp/images/weather-forecast-example.png" alt="Claude displaying weather forecast" width="700">
14  <p><em>Claude Desktop showing a detailed weather forecast with lawn mowing recommendations</em></p>
15</div>
16 
17## Features
18 
19- 🌍 Support for querying weather conditions anywhere in the world
20- 🌤️ Hourly forecasts for the next 48 hours
21- 📅 Provides detailed 8-day forecasts (today + following 7 days), with morning, afternoon, and evening data points
22- 🌧️ Weather summaries and precipitation probabilities
23- 🌡️ Detailed weather information including temperature, humidity, wind speed, etc.
24- 📍 Support for reporting results in different time zones
25- 🗂️ No separate configuration file needed; API key can be passed directly through environment variables or parameters
26 
27## Usage
28 
29### 1. Get an OpenWeatherMap API Key with One Call API 3.0 Access (free)
30 
311. Visit [OpenWeatherMap](https://openweathermap.org/) and register an account
322. Subscribe to the “One Call API 3.0” plan (offers 1,000 API calls per day for free)
333. Wait for API key activation (this can take up to an hour)
34 
35#### About the One Call API 3.0
36 
37The One Call API 3.0 provides comprehensive weather data:
38- Current weather conditions
39- Minute forecast for 1 hour
40- Hourly forecast for 48 hours
41- Daily forecast for 8 days (including today)
42- National weather alerts
43- Historical weather data
44 
45#### API Usage and Limits
46 
47- **Free tier**: 1,000 API calls per day
48- **Default limit**: 2,000 API calls per day (can be adjusted in your account)
49- **Billing**: Any calls beyond the free 1,000/day will be charged according to OpenWeatherMap pricing
50- **Usage cap**: You can set a call limit in your account to prevent exceeding your budget (including capping your usage at the free tier limit so no costs can be incurred)
51- If you reach your limit, you’ll receive a HTTP 429 error response
52 
53> **Note**: API key activation can take several minutes up to an hour. If you receive authentication errors shortly after subscribing or generating a new key, wait a bit and try again later.
54 
55### 2. Clone the Repository and Install Dependencies
56 
57```bash
58# Clone the repository
59git clone https://github.com/rossshannon/weekly-weather-mcp.git
60cd weekly-weather-mcp
61 
62# Create a virtual environment (recommended)
63python3 -m venv venv
64source venv/bin/activate  # Linux/Mac
65# OR
66venv\Scripts\activate  # Windows
67 
68# Install dependencies
69pip3 install -r requirements.txt
70```
71 
72This will install all the necessary dependencies to run the server and development tools.
73 
74### 3. Run the Server
75 
76There are two ways to provide the API key:
77 
78#### Method 1: Using Environment Variables
79 
80```bash
81# Set environment variables
82export OPENWEATHER_API_KEY="your_api_key"  # Linux/Mac
83set OPENWEATHER_API_KEY=your_api_key  # Windows
84 
85# Run the server
86python weather_mcp_server.py
87```
88 
89#### Method 2: Provide When Calling the Tool
90 
91Run directly without setting environment variables:
92 
93```bash
94python weather_mcp_server.py
95```
96 
97When calling the tool, you’ll need to provide the `api_key` parameter.
98 
99### 4. Use in MCP Client Configuration
100 
101Add the following configuration to your MCP-supported client (e.g., [Claude Desktop](https://www.anthropic.com/claude-desktop) ([instructions](https://modelcontextprotocol.io/quickstart/user)), [Cursor](https://www.cursor.com/)):
102 
103```json
104{
105  "weather_forecast": {
106    "command": "python3",
107    "args": [
108      "/full_path/weather_mcp_server.py"
109    ],
110    "env": {
111      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
112    },
113    "disabled": false,
114    "autoApprove": ["get_weather", "get_current_weather"]
115  }
116}
117```
118 
119If you’re using a virtual environment, your configuration should include the full path to the Python executable in the virtual environment:
120 
121```json
122{
123  "weather_forecast": {
124    "command": "/full_path/venv/bin/python3",
125    "args": [
126      "/full_path/weather_mcp_server.py"
127    ],
128    "env": {
129      "OPENWEATHER_API_KEY": "your_openweathermap_key_here"
130    },
131    "disabled": false,
132    "autoApprove": ["get_weather", "get_current_weather"]
133  }
134}
135```
136 
137### 5. Available Tools
138 
139The server exposes two tools, `get_weather` and `get_current_weather`. Both tools accept the same parameters:
140 
141- `location`: Location name as a string, e.g., “Beijing”, “New York”, “Tokyo”. The tool will handle geocoding this to a latitude/longitude coordinate.
142- `api_key`: OpenWeatherMap API key (optional, will read from environment variable if not provided)
143- `timezone_offset`: Timezone offset in hours, e.g., 8 for Beijing, -4 for New York. Default is 0 (UTC time). Times in the returned data will be accurate for this timezone.
144 
145#### get_weather
146 
147Get comprehensive weather data for a location including current weather (next 48 hours) and 8-day forecast with detailed information.
148 
149Returns:
150- Current weather information
151- Hourly forecasts for the next 48 hours
152- Daily forecasts for 8 days (today + 7 days ahead)
153- Morning (9 AM), afternoon (3 PM), and evening (8 PM) data points for each day
154- Weather summaries and precipitation probabilities
155- Detailed weather information including temperature, humidity, wind speed, etc.
156 
157Perfect for use cases like:
158- “🏃‍♂️ Which days this week should I go for a run?”
159- “🪴 When’s the best evening to work in my garden this week?”
160- “🪁 What’s the windiest day coming up soon for flying a kite?”
161- “💧 Will I need to water my garden this week or will rain take care of it?”
162 
163#### get_current_weather
164 
165Get current weather for a specified location.
166 
167Returns:
168- A simplified subset of the data returned by `get_weather`
169- Only the current weather information (temperature, feels like, weather condition, humidity, wind, etc.); no forecast data for future time periods
170- Useful for quick queries about present conditions only
171 
172##### Location Lookup Details
173 
174The `location` parameter uses OpenWeatherMap’s geocoding to convert location names to geographic coordinates:
175 
176- Simple location names work: “Paris”, “Tokyo”, “New York”
177- For better accuracy, include country codes: “Paris,FR”, “London,GB”, “Portland,US”
178- For US cities, you can include state: “Portland,OR,US” or “Portland,ME,US”
179- The API supports any location on Earth that OpenWeatherMap can geocode
180- Location names are converted to latitude/longitude coordinates internally
181 
182If a location can’t be found, the API will return an error. In case of ambiguous locations, try adding country or state codes for more precise results.
183 
184## Usage Examples
185 
186### Example 1: Current Weather
187 
188```
189User: What’s the weather like in New York right now?
190 
191AI: Let me check the current weather in New York for you.
192[Calling get_current_weather("New York", timezone_offset=-4)]
193 
194Current weather in New York: 5°C, few clouds, humidity 42%, wind speed 4.1m/s.
195```
196 
197### Example 2: Weekly Planning
198 
199```
200User: I need to mow my lawn this week in Boston. Which day would be best?
201 
202AI: Let me check the weather forecast for Boston to find the best day for lawn mowing.
203[Calling get_weather("Boston", timezone_offset=-4)]
204 
205Looking at the Boston forecast for the week:
206- Today (Monday): Light rain (28% chance), 5°C
207- Tuesday: Clear, sunny, 10°C
208- Wednesday: Light rain (100% chance), 9°C
209- Thursday: Moderate rain (100% chance), 10°C
210- Friday: Moderate rain (100% chance), 11°C
211- Saturday: Partly cloudy, 13°C
212- Sunday: Scattered clouds, 17°C
213 
214Tuesday would be your best option for mowing the lawn. It will be clear and sunny with no chance of rain, and the temperature will be comfortable at around 10°C.
215```
216 
217You can combine this MCP server with others to achieve multi-step workflows. For example, once the weather has been checked, you can also tell Claude to add that as an event in your calendar to remind yourself of those plans.
218 
219<div align="center">
220  <img src="https://rossshannon.github.io/weekly-weather-mcp/images/calendar-integration-example.png" alt="Calendar event created by Claude" width="365">
221  <p><em>Calendar event created by Claude based on the weather forecast</em></p>
222</div>
223 
224## Troubleshooting
225 
226### API Key Issues
227 
228If you encounter an “Invalid API key” or authorization error:
2291. Make sure you’ve subscribed to the “One Call API 3.0” plan. You’ll need a debit or credit card to enable your account, but you’ll only be charged if you exceed the free tier limit.
2302. Remember that API key activation can take up to an hour
2313. Verify you have set the `OPENWEATHER_API_KEY` correctly in environment variables, or check that you’re providing the correct `api_key` parameter when calling the tools
232 
233### Other Common Issues
234 
235- **“Location not found” error**:
236  - Check for typos in location names
237  - Some very small or remote locations might not be in OpenWeatherMap’s database
238 
239- **Incorrect location returned**:
240  - Try using a more accurate city name or add a country code, e.g., “Beijing,CN” or “Porto,PT”
241  - For US cities with common names, specify the state: “Springfield,IL,US” or “Portland,OR,US”
242  - For cities with the same name in different countries, always include the country code and state if applicable: “Paris,FR” for Paris, France vs “Paris,TX,US” for Paris, Texas, USA.
243 
244- **Rate limiting (429 error)**: You’ve exceeded your API call limit. Check your OpenWeatherMap account settings.
245 
246## Development and Testing
247 
248### Testing
249 
250This project includes unit tests, integration tests, and mock client test files to validate the MCP server functionality. The server has been manually tested to ensure it works correctly with Claude Desktop, Cursor, and other MCP clients.
251 
252#### Manual Client Testing
253 
254Before configuring the server with Claude Desktop or other MCP clients, you can use the included test script to verify your API key and installation:
255 
2561. Set your OpenWeatherMap API key:
257   ```bash
258   export OPENWEATHER_API_KEY="your_api_key"
259   ```
260 
2612. Run the test client:
262   ```bash
263   python3 test_mcp_client.py
264   ```
265 
266The test script directly calls the weather functions to check the current weather in New York and displays the results. This helps verify that:
2671. Your API key is working properly
2682. The OpenWeatherMap API is accessible
2693. The weather data functions are operational
270 
271If the test shows current weather data, you’re ready to configure the server with Claude Desktop, Cursor, or other MCP clients!
272 
273<div align="center">
274  <img src="https://rossshannon.github.io/weekly-weather-mcp/images/weather-mcp-test-client.png" alt="Running local test client" width="800">
275  <p><em>Running local test client to verify API key and installation</em></p>
276</div>
277 
278#### Automated Tests
279 
280The repository includes unit and integration test files that:
281- Test API key handling and validation
282- Validate data parsing and formatting
283- Verify error handling for API failures
284- Test both exposed MCP tools: `get_weather` and `get_current_weather`
285 
286These tests require proper setup of the development environment with all dependencies installed. They’re provided as reference for future development.
287 
288To run the automated tests:
289 
290```bash
291# Run unit tests
292python test_weather_mcp.py
293 
294# Run integration tests
295python test_mcp_integration.py
296```
297 
298The tests use a sample API response (`test_weather_response.json`) to simulate responses from the OpenWeatherMap API, so they can be run without an API key or internet connection.
299 
300These tests are provided as reference for future development and to ensure the MCP server continues to function correctly after any modifications.
301 
302## Credits
303 
304This project is adapted from an original [Weather MCP](https://github.com/Zippland/weather-mcp) by Zippland. The modifications include:
305 
306- Integration with OpenWeatherMap One Call API 3.0
307- Extended forecast data from 2 days to 8 days (today + 7 days)
308- Addition of morning, afternoon and evening data points for each day
309- Hourly forecasts for the next 48 hours
310- Inclusion of weather summaries, wind speed, and precipitation probabilities
311- Unit tests, integration tests, and mock client test files
312