# OpenWeather MCP Server

A Model Context Protocol (MCP) server that integrates OpenWeather API with Claude, enabling real-time weather information, forecasts, and air quality data directly in your conversations.

## Features

- 🌤️ **Current Weather**: Get real-time weather conditions for any city
- 📅 **5-Day Forecast**: Detailed weather forecasts with 3-hour intervals
- 📍 **Coordinate-Based Search**: Get weather data using latitude and longitude
- 🌍 **Air Quality Index**: Check pollution levels and air quality data
- 🌡️ **Detailed Metrics**: Temperature, humidity, wind speed, visibility, and more

## Prerequisites

- Node.js v18 or higher
- Claude Desktop
- OpenWeather API key (free tier available)

## Installation

### 1. Get OpenWeather API Key

1. Sign up at [OpenWeather](https://openweathermap.org/)
2. Navigate to "My API keys" in your account
3. Copy your API key (note: new keys take ~2 hours to activate)

### 2. Clone and Setup

```bash
# Clone the repository
git clone https://github.com/MadhurToshniwal/OpenWeather-MCP-server.git
cd OpenWeather-MCP-server

# Install dependencies
npm install

# Build the project
npm run build
```

### 3. Configure Claude Desktop

Edit your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "openweather": {
      "command": "node",
      "args": [
        "/absolute/path/to/openweather-mcp-server/dist/index.js"
      ],
      "env": {
        "OPENWEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**Important for Windows users**: Use double backslashes in paths:
```json
"args": ["C:\\Users\\YourName\\Desktop\\openweather-mcp-server\\dist\\index.js"]
```

### 4. Restart Claude Desktop

Completely quit and restart Claude Desktop for changes to take effect.

## Usage Examples

Once configured, you can ask Claude:

- "What's the weather in Tokyo?"
- "Give me a 5-day forecast for London"
- "What's the weather at coordinates 40.7128, -74.0060?"
- "Check the air quality in Beijing"
- "Compare weather between Mumbai and Delhi"

## Available Tools

### `get_current_weather`
Get current weather conditions for a specific city.

**Parameters:**
- `city` (required): City name
- `country_code` (optional): 2-letter country code (e.g., "US", "GB")

### `get_forecast`
Get 5-day weather forecast with 3-hour intervals.

**Parameters:**
- `city` (required): City name
- `country_code` (optional): 2-letter country code

### `get_weather_by_coordinates`
Get current weather by geographic coordinates.

**Parameters:**
- `latitude` (required): Latitude coordinate
- `longitude` (required): Longitude coordinate

### `get_air_pollution`
Get air quality data for specific coordinates.

**Parameters:**
- `latitude` (required): Latitude coordinate
- `longitude` (required): Longitude coordinate

## API Limits

The free tier of OpenWeather API includes:
- 1,000 API calls per day
- 60 calls per minute
- Current weather data
- 5-day forecast
- Air pollution data

## Project Structure

```
openweather-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── .env                  # Environment variables (not in repo)
├── package.json
├── tsconfig.json
└── README.md
```

## Development

```bash
# Build the project
npm run build

# Run in development mode
npm start
```

## Technologies Used

- **TypeScript**: Type-safe development
- **Model Context Protocol (MCP)**: Claude integration standard
- **OpenWeather API**: Weather data provider
- **Axios**: HTTP client for API requests

## Troubleshooting

### "API key not valid"
- Ensure your API key is correctly set in the configuration
- New API keys take up to 2 hours to activate after signup

### Tools not appearing in Claude
- Verify the path in `claude_desktop_config.json` is correct
- Restart Claude Desktop completely
- Check that the project is built (`dist` folder exists)

### "Cannot find module"
- Run `npm install` to install dependencies
- Ensure Node.js version is 18 or higher

## License

MIT

## Author

Madhur Toshniwal  
📧 madhurtoshniwal03@gmail.com

## Acknowledgments

- OpenWeather API for weather data
- Anthropic for the Model Context Protocol
- Claude Desktop for AI integration

---

**Built for campus placement showcase** | Demonstrates API integration, TypeScript, and modern development practices