Weather MCP Tool for Claude Desktop

1# Weather MCP Tool for Claude Desktop
2 
3An MCP (Model Context Protocol) tool that provides real-time weather data, forecasts, and historical weather information using the OpenWeatherMap API, specifically designed for Claude Desktop.
4 
5## Tutorial
6 
7For a detailed guide on setting up and using this tool, check out our comprehensive Medium tutorial:
8[Tutorial: Using Claude Desktop with Weather MCP Tool to Access Real-Time Weather Data Worldwide](https://medium.com/@saintdoresh/tutorial-using-claude-desktop-with-weather-mcp-tool-to-access-real-time-weather-data-worldwide-a0b811fc5cdf)
9 
10## Features
11 
12- Real-time weather conditions for any location
13- Weather forecasts (up to 5 days)
14- Historical weather data (last 5 days)
15- Air quality information
16- Weather alerts and warnings
17- Location search functionality
18 
19## Setup
20 
211. Ensure you have Python 3.10 or higher installed
22 
232. Install dependencies:
24```bash
25pip install -r requirements.txt
26```
27 
283. Get an API key from [OpenWeatherMap](https://openweathermap.org/api) (free tier available)
29   - Note: New API keys may take up to 24 hours to activate
30 
314. Set up environment variables for API key (recommended method):
32   - Create a `.env` file in the project directory
33   - Add your API key to the file:
34   ```
35   OPENWEATHER_API_KEY=your_openweathermap_api_key
36   ```
37   - Add `.env` to your `.gitignore` file to prevent committing sensitive data
38 
395. Update `main.py` to use the environment variable:
40   ```python
41   # Add these imports at the top
42   import os
43   from dotenv import load_dotenv
44   
45   # Load environment variables
46   load_dotenv()
47   
48   # Replace the API_KEY line with
49   API_KEY = os.getenv("OPENWEATHER_API_KEY")
50   ```
51 
52## Integration with Claude Desktop
53 
541. Configure your MCP settings in Claude Desktop by adding the following to your MCP configuration:
55 
56```json
57{
58  "mcpServers": {
59    "weather-mcp": {
60      "command": "py",
61      "args": ["-3.13", "C:\\Path\\To\\Your\\Weather-MCP-ClaudeDesktop\\main.py"]
62    }
63  }
64}
65```
66 
672. Replace the path with the full path to your main.py file
683. Run the server using:
69```bash
70py -3.13 main.py
71```
724. Keep the server running while using Claude Desktop
73 
74## Available Tools
75 
76### 1. get_current_weather
77Get real-time weather conditions for a location:
78```json
79{
80    "location": {
81        "name": "New York",
82        "country": "US",
83        "lat": 40.7128,
84        "lon": -74.006
85    },
86    "temperature": {
87        "current": 25.6,
88        "feels_like": 26.2,
89        "min": 23.4,
90        "max": 27.8
91    },
92    "weather_condition": {
93        "main": "Clear",
94        "description": "clear sky",
95        "icon": "01d"
96    },
97    "wind": {
98        "speed": 3.6,
99        "deg": 220
100    },
101    "clouds": 5,
102    "humidity": 65,
103    "pressure": 1015,
104    "visibility": 10000,
105    "sunrise": "2025-03-16T06:12:34",
106    "sunset": "2025-03-16T18:04:23",
107    "timestamp": "2025-03-16T14:30:00"
108}
109```
110 
111### 2. get_weather_forecast
112Get weather forecast for a location:
113```json
114{
115    "location": {
116        "name": "London",
117        "country": "GB",
118        "lat": 51.5074,
119        "lon": -0.1278
120    },
121    "forecast": [
122        {
123            "datetime": "2025-03-16T15:00:00",
124            "temperature": {
125                "temp": 18.2,
126                "feels_like": 17.8,
127                "min": 17.5,
128                "max": 19.1
129            },
130            "weather_condition": {
131                "main": "Rain",
132                "description": "light rain",
133                "icon": "10d"
134            },
135            "wind": {
136                "speed": 4.2,
137                "deg": 180
138            },
139            "clouds": 75,
140            "humidity": 82,
141            "pressure": 1010,
142            "visibility": 8000,
143            "pop": 0.4
144        }
145        // ... more forecast items
146    ],
147    "days": 5
148}
149```
150 
151### 3. get_air_quality
152Get air quality data for a location:
153```json
154{
155    "location": {
156        "name": "Beijing",
157        "country": "CN",
158        "lat": 39.9042,
159        "lon": 116.4074
160    },
161    "air_quality_index": 3,
162    "air_quality_level": "Moderate",
163    "components": {
164        "co": 250.34,
165        "no": 0.5,
166        "no2": 15.2,
167        "o3": 140.8,
168        "so2": 5.1,
169        "pm2_5": 8.2,
170        "pm10": 12.3,
171        "nh3": 0.7
172    },
173    "timestamp": "2025-03-16T14:30:00"
174}
175```
176 
177### 4. get_historical_weather
178Get historical weather data for a specific date:
179```json
180{
181    "location": {
182        "name": "Paris",
183        "country": "FR",
184        "lat": 48.8566,
185        "lon": 2.3522
186    },
187    "date": "2025-03-14",
188    "temperature": {
189        "temp": 20.3,
190        "feels_like": 19.8
191    },
192    "weather_condition": {
193        "main": "Clouds",
194        "description": "scattered clouds",
195        "icon": "03d"
196    },
197    "wind": {
198        "speed": 2.8,
199        "deg": 150
200    },
201    "clouds": 45,
202    "humidity": 60,
203    "pressure": 1012,
204    "visibility": 10000,
205    "sunrise": "2025-03-14T06:30:45",
206    "sunset": "2025-03-14T18:15:22",
207    "timestamp": "2025-03-14T12:00:00"
208}
209```
210 
211### 5. search_location
212Search for locations by name:
213```json
214{
215    "results": [
216        {
217            "name": "Tokyo",
218            "state": "",
219            "country": "JP",
220            "lat": 35.6762,
221            "lon": 139.6503
222        },
223        {
224            "name": "Tokyo",
225            "state": "Tokyo",
226            "country": "JP",
227            "lat": 35.6895,
228            "lon": 139.6917
229        }
230        // ... more results
231    ]
232}
233```
234 
235### 6. get_weather_alerts
236Get weather alerts for a location:
237```json
238{
239    "location": {
240        "name": "Miami",
241        "country": "US",
242        "lat": 25.7617,
243        "lon": -80.1918
244    },
245    "alerts": [
246        {
247            "sender": "NWS Miami",
248            "event": "Heat Advisory",
249            "start": "2025-03-16T12:00:00",
250            "end": "2025-03-16T20:00:00",
251            "description": "Heat index values between 105 and 110 expected",
252            "tags": ["Extreme temperature value"]
253        }
254        // ... more alerts if any
255    ],
256    "alert_count": 1
257}
258```
259 
260## Sample Queries
261 
262You can ask Claude Desktop questions like:
263- "What's the current weather in New York?"
264- "Show me the 5-day forecast for London"
265- "What's the air quality like in Beijing today?"
266- "How was the weather in Paris on March 14th?"
267- "Search for locations named 'Tokyo'"
268- "Are there any weather alerts for Miami?"
269- "Compare the current weather in Chicago, Miami, and Seattle"
270- "Show me a comparison of air quality in Beijing, Los Angeles, and Delhi"
271 
272## Error Handling
273 
274All tools include proper error handling and will return an error message if something goes wrong:
275```json
276{
277    "error": "Failed to fetch current weather for InvalidLocation: Location not found"
278}
279```
280 
281## Troubleshooting
282 
283If the MCP server is not working in Claude Desktop:
2841. Make sure the server is running - you should see output when you start the script
2852. Verify the path in your settings is correct and absolute
2863. Make sure Python 3.10+ is in your system PATH
2874. Check that all dependencies are installed
2885. Try restarting Claude Desktop
2896. Check logs for any error messages
290 
291### Common API Issues
292- **API Key Activation**: New OpenWeatherMap API keys may take up to 24 hours to activate
293- **Invalid API Key Error**: If you get a 401 error, verify your API key is correct and active
294- **Rate Limiting**: Free tier allows up to 60 calls per minute, which might be exceeded during heavy usage
295 
296## Rate Limits
297 
298This tool uses the OpenWeatherMap API which has rate limits. The free tier allows up to 60 calls per minute, which should be sufficient for personal use. Please be aware that very frequent requests may be throttled by the API.
299 
300## License
301 
302MIT License