# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather data using the free Open-Meteo API.

## Features

- **No API Key Required**: Uses the free Open-Meteo API
- **Current Weather**: Get real-time weather conditions for any location
- **Daily Forecast**: Multi-day weather forecasts (up to 16 days)
- **Hourly Forecast**: Detailed hour-by-hour predictions (up to 7 days)
- **Location Search**: Find coordinates for any city worldwide
- **Flexible Units**: Support for metric and imperial units
- **Multiple Formats**: Both human-readable markdown and machine-readable JSON outputs

## Tools

### 1. weather_search_location
Search for a city to get its coordinates.

**Parameters:**
- `city` (str): City name to search
- `count` (int, optional): Maximum number of results (default: 5)
- `response_format` (str, optional): Output format - 'markdown' or 'json' (default: 'markdown')

**Example:**
```python
{
    "city": "London",
    "count": 3
}
```

### 2. weather_get_current
Get current weather conditions for a location.

**Parameters:**
- `latitude` (float): Latitude coordinate (-90 to 90)
- `longitude` (float): Longitude coordinate (-180 to 180)
- `temperature_unit` (str, optional): 'celsius' or 'fahrenheit' (default: 'celsius')
- `wind_speed_unit` (str, optional): 'kmh', 'ms', 'mph', or 'kn' (default: 'kmh')
- `response_format` (str, optional): Output format (default: 'markdown')

**Example:**
```python
{
    "latitude": 51.5074,
    "longitude": -0.1278,
    "temperature_unit": "celsius"
}
```

### 3. weather_get_forecast
Get daily weather forecast for up to 16 days.

**Parameters:**
- `latitude` (float): Latitude coordinate
- `longitude` (float): Longitude coordinate
- `days` (int, optional): Number of forecast days 1-16 (default: 7)
- `temperature_unit` (str, optional): Temperature unit (default: 'celsius')
- `wind_speed_unit` (str, optional): Wind speed unit (default: 'kmh')
- `response_format` (str, optional): Output format (default: 'markdown')

**Example:**
```python
{
    "latitude": 40.7128,
    "longitude": -74.0060,
    "days": 5,
    "temperature_unit": "fahrenheit"
}
```

### 4. weather_get_hourly
Get hourly weather forecast for up to 7 days (168 hours).

**Parameters:**
- `latitude` (float): Latitude coordinate
- `longitude` (float): Longitude coordinate
- `hours` (int, optional): Number of forecast hours 1-168 (default: 24)
- `temperature_unit` (str, optional): Temperature unit (default: 'celsius')
- `wind_speed_unit` (str, optional): Wind speed unit (default: 'kmh')
- `response_format` (str, optional): Output format (default: 'markdown')

**Example:**
```python
{
    "latitude": 35.6762,
    "longitude": 139.6503,
    "hours": 48
}
```

## Installation

### Prerequisites
- Python 3.10 or higher
- pip

### Install Dependencies

```bash
cd weather_mcp
pip install -r requirements.txt
```

## Usage

### Running the Server

The server uses stdio transport for local integration:

```bash
python server.py
```

### Using with Claude Desktop or Other MCP Clients

Add the following to your MCP client configuration:

**For Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/weather_mcp/server.py"]
    }
  }
}
```

**For Claude Code** (`.claude/settings.json`):
```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/path/to/weather_mcp/server.py"]
    }
  }
}
```

### Testing with MCP Inspector

You can test the server using the MCP Inspector:

```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run inspector
npx @modelcontextprotocol/inspector python server.py
```

### Example Client

See [client_example.py](client_example.py) for a complete example of how to use the MCP server programmatically.

```bash
python client_example.py
```

## Example Queries

Here are some example queries you can use with this MCP server:

1. **Find a city and get its weather:**
   ```
   First, search for "Paris" to get coordinates, then get current weather for those coordinates.
   ```

2. **Get a weekly forecast:**
   ```
   Get a 7-day weather forecast for London (51.5074, -0.1278) in Fahrenheit.
   ```

3. **Check hourly conditions:**
   ```
   Get the next 24 hours of weather data for Tokyo (35.6762, 139.6503).
   ```

## API Response Formats

### Markdown Format (Default)
Human-readable format with headers, bullet points, and clear structure. Ideal for display to users.

### JSON Format
Machine-readable structured data. Perfect for programmatic processing or integration with other tools.

## Data Source

This server uses the [Open-Meteo API](https://open-meteo.com/), which provides:
- Free access for non-commercial use
- No API key required
- High-quality weather data from multiple national weather services
- Global coverage

## Architecture

- **FastMCP Framework**: Uses the official MCP Python SDK with FastMCP
- **Pydantic Validation**: All inputs are validated using Pydantic v2 models
- **Async HTTP**: Non-blocking API calls using httpx
- **Type Safety**: Full type hints throughout the codebase
- **Error Handling**: Comprehensive error messages with actionable suggestions

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT License - See LICENSE file for details.

## Acknowledgments

- Weather data provided by [Open-Meteo](https://open-meteo.com/)
- Built with [Model Context Protocol](https://modelcontextprotocol.io/)