# weather-mcp

**Repository Path**: openminds/weather-mcp

## Basic Information

- **Project Name**: weather-mcp
- **Description**: A Model Context Protocol (MCP) server that provides real-time weather forecasts worldwide using the OpenWeatherMap API.
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: MCP, weather

## README

# Weather MCP Server

A Model Context Protocol (MCP) server that provides real-time weather forecasts worldwide using the [OpenWeatherMap API](https://openweathermap.org/api).

Built with [FastMCP](https://gofastmcp.com) and Python.

## ✨ Features

- 🌍 **Global coverage** - Get weather forecasts for any location worldwide
- 🇨🇳 **China-friendly** - Works reliably in China with domestic APIs
- 🌤️ **5-day forecasts** - Detailed 3-hour interval forecasts
- 🎯 **Natural language queries** - Ask about weather in any city (e.g., "What's the weather in Beijing?")
- 🌡️ **Metric units** - Temperature in Celsius, wind speed in km/h
- 🔌 **Multiple transport modes** - Support for both stdio (local) and HTTP (cloud hosting)
- ☁️ **Cloud-ready** - Deploy to Azure App Service, Railway, or any cloud platform

## 🛠️ Available Tools

| Tool | Description |
|------|-------------|
| `get_weather_forecast` | Returns a formatted 5-day weather forecast for any location worldwide |

## 🚀 Quick Start

### Prerequisites

- Python 3.12 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- OpenWeatherMap API key (free, see [API Configuration Guide](API_CONFIG.md))

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/weather-mcp.git
cd weather-mcp

# Install dependencies
uv sync

# Configure API keys
cp .env.example .env
# Edit .env and add your API keys:
# - OPENWEATHER_API_KEY: Required for weather data
# - AMAP_API_KEY: Optional but recommended for Chinese locations (better accuracy & speed)
```

📖 **Need help getting API keys?** See the detailed [API Configuration Guide](API_CONFIG.md)

### Running Locally

**Stdio Mode** (for use with Copilot CLI):
```bash
uv run python server.py
```

**HTTP Mode** (for cloud deployment or remote access):
```bash
TRANSPORT=streamable-http PORT=8000 uv run python server.py
```

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

## 🔗 Connecting to GitHub Copilot CLI

### Local Connection (Stdio)

1. In Copilot CLI, run `/mcp add`
2. Configure:
   - **Server Name**: `weather`
   - **Server Type**: `2` (STDIO)
   - **Command**: `uv run python /path/to/server.py`
   - **Tools**: `*`

3. Try it: *"What's the weather in Beijing?"*

### Remote Connection (HTTP)

After deploying:
1. Run `/mcp add`
2. Configure:
   - **Server Name**: `weather`
   - **Server Type**: `3` (HTTP)
   - **URL**: `https://your-app.azurewebsites.net/mcp`

## ☁️ Cloud Deployment

### Azure App Service (Quick Deploy)

This project includes a GitHub Actions workflow for automatic deployment.

**Setup Steps:**

1. **Create Azure App Service**
   ```bash
   az webapp up --name <your-app-name> \
     --resource-group weather-mcp-rg \
     --runtime PYTHON:3.12 \
     --sku F1
   ```

2. **Configure Environment**
   ```bash
   az webapp config appsettings set \
     --name <your-app-name> \
     --resource-group weather-mcp-rg \
     --settings TRANSPORT=streamable-http
   ```

3. **Add GitHub Secrets**
   - `AZURE_WEBAPP_NAME`: Your app name
   - `AZURE_WEBAPP_PUBLISH_PROFILE`: From Azure Portal → Get publish profile

4. **Deploy**
   Push to `main` branch. GitHub Actions will deploy automatically.

**Endpoint**: `https://<your-app-name>.azurewebsites.net/mcp`

📖 **For other platforms** (Railway, Render, etc.), see [API_CONFIG.md](API_CONFIG.md).

## 📁 Project Structure

```
weather-mcp/
├── server.py              # Main FastMCP server
├── pyproject.toml         # Project configuration
├── .env                   # API keys (not committed)
├── .env.example           # Configuration template
├── test_server.py         # Unit tests
├── test_client.py         # Integration tests
├── validate_api_keys.py   # API key validator
├── run_tests.sh           # Test runner
└── .github/workflows/
    └── deploy.yml         # CI/CD workflow
```

📖 **Full documentation**: [API_CONFIG.md](API_CONFIG.md) | [TESTING.md](TESTING.md) | [LOCATION_FORMAT.md](LOCATION_FORMAT.md) | [FASTMCP_CLI_GUIDE.md](FASTMCP_CLI_GUIDE.md)

## 🔍 How It Works

1. **Geocoding** - Convert location names to coordinates:
   - Chinese locations: AMap → OpenWeatherMap → Nominatim
   - International: OpenWeatherMap → Nominatim
2. **Weather Data** - Fetch 5-day forecast from OpenWeatherMap API
3. **Formatting** - Return user-friendly output in Celsius with Chinese descriptions

### 🌍 Location Format

Use `"City, Country Code"` format (ISO 3166-1 alpha-2):

```bash
✅ "Beijing, CN" | "New York, US" | "London, GB"
❌ "New York, NY" | "Los Angeles, CA"  # Don't use state codes
```

💡 Chinese cities support both English and Chinese: `"北京"` or `"Beijing, CN"`

📖 **Full guide**: [LOCATION_FORMAT.md](LOCATION_FORMAT.md)

## 📝 Example Usage

Once connected to Copilot CLI, you can ask questions like:

- *"What's the weather in Beijing this week?"*
- *"Will it rain in Shanghai tomorrow?"*
- *"Give me the forecast for Guangzhou, China"*
- *"What's the temperature trend for Shenzhen over the next 5 days?"*
- *"天气怎么样？"* (Works with Chinese queries too!)

## 🧪 Testing

### Quick Start

```bash
# Unit tests (fast, no network)
uv run pytest test_server.py -v

# Integration test (requires API key)
uv run python test_client.py "Beijing, CN"

# FastMCP CLI
uv run fastmcp inspect server.py
uv run fastmcp call server.py get_weather_forecast location="Beijing, CN"
```

📖 **Full guide**: [TESTING.md](TESTING.md) | [FASTMCP_CLI_GUIDE.md](FASTMCP_CLI_GUIDE.md)

## 🤝 Contributing

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

## 📄 License

MIT License - see [LICENSE](LICENSE)

## 🔗 Links

- [API Configuration](API_CONFIG.md)
- [Testing Guide](TESTING.md)
- [Location Format](LOCATION_FORMAT.md)
- [FastMCP CLI](FASTMCP_CLI_GUIDE.md)
- [FastMCP](https://gofastmcp.com) | [OpenWeatherMap](https://openweathermap.org/api) | [MCP Protocol](https://modelcontextprotocol.io)