# Weather MCP Server 🌤️

A Model Context Protocol (MCP) server that provides real-time weather information for any city using the Open-Meteo API.

## Features

- 🌍 Get current weather for any city worldwide
- 🌡️ Returns temperature in Celsius
- 💨 Provides wind speed in km/h
- 📍 Includes geographic coordinates
- 🐳 Fully containerized with Docker
- 🚀 Easy to deploy and use

## Quick Start

### Using Docker (Recommended)

Pull and run the pre-built image from Docker Hub:

```bash
docker pull 125478963/weather-mcp:latest
docker run -d -p 8000:8000 125478963/weather-mcp:latest
```

The server will be available at: `http://localhost:8000/mcp`

### Building from Source

1. Clone this repository:
```bash
git clone https://github.com/rajeevchandra/weather-mcp-docker.git
cd weather-mcp-docker
```

2. Build the Docker image:
```bash
docker build -t weather-mcp .
```

3. Run the container:
```bash
docker run -d -p 8000:8000 weather-mcp
```

## Usage

This MCP server exposes a `weather` tool that can be used by MCP clients like Claude Desktop.

### Available Tool

**`weather(city: str)`**
- Returns current temperature (°C) and wind speed (km/h) for the specified city
- Default city: Philadelphia

### Example Response

```json
{
  "city": "London",
  "latitude": 51.5074,
  "longitude": -0.1278,
  "temperature_c": 15.2,
  "windspeed_kmh": 12.5
}
```

## Configuration

The server runs on:
- **Host**: `0.0.0.0` (accessible from outside the container)
- **Port**: `8000`
- **Endpoint**: `/mcp`

## Using with MCP Clients

### Claude Desktop

Add this to your Claude Desktop MCP settings:

```json
{
  "mcpServers": {
    "weather": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

## Development

### Prerequisites

- Python 3.11+
- Docker (optional, for containerization)

### Local Development

1. Install dependencies:
```bash
pip install -r requirements.txt
```

2. Run the server:
```bash
python server.py
```

### Testing

Run the complete test script to verify the server is working:

```bash
python complete_test.py
```

This will:
1. Initialize a session with the MCP server
2. List available tools
3. Test the weather tool with multiple cities (London, Paris, Tokyo)
4. Display real-time weather data

**Expected Output:**
```
✅ Session initialized successfully!
Server: WeatherMCP
Version: 1.20.0

🌍 Getting weather for London...
   ✅ Success!
      Temperature: 14.2°C
      Wind Speed: 15.3 km/h
```

Or use the quick health check:

```bash
curl http://localhost:8000/mcp
```

## Project Structure

```
weather-mcp/
├── server.py           # Main MCP server implementation
├── requirements.txt    # Python dependencies
├── Dockerfile         # Docker configuration
├── easy_test.py       # Simple test script
└── README.md          # This file
```

## How It Works

1. **Geocoding**: Converts city names to coordinates using Open-Meteo Geocoding API
2. **Weather Data**: Fetches current weather data using Open-Meteo Weather API
3. **MCP Protocol**: Exposes weather data through the Model Context Protocol

## API Credits

This server uses the [Open-Meteo API](https://open-meteo.com/) which is free and requires no API key.

## Docker Hub

Pre-built images are available on Docker Hub:
- Latest: `125478963/weather-mcp:latest`
- Version 1: `125478963/weather-mcp:v1`

[View on Docker Hub](https://hub.docker.com/r/125478963/weather-mcp)

## Troubleshooting

### Server not responding?

Check if the container is running:
```bash
docker ps | grep weather-mcp
```

View logs:
```bash
docker logs <container-id>
```

### Port already in use?

Use a different port:
```bash
docker run -d -p 8080:8000 125478963/weather-mcp:latest
```

## License

MIT License - feel free to use and modify as needed.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please open an issue on GitHub.

---

Made with ❤️ using the Model Context Protocol